Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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 installkubectl
locally, use theaz 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 toNew 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.
npm install
- Installs the dependencies.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.
Azure Kubernetes Service