DocsTelepresence OSSConfiguring intercept using CLI
Configuring intercept using CLI
Specifying a namespace for an intercept
The namespace of the intercepted workload is specified during connect using the --namespace
option.
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
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.
Run telepresence status
to see the list of active intercepts.
Finally, run telepresence leave <name of intercept>
to stop the intercept.
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, there may be 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 example, if you wanted to use the echo-stable
service
when intercepting your workload, your command would look like this:
Intercepting multiple ports
It is possible to intercept more than one service and/or service port that are using the same workload. You do this
by creating more than one intercept that identify the same workload using the --workload
flag.
Let's assume that we have a service multi-echo
with the two ports http
and grpc
. They are both
targeting the same multi-echo
deployment.
Port-forwarding an intercepted container's sidecars
Sidecars are containers that sit in the same pod as an application
container; they usually provide auxiliary functionality to an
application, and can usually be reached at
localhost:${SIDECAR_PORT}
. For example, a common use case for a
sidecar is to proxy requests to a database, your application would
connect to localhost:${SIDECAR_PORT}
, and the sidecar would then
connect to the database, perhaps augmenting the connection with TLS or
authentication.
When intercepting a container that uses sidecars, you might want those
sidecars' ports to be available to your local application at
localhost:${SIDECAR_PORT}
, exactly as they would be if running
in-cluster. Telepresence's --to-pod ${PORT}
flag implements this
behavior, adding port-forwards for the port given.
If there are multiple ports that you need forwarded, simply repeat the
flag (--to-pod=<sidecarPort0> --to-pod=<sidecarPort1>
).
Intercepting headless services
Kubernetes supports creating services without a ClusterIP,
which, when they have a pod selector, serve to provide a DNS record that will directly point to the service's backing pods.
Telepresence supports intercepting these headless
services as it would a regular service with a ClusterIP.
So, for example, if you have the following service:
You can intercept it like any other:
Specifying the intercept traffic target
By default, it's assumed that your local app is reachable on 127.0.0.1
, and intercepted traffic will be sent to that IP
at the port given by --port
. If you wish to change this behavior and send traffic to a different IP address, you can use the --address
parameter
to telepresence intercept
. Say your machine is configured to respond to HTTP requests for an intercept on 172.16.0.19:8080
. You would run this as:
Replacing a running workload
By default, your application keeps running as Telepresence intercepts it, even if it doesn't receive any traffic (or receives only a subset, as with personal intercepts). This can pose a problem for applications that are active even when they're not receiving requests. For instance, if your application consumes from a message queue as soon as it starts up, intercepting it won't stop the pod from consuming from the queue.
To work around this issue, telepresence intercept
allows you to pass in a --replace
flag that will stop every
application container from running on your pod. When you pass in --replace
, Telepresence will restart your application
with a dummy application container that sleeps infinitely, and instead just place a traffic agent to redirect traffic to
your local machine. The application container will be restored as soon as you leave the intercept.
ON THIS PAGE
- Specifying a namespace for an intercept
- Importing environment variables
- Creating an intercept
- Creating an intercept When multiple services match your workload
- Intercepting multiple ports
- Port-forwarding an intercepted container's sidecars
- Intercepting headless services
- Specifying the intercept traffic target
- Replacing a running workload