Tutorial: Use Telepresence to develop and test microservices locally

2025-01-22

Telepresence is a Cloud Native Computing Foundation (CNCF) Sandbox project created by the team at Ambassador Labs. Telepresence allows developers to run services locally on their development machine while connected to a remote Kubernetes cluster. This setup makes it easier to develop, debug, and test applications that interact with other services in the cluster without having to redeploy or rebuild the entire application in Kubernetes every time changes are made.

Note

Telepresence is an open-source CNCF project. Microsoft doesn't offer support for problems you might have using Telepresence. If you do have problems using Telepresence, visit their Telepresence GitHub issue page and open an issue.

In this tutorial, you connect an AKS cluster to Telepresence and then modify a sample application running locally.

How Telepresence works

Telepresence injects Traffic Agents into the workload pod as a sidecar. The Traffic Agents act as a proxy, rerouting inbound and outbound network traffic from the AKS cluster to your local machine. Then, you can develop and test in your local environment as though your local machine were in the AKS cluster. The process involves:

Connecting to your AKS cluster to Telepresence.
Specifying the service or deployment you want to intercept inbound and outbound traffic for and then reroute to your local environment.
Running the local version of the service. Telepresence connects the local version of the service to the cluster through the proxy pod.

Prerequisites

An AKS cluster. If you don't have a cluster you can use for this tutorial, create one using Tutorial - Create an Azure Kubernetes Service (AKS) cluster.
Kubectl is installed and on the path in command-line environment you use for development. This tutorial uses kubectl to manage the Kubernetes cluster. kubectl is already installed if you use Azure Cloud Shell. To install kubectl locally, use the az aks install-cli command.
Install Node.js LTS. Run the command node --version to verify that Node.js is installed.

Connect to cluster using kubectl

Note

Set the values of $MY_RESOURCE_GROUP_NAME and $MY_AKS_CLUSTER_NAME accordingly.

Before you can install Telepresence and interact with your AKS cluster, make sure you're connected to your cluster. If you didn't install kubectl in the Prerequisites section, do that before continuing.

Configure kubectl to connect to your AKS cluster using the az aks get-credentials command. This command downloads credentials and configures the Kubernetes CLI to use them.
```
az aks get-credentials --resource-group $MY_RESOURCE_GROUP_NAME --name $MY_AKS_CLUSTER_NAME
```
Verify the connection to your cluster using the kubectl cluster-info command. This command displays the name of the cluster so you can confirm you're connected to the cluster you want to work with.
```
kubectl cluster-info
```

Clone the sample app and deploy it your AKS cluster

The aks-store-demo app used in this tutorial is a basic store front app including the following Kubernetes deployments and services:

Store front: Web application for customers to view products and place orders.
Product service: Shows product information.
Order service: Places orders.
Rabbit MQ: Message queue for an order queue.

Use git to clone the sample application to your development environment.
```
git clone https://github.com/Azure-Samples/aks-store-demo.git
```
Change into the cloned directory.
```
cd aks-store-demo
```

Deploy the app to your AKS cluster.

kubectl apply -f aks-store-quickstart.yaml

Install Telepresence

To intercept traffic to and from your AKS cluster, you need to install the Telepresence client on your local machine and the traffic manager to your AKS cluster.

Install the Telepresence client

Choose the OS you're using on your local machine and install that version of Telepresence.

Refer to the Telepresence documentation for installation instructions.

Install the Telepresence traffic manager

To route cloud traffic to your local machine, Telepresence uses a traffic manager. Helm is used to deploy the traffic manager into your Kubernetes cluster.

telepresence helm install

Intercept traffic to your service

Complete the following steps to intercept traffic going to your service in the AKS cluster and route it to your local machine.

From the command line on your local machine, run telepresence connect to connect to your AKS cluster and the Kubernetes API server.
```
telepresence connect
```
A successful response from telepresence connect shows the cluster name and default namespace that Telepresence connected to, similar to the following example.
```
Connected to context myAKSCluster, namespace default (https://myAKSCluster-dns-ck7w5t5h.hcp.eastus2.azmk8s.io:443)
```

Use the telepresence list command to display a list of the services you can intercept.

telepresence list

A successful response displays available services, similar to the following example.

order-service  : ready to intercept (traffic-agent not yet installed)
product-service: ready to intercept (traffic-agent not yet installed)
rabbitmq       : ready to intercept (traffic-agent not yet installed)
store-front    : ready to intercept (traffic-agent not yet installed)

Find the name of the port you need to intercept traffic from using kubectl get service service-name --output yaml. For this tutorial, enter the following command in the command line.
```
kubectl get service store-front -ojsonpath='{.spec.ports[0].port}'
```
In this example, the port to intercept, 80, is returned.
```
80
```
Intercept the traffic from your service in your AKS cluster using the telepresence intercept command with the following format: $ telepresence intercept <service-name> --port <local-port>[:<remote-port>] --env-file <path-to-env-file>
- --port specifies the local port and the remote port for your AKS cluster.
- --env-file specifies the path where Telepresence creates an env file containing the environment variables needed to intercept traffic. This file must exist to properly intercept your service's traffic to your local machine. If a file doesn't exist, telepresence creates it for you.
Note

sshfs is required in order for volume mounts to work correctly during intercepts for both Linux and macOS versions of Telepresence. If you don't have it installed, see the Telepresence documentation for more information.

For this tutorial, enter the following command to intercept the traffic.
```
cd src/store-front
telepresence intercept store-front --port 8080:80 --env-file .env
```
A successful response displays which connections Telepresence is intercepting, similar to the following example.
```
Using Deployment store-front
Intercept name         : store-front
State                  : ACTIVE
Workload kind          : Deployment
Destination            : 127.0.0.1:8080
Service Port Identifier: 80/TCP
Volume Mount Point     : /tmp/telfs-3392425241
Intercepting           : all TCP connections
```

Modify your local code and see real-time changes

With Telepresence configured, you can seamlessly modify your local code and see the changes reflected in real time. This allows you to test and debug locally while leveraging your AKS cluster.

Navigate and open components/TopNav.Vue in the application you cloned previously.

Change the Products navigation item to New Products, as seen in the following example, and save the changes.

<template>
  <nav>
    <div class="logo">
      <router-link to="/">
        <img src="/contoso-pet-store-logo.png" alt="Contoso Pet Store Logo" />
      </router-link>
    </div>
    <button class="hamburger" @click="toggleNav">
      <span class="hamburger-icon"></span>
    </button>
    <ul class="nav-links" :class="{ 'nav-links--open': isNavOpen }">
      <li><router-link to="/" @click="closeNav">Products</router-link></li>
      <li>
        <router-link to="/cart" @click="closeNav">Cart ({{ cartItemCount }})</router-link>
      </li>
    </ul>
  </nav>
</template>

Run the following commands to run the app locally.
1. npm install - Installs the dependencies.
2. npm run serve - Starts the development server.

When you go to the public IP of the store-front service in your AKS cluster, the updated navigation is present and traffic is being routed to your locally running version of the service. Your local changes are reflected in real-time and interact with other services in your AKS cluster.

Video demo

The following video provides a clear and concise walkthrough of Telepresence's F5 debugging capabilities.

Next step

This tutorial explains how to use Telepresence with a sample application on AKS. Telepresence offers more in-depth documentation on their website. Their content covers FAQs, troubleshooting, technical reference, core concepts, tutorials, and links to the community.