Teleport

Kubernetes Access Multiple Clusters

Improve

This guide will show you how to use Teleport as an access plane for multiple Kubernetes clusters.

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 9.3.7.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 9.3.7, which you can download by visiting the customer portal.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 9.3.8. To download these tools, visit the Downloads page.
```
tctl version
Teleport v9.3.8 go1.17
tsh version
Teleport v9.3.8 go1.17
```

The Teleport Kubernetes Service running in a Kubernetes cluster, version >= v1.17.0. We will assume that you have already followed Connect a Kubernetes Cluster to Teleport
The jq tool to process JSON output. This is available via common package managers
An additional Kubernetes cluster version >= v1.17.0
Helm >= 3.4.2

Verify that Helm and Kubernetes are installed and up to date.

helm version
version.BuildInfo{Version:"v3.4.2"}
kubectl version
Client Version: version.Info{Major:"1", Minor:"17+"}
Server Version: version.Info{Major:"1", Minor:"17+"}

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Connecting clusters

Teleport can act as an access plane for multiple Kubernetes clusters.

We will assume that the domain of your Teleport cluster is tele.example.com.

Let's start a lightweight agent in another Kubernetes cluster cookie and connect it to tele.example.com.

We will need a join token from tele.example.com:

A trick to save the pod ID in tele.example.com
POD=$(kubectl get pod -l app=teleport-cluster -o jsonpath='{.items[0].metadata.name}')
Create a join token for the cluster cookie to authenticate
TOKEN=$(kubectl exec -ti "${POD?}" -- tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]')
echo $TOKEN

Switch kubectl to the Kubernetes cluster cookie and run:

Add Teleport chart repository
helm repo add teleport https://charts.releases.teleport.dev
Deploy a Kubernetes agent. It dials back to the Teleport cluster tele.example.com.
CLUSTER='cookie'
PROXY='tele.example.com:443'
helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \  --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent

List connected clusters using tsh kube ls and switch between them using tsh kube login:

tsh kube ls
Kube Cluster Name Selected
----------------- --------
cookie
tele.example.com    *
kubeconfig now points to the cookie cluster
tsh kube login cookie
Logged into Kubernetes cluster "cookie"
kubectl command executed on `cookie` but is routed through the `tele.example.com` cluster.
kubectl get pods

Teleport can act as an access plane for multiple Kubernetes clusters.

We will assume that the domain of your Teleport cluster is mytenant.teleport.sh.

Let's start a lightweight agent in another Kubernetes cluster cookie and connect it to mytenant.teleport.sh.

We will need a join token from mytenant.teleport.sh:

Create a join token for the cluster cookie to authenticate
TOKEN=$(tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]')
echo $TOKEN

Switch kubectl to the Kubernetes cluster cookie and run:

Add Teleport chart repository
helm repo add teleport https://charts.releases.teleport.dev
Deploy a Kubernetes agent. It dials back to the Teleport cluster mytenant.teleport.sh.
CLUSTER='cookie'
PROXY='mytenant.teleport.sh'
helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \  --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent

List connected clusters using tsh kube ls and switch between them using tsh kube login:

tsh kube ls
Kube Cluster Name Selected
----------------- --------
cookie
mytenant.teleport.sh    *
kubeconfig now points to the cookie cluster
tsh kube login cookie
Logged into Kubernetes cluster "cookie"
kubectl command executed on `cookie` but is routed through the `mytenant.teleport.sh` cluster.
kubectl get pods

Have a suggestion or can’t find something?

IMPROVE THE DOCS