How to use Telepresence in Windows

Recently I came across Telepresence. It allow you to quickly replace a deployment in your Kubernetes cluster with some application running on your machine. It means that all requests inside the cluster to the pods of this deployment will actually go to your developer machine. It allows you, for example, to debug your application in real environment. For other use cases please consult with the documentation.

Here I want to show how you can install and use it on your Windows machine.

Prepare Kubernetes cluster

First of all, you'll need some Kubernetes cluster. I use Docker Desktop, but you can use whatever you want. In my cluster there will be only single deployment of Nginx and a single service for it. Here is my YAML file for the deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
    name: nginx-deployment
    labels:
        service: nginx
spec:
    replicas: 1
    selector:
        matchLabels:
            service: nginx
    template:
        metadata:
            labels:
                service: nginx
        spec:
            containers:
                - name: nginx-container
                  image: nginx

And this is the YAML file of my service:

apiVersion: v1
kind: Service
metadata:
    name: nginx-service
    labels:
        service: nginx
spec:
    type: NodePort
    selector:
        service: nginx
    ports:
        - name: http
          port: 80
          targetPort: 80
          nodePort: 31000

I install them into the cluster from one folder with a simple command:

kubectl apply -f .

Now I can contact Nginx at http://localhost:31000:

Install Telepresence

There is a documentation page describing how to install Telepresence. In short words, it says the following. Download the archive with the latest version of Telepresence. Extract it somewhere. Execute install-telepresence.ps1 in PowerShell with administrator rights and elevated execution policy. I wanted to specify a folder to install Telepresence to, so I executed

Set-ExecutionPolicy Bypass -Scope Process
.\install-telepresence.ps1 -Path c:\tools\telepresence

Now Telepresence is installed on our machine. Let's connect it to the Kubernetes cluster.

Connecting to Kubernetes

The documentation says that after installation I must close PowerShell and open a new PowerShell session (with administrator rights, of course). Now we must execute:

telepresence connect

This command installs something into your Kubernetes cluster (your can take a look inside ambassador namespace) and makes everything ready. I think that it somehow uses the usual kubectl command. So make sure you have sufficient rights to install different things into the Kubernetes cluster.

And here I got strange error. It said something like Configured to use 'C:\tools\telepresence\telepresence.exe' but actually using 'c:\tools\telepresence\telepresence.exe'. Really strange thing. Nevertheless, what should we do? Use Cmd instead of PowerShell, of course. In Cmd with administrator rights everything works like a charm.

Replacing a deployment

Now it is time to replace something inside the Kubernetes cluster with something on our developer machine. There is a page in the documentation that is entitled 'Intercept a service in your own environment'. It recommends to use command like this:

telepresence intercept nginx-service --port 5500:http --env-file ./nginx-service-intercept.env

I really thought that we'll replace a Kubernetes service and it'll start routing all traffic into our developer machine. But this is not the case:

telepresence: error: No interceptable deployment, replicaset, or statefulset matching nginx-service found

We must replace a deployment:

telepresence intercept nginx-deployment --port 5500:http --env-file ./nginx-service-intercept.env

Now everything works fine. All requests to the deployment in the cluster will be rerouted to the port 5500 on my developer machine. This command also created a nginx-service-intercept.env file. This file contains values of all environment variables available for the deployment pods in the cluster. You can use them to configure your application on developer machine.

Now when you browse http://localhost:31000 you'll see whatever you provide on port 5500:

Cleaning up

If you want to stop intercepting traffic, execute the following command:

telepresence leave nginx-deployment

To disconnect Telepresence from your cluster use:

telepresence quit

And finally to uninstall Telepresence items from the cluster use:

telepresence uninstall --everything

Conclusion

Telepresence is very interesting and useful technology. Unfortunately it is very unstable for Windows at the moment. I had to uninstall and reinstall Telepresence objects to the cluster several times before it started to work for me. But we must remember that it is still in Developer Preview for Windows now. I'm sure they'll make it work fine.

I hope this short article is useful for you. Good luck!