Debugging services locally using Telepresence

When a build fails in your CI pipeline or a service running in a staging cluster contains a bug, you may need to run the service locally to troubleshoot it properly. However, applications depend on other applications and services on the cluster; for example, a database. Telepresence helps you run your code locally, as a normal local process, and then forwards requests to the Kubernetes cluster. This recipe will show you how to debug services locally while running a local Kubernetes cluster.

Let's perform the following steps to view logs through the various options that are available in Kubernetes:

1. On OSX, install the Telepresence binary using the following command:

$ brew cask install osxfuse
$ brew install datawire/blackbird/telepresence

On Windows, use Ubuntu on the Windows Subsystem for Linux (WSL). Then, on Ubuntu, download and install the Telepresence binary using the following command:

$ curl -s https://packagecloud.io/install/repositories/datawireio/telepresence/script.deb.sh | sudo bash
$ sudo apt install --no-install-recommends telepresence

2. Now, create a deployment of your application. Here, we're using a hello-world example:

$ kubectl run hello-world --image=datawire/hello-world --port=8000

3. Expose the service using an external LoadBalancer and get the service IP:

$ kubectl expose deployment hello-world --type=LoadBalancer --name=hello-world
$ kubectl get service hello-world
NAME        TYPE         CLUSTER-IP     EXTERNAL-IP                                   PORT(S)        AGE
hello-world LoadBalancer 100.71.246.234 a643ea7bc0f0311ea.us-east-1.elb.amazonaws.com 8000:30744/TCP 8s

4. To be able to query the address, store the address in a variable using the following command:

$ export HELLOWORLD=http://$(kubectl get svc hello-world -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'):8000

5. Send a query to the service. This will return a Hello, world! message similar to the following:

$ curl $HELLOWORLD/
Hello, world!

6. Next, we will create a local web service and replace the Kubernetes service hello-world message with the local web server service. First, create a directory and a file to be shared using the HTTP server:

$ mkdir /tmp/local-test && cd /tmp/local-test
$ echo "hello this server runs locally on my laptop" > index.html

7. Create a web server and expose the service through port 8000 using the following command:

$ telepresence --swap-deployment hello-world --expose 8000 \
--run python3 -m http.server 8000 &

...
T: Forwarding remote port 8000 to local port 8000.
T: Guessing that Services IP range is 100.64.0.0/13. Services started after this point will be inaccessible if are outside
T: this range; restart telepresence if you can't access a new Service.
T: Setup complete. Launching your command.
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

The preceding command will start a proxy using the vpn-tcp method. Other methods can be found in the Full list of Telepresence methods link in the See also section. 

When a service is exposed over the network, remember that your computer is exposed to all the risks of running a web server. When you expose a web service using the commands described here, make sure that you don't have any important files in the /tmp/local-test directory that you don't want to expose externally. 

8. Send a query to the service. You will see that queries to the hello-world Service will be forwarded to your local web server:

$ curl $HELLOWORLD/
hello this server runs locally on my laptop

9. To end the local service, use the fg command to bring the background Telepresence job in the current shell environment into the foreground. Then, use the Ctrl + C keys to exit it.