Connect to a remote Kubernetes cluster

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.

Connecting to a remote cluster

In this tutorial you'll see how Telepresence allows you to get transparent access to a remote cluster from a local process. This allows you to use your local tools on your laptop to communicate with processes inside the cluster.

You should start by running a service in the cluster:

Terminal
$ kubectl create deployment myservice --image=datawire/hello-world
$ kubectl expose deployment myservice --port=8000
$ kubectl get service myservice
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
myservice 10.0.0.12 <none> 8000/TCP 1m

It may take a minute or two for the pod running the server to be up and running, depending on how fast your cluster is.

You can now run a local process using Telepresence that can access that service, even though the process is local but the service is running in the Kubernetes cluster:

Terminal
$ telepresence --run curl http://myservice:8000/
Hello, world!

(This will not work if the hello world pod hasn't started yet... if so, try again.)

What's going on:

  1. Telepresence creates a new Deployment, which runs a proxy.
  2. Telepresence runs curl locally in a way that proxies networking through that Deployment.
  3. The DNS lookup and HTTP request done by curl get routed through the proxy and transparently access the cluster... even though curl is running locally.
  4. When curl exits the new Deployment will be cleaned up.

To learn more about what Telepresence proxies you can read the relevant reference documentation.

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.