DocsTelepresence
2.3
Intercept a service in your own environment
Intercept a service in your own environment
Contents
Prerequisites
You’ll need kubectl
or oc
installed
and set up
(Linux /
macOS /
Windows)
to use a Kubernetes cluster, preferably an empty test cluster. This
document uses kubectl
in all example commands, but OpenShift
users should have no problem substituting in the oc
command instead.
If you have used Telepresence previously, please first reset your Telepresence deployment with:
telepresence uninstall --everything
.
This guide assumes you have a Kubernetes deployment and service accessible publicly by an ingress controller and that you can run a copy of that service on your laptop.
1. Install the Telepresence CLI
GNU/Linux
macOS
2. Test Telepresence
Telepresence connects your local workstation to a remote Kubernetes cluster.
Connect to the cluster:
telepresence connect
Test that Telepresence is working properly by connecting to the Kubernetes API server:
curl -ik https://kubernetes.default
3. Intercept your service
In this section, we will go through the steps required for you to intercept all traffic going to a service in your cluster and route it to your local environment instead.
List the services that you can intercept with
telepresence list
and make sure the one you want to intercept is listed.For example, this would confirm that
example-service
can be intercepted by Telepresence:Get the name of the port you want to intercept on your service:
kubectl get service <service name> --output yaml
.For example, this would show that the port
80
is namedhttp
in theexample-service
:Intercept all traffic going to the service in your cluster:
telepresence intercept <service-name> --port <local-port>[:<remote-port>] --env-file <path-to-env-file>
.- For the
--port
argument, specify the port on which your local instance of your service will be running.- If the service you are intercepting exposes more than one port, specify the one you want to intercept after a colon.
- For the
--env-file
argument, specify the path to a file on which Telepresence should write the environment variables that your service is currently running with. This is going to be useful as we start our service.
For the example below, Telepresence will intercept traffic going to service
example-service
so that requests reaching it on porthttp
in the cluster get routed to8080
on the workstation and write the environment variables of the service to~/example-service-intercept.env
.- For the
Start your local environment using the environment variables retrieved in the previous step.
Here are a few options to pass the environment variables to your local process:
- with
docker run
, provide the path to the file using the--env-file
argument - with JetBrains IDE (IntelliJ, WebStorm, PyCharm, GoLand, etc.) use the EnvFile plugin
- with Visual Studio Code, specify the path to the environment variables file in the
envFile
field of your configuration
- with
Query the environment in which you intercepted a service the way you usually would and see your local instance being invoked.
You can now:
- Make changes on the fly and see them reflected when interacting with your Kubernetes environment.
- Query services only exposed in your cluster's network.
- Set breakpoints in your IDE to investigate bugs.
4. Create a preview URL to only intercept certain requests to your service
When working on a development environment with multiple engineers, you don't want your intercepts to impact your teammates. If you are logged in, then when creating an intercept, by default Telpresence will automatically talk to Ambassador Cloud to generate a preview URL. By doing so, Telepresence can route only the requests coming from that preview URL to your local environment; the rest will be routed to your cluster as usual.
Clean up your previous intercept by removing it:
telepresence leave <service name>
Log in to Ambassador Cloud, a web interface for managing and sharing preview URLs:
If you are in an environment where Telepresence cannot launch a local browser for you to interact with, you will need to pass the
--apikey
flag totelepresence login
.Start the intercept again:
telepresence intercept <service-name> --port <local-port>[:<remote-port>] --env-file <path-to-env-file>
You will be asked for the following information:
Ingress layer 3 address: This would usually be the internal address of your ingress controller in the format
<service name>.namespace
. For example, if you have a serviceambassador-edge-stack
in theambassador
namespace, you would enterambassador-edge-stack.ambassador
.Ingress port: The port on which your ingress controller is listening (often 80 for non-TLS and 443 for TLS).
Ingress TLS encryption: Whether the ingress controller is expecting TLS communication on the specified port.
Ingress layer 5 hostname: If your ingress controller routes traffic based on a domain name (often using the
Host
HTTP header), this is the value you would need to enter here.For the example below, you will create a preview URL that will send traffic to the
ambassador
service in theambassador
namespace on port443
using TLS encryption and setting theHost
HTTP header todev-environment.edgestack.me
:
Start your local service as in the previous step.
Go to the preview URL printed after doing the intercept and see that your local service is processing the request.
Make a request on the URL you would usually query for that environment. The request should not be routed to your laptop.
Normal traffic coming into the cluster through the Ingress (i.e. not coming from the preview URL) will route to services in the cluster like normal.
You can now:
- Make changes on the fly and see them reflected when interacting with your Kubernetes environment.
- Query services only exposed in your cluster's network.
- Set breakpoints in your IDE to investigate bugs.
...and all of this without impacting your teammates!
What's Next?
Collaborating
Use personal intercepts to get specific requests when working with colleagues.
Outbound Sessions
Control what your laptop can reach in the cluster while connected.
Telepresence for Docker Compose
Develop in a hybrid local/cluster environment using Telepresence for Docker Compose.