Rapid development with Kubernetes

Install Telepresence with Homebrew/apt/dnf

You will need the following available on your machine:

  • kubectl command line tool (here's the installation instructions).
  • Access to your Kubernetes cluster, with local credentials on your machine. You can test this by running kubectl get pod - if this works you're all set.

OS X

On OS X you can install Telepresence by running the following:

shell
brew install --cask osxfuse
brew install datawire/blackbird/telepresence-legacy

Ubuntu 16.04 or later

Run the following to install Telepresence:

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

If you are running another Debian-based distribution that has Python 3.5 installable as python3, you may be able to use the Ubuntu 16.04 (Xenial) packages. The following works on Linux Mint 18.2 (Sonya) and Debian 9 (Stretch) by forcing the PackageCloud installer to access Xenial packages.

shell
curl -sO https://packagecloud.io/install/repositories/datawireio/telepresence/script.deb.sh
sudo env os=ubuntu dist=xenial bash script.deb.sh
sudo apt install --no-install-recommends telepresence
rm script.deb.sh

A similar approach may work on Debian-based distributions with Python 3.6 by using the Ubuntu 17.10 (Artful) packages.

Fedora 26 or later

Run the following:

shell
curl -s https://packagecloud.io/install/repositories/datawireio/telepresence/script.rpm.sh | sudo bash
sudo dnf install telepresence

If you are running a Fedora-based distribution that has Python 3.6 installable as python3, you may be able to use Fedora packages. See the Ubuntu section above for information on how to invoke the PackageCloud installer script to force OS and distribution.

Arch Linux

Until we have a correct and working AUR package, please install from source. See issue #135 for the latest information.

Windows

See the Windows support documentation.

Install from source

On systems with Python 3.5 or newer, install into /usr/local/share/telepresence and /usr/local/bin by running:

shell
sudo env PREFIX=/usr/local ./install.sh

Install the software from the list of dependencies to finish.

Install into arbitrary locations by setting other environment variables before calling the install script. See the install script for more information. After installation you can safely delete the source code.

Other platforms

Don't see your favorite platform? Let us know and we'll try to add it. Also try installing from source.

Rapid development with Telepresence

Imagine you're developing a new Kubernetes service. Typically the way you'd test is by changing the code, rebuilding the image, pushing the image to a Docker registry, and then redeploying the Kubernetes Deployment. This can be slow.

Or, you can use Telepresence. Telepresence will proxy a remote Deployment to a process running on your machine. That means you can develop locally, editing code as you go, but test your service inside the Kubernetes cluster.

Let's say you're working on the following minimal server, helloworld.py:

python
#!/usr/bin/env python3
from http.server import BaseHTTPRequestHandler, HTTPServer
class RequestHandler(BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'text/plain')
self.end_headers()
self.wfile.write(b"Hello, world!\n")
return
httpd = HTTPServer(('', 8080), RequestHandler)
httpd.serve_forever()

You start a proxy inside your Kubernetes cluster that will forward requests from the cluster to your local process, and in the resulting shell you start the web server:

Terminal
localhost$ telepresence --new-deployment hello-world --expose 8080
localhost$ python3 helloworld.py

This will create a new Deployment and Service named hello-world, which will listen on port 8080 and forward traffic to the process on your machine on port 8080.

You can see this if you start a container inside the Kubernetes cluster and connect to that Service. In a new terminal run:

Terminal
localhost$ kubectl --restart=Never run -i -t --image=alpine console /bin/sh
kubernetes# wget -O - -q http://hello-world:8080/
Hello, world!

Now, switch back to the other terminal, kill helloworld.py and edit it so it returns a different string. For example:

Terminal
localhost$ python3 helloworld.py
^C
localhost$ sed s/Hello/Goodbye/g -i helloworld.py
localhost$ grep Goodbye helloworld.py
self.wfile.write(b"Goodbye, world!\n")
localhost$ python3 helloworld.py

Now that we've restarted our local process with new code, we can send it another query from the other terminal where we have a shell running inside a Kubernetes pod:

Terminal
kubernetes# wget -O - -q http://hello-world:8080/
Goodbye, world!
kubernetes# exit

And there you have it: you edit your code locally, and changes are reflected immediately to clients inside the Kubernetes cluster without having to redeploy, create Docker images, and so on.

Install Telepresence with Homebrew/apt/dnf

You will need the following available on your machine:

  • kubectl command line tool (here's the installation instructions).
  • Access to your Kubernetes cluster, with local credentials on your machine. You can test this by running kubectl get pod - if this works you're all set.

OS X

On OS X you can install Telepresence by running the following:

shell
brew install --cask osxfuse
brew install datawire/blackbird/telepresence-legacy

Ubuntu 16.04 or later

Run the following to install Telepresence:

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

If you are running another Debian-based distribution that has Python 3.5 installable as python3, you may be able to use the Ubuntu 16.04 (Xenial) packages. The following works on Linux Mint 18.2 (Sonya) and Debian 9 (Stretch) by forcing the PackageCloud installer to access Xenial packages.

shell
curl -sO https://packagecloud.io/install/repositories/datawireio/telepresence/script.deb.sh
sudo env os=ubuntu dist=xenial bash script.deb.sh
sudo apt install --no-install-recommends telepresence
rm script.deb.sh

A similar approach may work on Debian-based distributions with Python 3.6 by using the Ubuntu 17.10 (Artful) packages.

Fedora 26 or later

Run the following:

shell
curl -s https://packagecloud.io/install/repositories/datawireio/telepresence/script.rpm.sh | sudo bash
sudo dnf install telepresence

If you are running a Fedora-based distribution that has Python 3.6 installable as python3, you may be able to use Fedora packages. See the Ubuntu section above for information on how to invoke the PackageCloud installer script to force OS and distribution.

Arch Linux

Until we have a correct and working AUR package, please install from source. See issue #135 for the latest information.

Windows

See the Windows support documentation.

Install from source

On systems with Python 3.5 or newer, install into /usr/local/share/telepresence and /usr/local/bin by running:

shell
sudo env PREFIX=/usr/local ./install.sh

Install the software from the list of dependencies to finish.

Install into arbitrary locations by setting other environment variables before calling the install script. See the install script for more information. After installation you can safely delete the source code.

Other platforms

Don't see your favorite platform? Let us know and we'll try to add it. Also try installing from source.

Still have questions? Ask in our Slack chatroom or file an issue on GitHub.