Share dev environments with preview URLs

Telepresence can generate sharable preview URLs, allowing you to work on a copy of your service locally and share that environment directly with a teammate for pair programming. While using preview URLs Telepresence will route only the requests coming from that preview URL to your local environment; requests to the ingress will be routed to your cluster as usual.

Preview URLs are protected behind authentication via Ambassador Cloud, ensuring that only users in your organization can view them. A preview URL can also be set to allow public access for sharing with outside collaborators.

Prerequisites

• You should have the Telepresence CLI installed on your laptop.

• If you have Telepresence already installed and have used it previously, please first reset it with telepresence uninstall --everything.

• You will need a service running in your cluster that you would like to intercept.

Creating a preview URL

1. List the services that you can intercept with telepresence list and make sure the one you want is listed.

   If it isn't:

   • Only Deployments, ReplicaSets, or StatefulSets are supported, and each of those requires a label matching a Service

   • If the service is in a different namespace, specify it with the --namespace flag

2. Log in to Ambassador Cloud where you can manage and share 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: telepresence intercept <service-name> --port <TCP-port> --env-file <path-to-env-file>

   For --port, 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 --env-file, specify a file path where Telepresence will write the environment variables that are set in the Pod. This is going to be useful as we start our service locally.

   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), enter that value here.

      For the example below, you will create a preview URL for example-service which listens on port 8080. The preview URL for ingress will use the ambassador service in the ambassador namespace on port 443 using TLS encryption and the hostname dev-environment.edgestack.me:

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. Go to the preview URL that was provided after starting the intercept (the next to last line in the terminal output above). Your local service will be processing the request.

   Success! You have intercepted traffic coming from your preview URL without impacting other traffic from your Ingress.
   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.

7. Share with a teammate.

   You can collaborate with teammates by sending your preview URL to them. They will be asked to log in to Ambassador Cloud if they are not already. Upon login they must select the same identity provider and org as you are using; that is how they are authorized to access the preview URL (see the list of supported identity providers). When they visit the preview URL, they will see the intercepted service running on your laptop.

Sharing a preview URL with people outside your team

To collaborate with someone outside of your identity provider's organization, you must go to Ambassador Cloud, navigate to your service's intercepts, select the preview URL details, and click Make Publicly Accessible. Now anyone with the link will have access to the preview URL. When they visit the preview URL, they will see the intercepted service running on your laptop.

To disable sharing the preview URL publicly, click Require Authentication in the dashboard. Removing the preview URL either from the dashboard or by running telepresence preview remove <intercept-name> also removes all access to the preview URL.

Change access restrictions

To collaborate with someone outside of your identity provider's organization, you must make your preview URL publicly accessible.

1. Go to Ambassador Cloud
2. Navigate to the desired service Intercepts page
3. Expand the preview URL details
4. Click Make Publicly Accessible

Now anyone with the link will have access to the preview URL. When they visit the preview URL, they will see the intercepted service running on a local environment.

To disable sharing the preview URL publicly, click Require Authentication in the dashboard.

Remove a preview URL from an Intercept

To delete a preview URL and remove all access to the intercepted service,

1. Go to Ambassador Cloud
2. Navigate to the desired service Intercepts page
3. Expand the preview URL details
4. Click Remove Preview

Alternatively, a preview URL can also be removed by running telepresence preview remove <intercept-name>