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.
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.
- List the services that you can intercept with
telepresence listand make sure the one you want is listed. If it isn't:
- Only Deployments with labels matching a Service are listed.
- If the service is in a different namespace specify the name space with the
Login to Ambassador Cloud where you can manage and share preview URLs:
telepresence login$ telepresence loginLaunching browser authentication flow...<browser opens, login and choose your org>Login successful.
Start the intercept:
telepresence intercept <service-name> --port <TCP-port> --env-file <path-to-env-file>
--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.
--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:
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
ambassadornamespace, you would enter
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
HostHTTP header), enter that value here.
For the example below, you will create a preview URL for
example-servicewhich listens on port 8080. The preview URL for ingress will use the
ambassadorservice in the
ambassadornamespace on port
443using TLS encryption and the hostname
dev-environment.edgestack.me:$ telepresence intercept example-service --port 8080 --env-file ~/ex-svc.envTo create a preview URL, telepresence needs to know how clusteringress works for this service. Please Confirm the ingress to use.1/4: What's your ingress' layer 3 (IP) address?You may use an IP address or a DNS name (this is usually a"service.namespace" DNS name).[default: -]: ambassador.ambassador2/4: What's your ingress' layer 4 address (TCP port number)?[default: -]: 4433/4: Does that TCP port on your ingress use TLS (as opposed to cleartext)?[default: n]: y4/4: If required by your ingress, specify a different layer 5 hostname(TLS-SNI, HTTP "Host" header) to access this service.[default: ambassador.ambassador]: dev-environment.edgestack.meUsing deployment example-serviceinterceptedIntercept name : example-serviceState : ACTIVEDestination : 127.0.0.1:8080Service Port Identifier: httpIntercepting : HTTP requests that match all of:header("x-telepresence-intercept-id") ~= regexp("<intercept-id>:example-service")Preview URL : https://<random-domain-name>.preview.edgestack.meLayer 5 Hostname : dev-environment.edgestack.me
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:
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.
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.
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 log in 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.
To collaborate with someone outside of your identity provider's organization, you must go to Ambassador Cloud, select the preview URL, 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 intercept either from the dashboard or by running
telepresence leave <service-name> also removes all access to the preview URL.