Docs
Telepresence2.4Telepresence Quick Start
Telepresence Quick Start
Contents
In this guide, we'll give you a hands-on tutorial with Telepresence. To go through this tutorial, the only thing you'll need is a computer that runs Docker Desktop >=20.10.7. We'll give you a pre-configured remote Kubernetes cluster and a Docker container to run locally.
If you don't have Docker Desktop already installed, go to the Docker download page and install Docker.
1. Get a free remote cluster
Telepresence connects your local workstation with a remote Kubernetes cluster. In this tutorial, we'll start with a pre-configured, remote cluster.
- Get a Free Remote Cluster
Sign in to Ambassador Cloud to activate your demo cluster. - Go to the Service Catalog to see all the services deployed on your cluster.The Service Catalog gives you a consolidated view of all your services across development, staging, and production. After exploring the Service Catalog, continue with this tutorial to test the application in your demo cluster.
2. Try the Emojivoto application
The remote cluster is running the Emojivoto application, which consists of four services. Test out the application:
Go to the remote demo cluster and vote for some emojis.
Now, click on the 🍩 emoji. You'll see that a bug is present, and voting 🍩 doesn't work. We're going to use Telepresence shortly to fix this bug, as everyone should be able to vote for 🍩!
3. Set up your local development environment
We'll set up a development environment locally on your workstation. We'll then use Telepresence to connect this local development environment to the remote Kubernetes cluster. To save time, the development environment we'll use is pre-packaged as a Docker container.
- Run the Docker container locally, by running this command inside your local terminal:
GNU/Linux
macOS
Windows
The Docker container includes a copy of the Emojivoto application that fixes the bug. Visit the leaderboard and notice how it is different from the leaderboard in your Kubernetes cluster.
Vote for 🍩 on your local leaderboard, and you can see that the bug is fixed!
4. Testing our fix
A common use case for Telepresence is to connect your local development environment to a remote cluster. This way, if your application is too big or complex to run locally, you can still develop locally. In this Quick Start, we're also going to show Telepresence can be used for integration testing, by testing our fix against the services in the remote cluster.
From your Docker container, create an intercept, which will tell Telepresence to send traffic to the service in your container instead of the service in the cluster:
telepresence intercept web --port 8080When prompted for ingress configuration, all default values should be correct as displayed below.
5. Preview URLs
Preview URLs enable you to safely share your development environment with anyone. For example, you may want your UX designer to take a quick look at what you're developing, before you commit the code. Preview URLs enable this easy collaboration.
If you access the Emojivoto application on your remote cluster and vote for the 🍩 emoji, you'll see the bug is still present.
Vote for the 🍩 emoji using the Preview URL obtained in the previous step, and you will see that the bug is fixed, since traffic is being routed to the fixed version running locally.
6. How/Why does this all work?
Telepresence works by deploying a two-way network proxy in a pod running in a Kubernetes cluster. This proxy can intercept traffic meant for the service and reroute it to a local copy, which is ready for further (local) development.
Intercepts and preview URLs are functions of Telepresence that enable easy local development from a remote Kubernetes cluster and offer a preview environment for sharing and real-time collaboration.
Telepresence also uses custom headers and header propagation for controllable intercepts and preview URLs. The headers facilitate the smart routing of requests either to live services in the cluster or services running locally on a developer’s machine.
Preview URLs, when created, generate an ingress request containing a custom header with a token (the context). Telepresence sends this token to Ambassador Cloud with other information about the preview. Visiting the preview URL directs the user to Ambassador Cloud, which proxies the user to the cluster ingress with the token header injected into the request. The request carrying the header is routed in the cluster to the appropriate pod (the propagation). The Traffic Agent on the service pod sees the header and intercepts the request, redirecting it to the local developer machine that ran the intercept.
What's Next?
Apply what you've learned from this guide and employ the Emojivoto application in your own local development environment. See the Creating a local Kubernetes development environment pages for Golang and Java page to learn more.