Configuring intercept using specifications

This page references the different options available to the telepresence intercept specification.

With telepresence, you can provide a file to define how an intercept should work.

Templating

The intercept specification supports template expansion in all properties except names that references other objects within the specification, and makes all functions from the Masterminds/sprig package available. Here's an example showing how to provide Header value created from two environment variables:

Telepresence also provides its own set of properties. Currently limited to:

Root

Your intercept specification is where you can create a standard, easy to use, configuration to easily run pre and post tasks, start an intercept, and start your local application to handle the intercepted traffic.

There are many ways to configure your specification to suit your needs, the table below shows the possible options within your specifcation, and you can see the spec's schema, with all available options and formats, here.

Name

The name is optional. If you don't specify the name it will use the filename of the specification file.

Connection

The connections option defines how Telepresence establishes connections to a cluster. Connections established during the execution of an intercept specification will be temporary and terminate with the completion of the spec, while pre-existing connections are discovered and retained for future use.

A connection can be declared in singular form as:

or, when more than one connection is necessary, in plural form as:

When multiple connections are used, all intercept handlers must run in docker and all connections must have a name.

You can pass the most common parameters from telepresence connect command (telepresence connect --help) using a camel case format.

Some commonly used options:

Handlers

A handler is code running locally.

It can receive traffic for an intercepted service, or can set up prerequisites to run before/after the intercept itself.

When it is intended as an intercept handler (i.e. to handle traffic), it's usually the service you're working on, or another dependency (database, another third party service, ...) running on your machine. A handler can be a Docker container, or an application running natively.

The sample below is creating an intercept handler, giving it the name echo-server and using a docker container. The container will automatically have access to the ports, environment, and mounted directories of the intercepted container.

If you don't want to use Docker containers, you can still configure your handlers to start via a regular script. The snippet below shows how to create a handler called echo-server that sets an environment variable of PORT=8080 and starts the application.

If you prefer not to utilize Docker containers or scripts but still wish to harness all the essential data (including volumes and environment variables) to initiate a process that can manage intercepted traffic directed towards a specified output without actually executing anything, the solution lies in setting up an external handler.

The following snippet illustrates how to establish such a handler, dubbed "echo-server." This configuration not only sets an environment variable defined as PORT=8080, but also generates a file encompassing all pertinent metadata.

Keep in mind that an empty handler is still a valid handler. This is sometimes useful when you want to, for example, simulate an intercepted service going down:

The table belows defines the parameters that can be used within the handlers section.

Script

The handler's script element defines the parameters:

Docker

The handler's docker element defines the parameters. The build and image parameters are mutually exclusive:

External

The handler's external element defines the parameters:

Build

The docker build element defines the parameters:

For additional informations on these parameters, please check the docker documentation.

Compose

The Docker Compose element defines the way to integrate with the tool of the same name.

Service

The service describe how to integrate with each service from your Docker Compose file, and can be seen as an override functionality. A service is normally not provided when you want to keep the original behavior, but can be provided for documentation purposes using the local behavior.

A service can be declared either as a property of compose in the Intercept Specification, or as an x-telepresence extension in the Docker compose specification. The syntax is the same in both cases, but the name property must not be used together with x-telepresence because it is implicit.

Behavior

Mapping

Examples

Considering the following Docker Compose file:

This will use the myapp service as the interceptor.

Due to the possibility of multiple workloads using different connections utilizing the same compose-handler, the services designated as interceptHandler within the compose-spec may operate on distinct connections. When this is the case, the connection must be explicitly specified within each service.

This will prevent the service from running locally. DNS will point the service in the cluster with the same name.

Adding a mapping allows to select the cluster service more accurately, here by indicating to Telepresence that the postgres service should be mapped to the psql service in the big-data namespace.

As an alternative, the services can instead be added as x-telepresence extensions in the docker compose file:

Prerequisites

When creating an intercept specification there is an option to include prerequisites.

Prerequisites give you the ability to run scripts for setup, build binaries to run as your intercept handler, or many other use cases.

Prerequisites is an array, so it can handle many options prior to starting your intercept and running your intercept handlers. The elements of the prerequisites array correspond to handlers.

The sample below is declaring that build-binary and rm-binary are two handlers; the first will be run before any intercepts, the second will be run after cleaning up the intercepts.

If a prerequisite create succeeds, the corresponding delete is guaranteed to run even if the other steps in the spec fail.

The table below defines the parameters availble within the prerequistes section.

Workloads

Workloads define the services in your cluster that will be intercepted.

The example below is creating an intercept on a service called echo-server on port 8080. It creates a personal intercept with the header of x-intercept-id: foo, and routes its traffic to a handler called echo-server

When multiple connections are used, the name of the workload must be prefixed with the name of the connection and a slash. Like this:

This table defines the parameters available within a workload.

Intercepts

This table defines the parameters available for each intercept.

PreviewURL

You can configure the preview URL using these fields:

Header

You can define headers to filter the requests which should end up on your machine when intercepting.

Usage

Running your specification from the CLI

After you've written your intercept specification you will want to run it.

To start your intercept, use this command:

This will validate and run your spec. In case you just want to validate it, you can do so by using this command:

Using and sharing your specification as a CRD

If you want to share specifications across your team or your organization. You can save specifications as CRDs inside your cluster.

1. Install CRD object in your cluster (one time installation) :

2. Then you need to deploy the specification in your cluster as a CRD:

   So echo-server example looks like this:

   Then every person that is connected to the cluster can start your intercept by using this command:

   You can also list available specifications:

Docker integration

Intercept specification can be used within the docker extension if you are using a YAML file and a docker runtime as handlers.

IDE Integration

You can integrate our JSON schemas into your IDE to give you autocompletion and hints while writing your intercept specification. There are two schemas available :

• one for YAML specification
• one for CRD specification

To then add the schema to your IDE follow the instructions for you given IDE, a few popular our listed below: VSCode GoLand