Intercepts

Intercept behavior when logged into Ambassador Cloud

After logging into Ambassador Cloud (with telepresence login), Telepresence will default to --preview-url=true, which will use Ambassador Cloud to create a sharable preview URL for this intercept. (Creating an intercept without logging in will default to --preview-url=false).

In order to do this, it will prompt you for four options. For the first, Ingress, Telepresence tries to intelligently determine the ingress controller deployment and namespace for you. If they are correct, you can hit enter to accept the defaults. Set the next two options, TLS and Port, appropriately based on your ingress service. The fourth is a hostname for the service, if required by your ingress.

Also because you're logged in, Telepresence will default to --mechanism=http --http-match=auto (or just --http-match=auto; --http-match implies --mechanism=http). If you hadn't been logged in it would have defaulted to --mechanism=tcp. This tells it to do smart intercepts and only intercept a subset of HTTP requests, rather than just intercepting the entirety of all TCP connections. This is important for working in a shared cluster with teammates, and is important for the preview URL functionality. See telepresence intercept --help for information on using --http-match to customize which requests it intercepts.

Supported workloads

Kubernetes has various workloads. Currently, telepresence supports intercepting Deployments, ReplicaSets, and StatefulSets.

Specifying a namespace for an intercept

The namespace of the intercepted workload is specified using the --namespace option. When this option is used, and --workload is not used, then the given name is interpreted as the name of the workload and the name of the intercept will be constructed from that name and the namespace.

This will intercept a workload named hello and name the intercept hello-myns. In order to remove the intercept, you will need to run telepresence leave hello-mydns instead of just telepresence leave hello.

The name of the intercept will be left unchanged if the workload is specified.

This will intercept a workload named hello and name the intercept myhello.

Importing environment variables

Telepresence can import the environment variables from the pod that is being intercepted, see this doc for more details.

Creating an intercept Without a preview URL

If you are not logged into Ambassador Cloud, the following command will intercept all traffic bound to the service and proxy it to your laptop. This includes traffic coming through your ingress controller, so use this option carefully as to not disrupt production environments.

If you are logged into Ambassador Cloud, setting the preview-url flag to false is necessary.

This will output a header that you can set on your request for that traffic to be intercepted:

Run telepresence status to see the list of active intercepts.

Finally, run telepresence leave <name of intercept> to stop the intercept.

Creating an intercept when a service has multiple ports

If you are trying to intercept a service that has multiple ports, you need to tell telepresence which service port you are trying to intercept. To specify, you can either use the name of the service port or the port number itself. To see which options might be available to you and your service, use kubectl to describe your service or look in the object's YAML. For more information on multiple ports, see the Kubernetes documentation.

When intercepting a service that has multiple ports, the name of the service port that has been intercepted is also listed.

If you want to change which port has been intercepted, you can create a new intercept the same way you did above and it will change which service port is being intercepted.

Creating an intercept When multiple services match your workload

Oftentimes, there's a 1-to-1 relationship between a service and a workload, so telepresence is able to auto-detect which service it should intercept based on the workload you are trying to intercept. But if you use something like Argo, it uses two services (that use the same labels) to manage traffic between a canary and a stable service.

Fortunately, if you know which service you want to use when intercepting a workload, you can use the --service flag. So in the aforementioned demo, if you wanted to use the echo-stable service when intercepting your workload, your command would look like this: