Local Connection to Kubernetes Client Libraries

Author: Guray Yildirim (@gurayyildirim)

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.

Intro

Kubernetes has client libraries in many different languages. It is not rare to have situations that require connecting Kubernetes API from your cluster and getting resources/creating new pods & deployments, ... While the list goes on, Kubernetes provide ServiceAccount objects in its RBAC to fill up this need. Still, development from local computers, testing, and debugging become a pain due to lack of direct access to the cluster API using token.

Using Telepresence, it becomes an easy task to access ServiceAccount token seamlessly with your libraries. Here are the links for jumping:

Java Kubernetes Client

If you are using a Kubernetes client like this one, you need to make sure the client can access service account information. This can be done with the --mount command introduced in Telepresence 0.85.

We need to add the following to the command:

  • --mount /tmp/known Tells Telepresence to mount TELEPRESENCE_ROOT to a known folder
  • -v=/tmp/known/var/run/secrets:/var/run/secrets This is another Docker mounting command to mount the known folder to /var/run/secrets in the local container. The Fabric8 Kubernetes client can find the secrets there as it would inside Kubernetes

So our telepresense.sh file would look like that

telepresence.sh

bash
telepresence --mount /tmp/known --swap-deployment foo --docker-run --rm -v$(pwd):/build -v $HOME/.m2/repository:/m2 -v=/tmp/known/var/run/secrets:/var/run/secrets -p 8080:8080 maven-build:jdk8 mvn -Dmaven.repo.local=/m2 -f /build spring-boot:run

For more details about the mount command check the documentation

Python Kubernetes Client

If you are using a Python Kubernetes client like the officially supported one, you need to make sure the client can access service account information. This can be done with the --mount command introduced in Telepresence 0.85.

We need to add the following to the command:

  • --mount /tmp/known Tells Telepresence to mount TELEPRESENCE_ROOT to a known folder
  • -v=/tmp/known/var/run/secrets:/var/run/secrets This is another Docker mounting command to mount the known folder to /var/run/secrets in the local container. The Kubernetes Python client can find the secrets there as it would inside Kubernetes.

telepresence.sh

bash
telepresence --mount /tmp/known --swap-deployment myapp --docker-run --rm -v$(pwd):/code -v=/tmp/known/var/run/secrets:/var/run/secrets -p 8080:8080 guray/podstatus:1.0

The example is an API which returns list of pods in the desired namespace(if serviceaccount is authorized), to try it from your laptop: curl localhost:8080/pods/default.

How it works?

The container is running on your laptop and gets serviceaccount information like it is on the Kubernetes cluster. Afterwards if authorized, get list of the pods and returns with their status as JSON.

For more details about the mount command check the documentation