Telepresence Quick Start

In this guide you will explore some of the key features of Telepresence. First, you will install the Telepresence CLI and set up a test cluster with a demo web app. Then, you will run one of the app's services on your laptop, using Telepresence to intercept requests to the service on the cluster and see your changes live via a preview URL.

Prerequisites

It is recommended to use an empty development cluster for this guide. You must have access via RBAC to create and update deployments and services in the cluster. You must also have Node.js installed on your laptop to run the demo app code.

Finally, you will need the Telepresence CLI. Run the commands for your OS to install it and login to Ambassador Cloud in your browser. Follow the prompts to login with GitHub then select your organization. You will be redirected to the dashboard; later you will manage your preview URLs here.

macOS

Linux

Cluster Setup

1. You will use a sample Java app for this guide. Later, after deploying the app into your cluster, we will review its architecture. Start by cloning the repo:

2. Install Edge Stack to use as an ingress controller for your cluster. We need an ingress controller to allow access to the web app from the internet.

   Change into the repo directory, then into k8s-config, and apply the YAML files to deploy Edge Stack.

3. Install the web app by applying its manifest:

4. Wait a few moments for the external load balancer to become available, then retrieve its IP address:

Wait until all the pods start, then access the the Edgy Corp web app in your browser at http://<load-balancer-ip/>. Be sure you use http, not https! You should see the landing page for the web app with an architecture diagram. The web app is composed of three services, with the frontend VeryLargeJavaService dependent on the two backend services.

Developing with Telepresence

Now that your app is all wired up you're ready to start doing development work with Telepresence. Imagine you are a Java developer and first on your to-do list for the day is a change on the DataProcessingNodeService. One thing this service does is set the color for the title and a pod in the diagram. The production version of the app on the cluster uses green elements, but you want to see a version with these elements set to blue.

The DataProcessingNodeService service is dependent on the VeryLargeJavaService and VeryLargeDataStore services to run. Local development would require one of the two following setups, neither of which is ideal.

First, you could run the two dependent services on your laptop. However, as their names suggest, they are too large to run locally. This option also doesn't scale well. Two services isn't a lot to manage, but more complex apps requiring many more dependencies is not feasible to manage running on your laptop.

Second, you could run everything in a development cluster. However, the cycle of writing code then waiting on containers to build and deploy is incredibly disruptive. The lengthening of the inner dev loop in this way can have a significant impact on developer productivity.

Intercepting a Service

Alternatively, you can use Telepresence's intercept command to proxy traffic bound for a service to your laptop. This will let you test and debug services on code running locally without needing to run dependent services or redeploy code updates to your cluster on every change. It also will generate a preview URL, which loads your web app from the cluster ingress but with requests to the intercepted service proxied to your laptop.

1. You started this guide by installing the Telepresence CLI and logging into Ambassador Cloud. The Cloud dashboard is used to manage your intercepts and share them with colleagues. You must be logged in to create selective intercepts as we are going to do here.

   Run telepresence dashboard if you are already logged in and just need to reopen the dashboard.

2. In your terminal and run telepresence list. This will connect to your cluster, install the Traffic Manager to proxy the traffic, and return a list of services that Telepresence is able to intercept.

3. Navigate up one directory to the root of the repo then into DataProcessingNodeService. Install the Node.js dependencies and start the app passing the blue argument, which is used by the app to set the title and pod color in the diagram you saw earlier.

4. In a new terminal window start the intercept with the command below. This will proxy requests to the DataProcessingNodeService service to your laptop. It will also generate a preview URL, which will let you view the app with the intercepted service in your browser.

   The intercept requires you specify the name of the deployment to be intercepted and the port to proxy.

   You will be prompted with a few options. Telepresence tries to intelligently determine the deployment and namespace of your ingress controller. Hit enter to accept the default value of ambassador.ambassador for Ingress. For simplicity's sake, our app uses 80 for the port and does not use TLS, so use those options when prompted for the port and TLS settings. Your output should be similar to this:

Open the preview URL in your browser to see the intercepted version of the app. The Node server on your laptop replies back to the cluster with the blue option enabled; you will see a blue title and blue pod in the diagram. Remember that previously these elements were green. You will also see a banner at the bottom on the page informing that you are viewing a preview URL with your name and org name.

Switch back in your browser to the dashboard page and refresh it to see your preview URL listed. Click the box to expand out options where you can disable authentication or remove the preview. If there were other developers in your organization also creating preview URLs, you would see them here as well.

This diagram demonstrates the flow of requests using the intercept. The laptop on the left visits the preview URL, the request is redirected to the cluster ingress, and requests to and from the DataProcessingNodeService by other pods are proxied to the developer laptop running Telepresence.

7. Clean up your environment by first typing Ctrl+C in the terminal running Node. Then stop the intercept with the leave command and quit to stop the daemon. Finally, use uninstall --everything to remove the Traffic Manager and Agents from your cluster.

8. Refresh the dashboard page again and you will see the intercept was removed after running the leave command. Refresh the browser tab with the preview URL and you will see that it has been disabled.

What's Next?

Telepresence and preview URLS open up powerful possibilities for collaborating with your colleagues and others outside of your organization.

Learn more about how Telepresence handles outbound sessions, allowing locally running services to interact with cluster services without an intercept.

Read the FAQs to learn more about uses cases and the technical implementation of Telepresence.