Intercept a service in your own environment

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

2. Test Telepresence

Telepresence connects your local workstation to a remote Kubernetes cluster.

1. Connect to the cluster: telepresence connect

   macOS users: If you receive an error when running Telepresence that the developer cannot be verified, open
   System Preferences → Security & Privacy → General.
   Click Open Anyway at the bottom to bypass the security block. Then retry the telepresence connect command.

2. Test that Telepresence is working properly by connecting to the Kubernetes API server: curl -ik https://kubernetes.default

   Didn't work? Make sure you are using Telepresence 2.0.3 or greater, check with telepresence version and upgrade here if needed.
   The 401 response is expected. What's important is that you were able to contact the API.

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.

1. 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:

2. 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 named http in the example-service:

3. 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 port http in the cluster get routed to 8080 on the workstation and write the environment variables of the service to ~/example-service-intercept.env.

4. 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

5. Query the environment in which you intercepted a service the way you usually would and see your local instance being invoked.

   Didn't work? Make sure the port you're listening on matches the one specified when creating your intercept.

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.

1. Clean up your previous intercept by removing it: telepresence leave <service name>

2. 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 to telepresence login.

3. 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:

   1. 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 service ambassador-edge-stack in the ambassador namespace, you would enter ambassador-edge-stack.ambassador.

   2. Ingress port: The port on which your ingress controller is listening (often 80 for non-TLS and 443 for TLS).

   3. Ingress TLS encryption: Whether the ingress controller is expecting TLS communication on the specified port.

   4. 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.

      Telepresence supports any ingress controller, not just Ambassador Edge Stack.

      For the example below, you will create a preview URL that will send traffic to the ambassador service in the ambassador namespace on port 443 using TLS encryption and setting the Host HTTP header to dev-environment.edgestack.me:

4. Start your local service as in the previous step.

5. Go to the preview URL printed after doing the intercept and see that your local service is processing the request.

   Didn't work? It might be because you have services in between your ingress controller and the service you are intercepting that do not propagate the x-telepresence-intercept-id HTTP Header. Read more on context propagation.

6. 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?