Telepresence Quick Start

In this guide we'll give you everything you need in a preconfigured demo cluster: the Telepresence CLI, a config file for connecting to your demo cluster, and code to run a cluster service locally.

1. Download the demo cluster archive

1. Sign in to Ambassador Cloud to download your demo cluster archive. The archive contains all the tools and configurations you need to complete this guide.

2. Extract the archive file, open the ambassador-demo-cluster folder, and run the installer script (the commands below might vary based on where your browser saves downloaded files).

   This step will also install some dependency packages onto your laptop using npm, you can see those packages at ambassador-demo-cluster/edgey-corp-nodejs/DataProcessingService/package.json.

3. The demo cluster we provided already has a demo app running. List the app's services: kubectl get services

4. Confirm that the Telepresence CLI is now installed, we expect to see that the daemons are not yet running: telepresence status

   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 status command.

2. Test Telepresence

Telepresence connects your local workstation to a remote Kubernetes cluster.

1. Connect to the cluster (this requires root privileges and will ask for your password): telepresence connect

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. Check out the sample application

Your local workstation may not have the compute or memory resources necessary to run all the services in a multi-service application. In this example, we’ll show you how Telepresence can give you a fast development loop, even in this situation.

We'll use a sample app that is already installed in your demo cluster. Let's take a quick look at it's architecture before continuing.

1. Use kubectl get pods to check the status of your pods:

2. Since you’ve already connected Telepresence to your cluster, you can access the frontend service in your browser at http://verylargejavaservice.default:8080.

3. You should see the EdgyCorp WebApp with a green title and green pod in the diagram.

4. Run a service on your laptop

Now start up the DataProcessingService service on your laptop. This version of the code has the UI color set to blue instead of green.

1. In a new terminal window, go the demo application directory in the extracted archive folder: cd edgey-corp-nodejs/DataProcessingService

2. Start the application: npm start

3. Back in your previous terminal window, curl the service running locally to confirm it’s set to blue: curl localhost:3000/color

5. Intercept all traffic to the service

Next, we’ll create an intercept. An intercept is a rule that tells Telepresence where to send traffic. In this example, we will send all traffic destined for the DataProcessingService to the version of the DataProcessingService running locally instead:

1. Start the intercept with the intercept command, setting the service name and port: telepresence intercept dataprocessingservice --port 3000

   Didn't work? Make sure you are working in the terminal window where you ran the script because it sets environment variables to access the demo cluster. Those variables will only will apply to that terminal session.

2. Go to the frontend service again in your browser at http://verylargejavaservice:8080. You will now see the blue elements in the app.

6. Make a code change

We’ve now set up a local development environment for the DataProcessingService, and we’ve created an intercept that sends traffic in the cluster to our local environment. We can now combine these two concepts to show how we can quickly make and test changes.

1. Open edgey-corp-nodejs/DataProcessingService/app.js in your editor and change line 6 from blue to orange. Save the file and the Node server will auto reload.

2. Now visit http://verylargejavaservice:8080 again in your browser. You will now see the orange elements in the application. The frontend verylargejavaservice is still running on the cluster, but it's request to the DataProcessingService for retrieve the color to show is being proxied by Telepresence to your laptop.

7. Create a Preview URL

Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.

1. Clean up your previous intercept by removing it: telepresence leave dataprocessingservice

2. Login to Ambassador Cloud, a web interface for managing and sharing preview URLs: telepresence login

   This opens your browser; login with your preferred identity provider and choose your org.

3. Start the intercept again: telepresence intercept dataprocessingservice --port 3000

   You will be asked for your ingress layer 3 address; specify the front end service: verylargejavaservice.default Then when asked for the port, type 8080, for "use TLS", type n. The default for the fourth value is correct so hit enter to accept it

4. Wait a moment for the intercept to start; it will also output a preview URL. Go to this URL in your browser, it will be the orange version of the app.

5. Now go again to http://verylargejavaservice:8080, it’s still green.

Normal traffic coming to your app gets the green cluster service, but traffic coming from the preview URL goes to your laptop and gets the orange local service!

What's Next?