Fork me on GitHub

Connect Kubernetes Cluster to Teleport


This guide works for Open Source and Enterprise, self-hosted or cloud-hosted editions of Teleport.


  • Installed and running Teleport cluster, self-hosted or cloud-hosted.
  • Tool jq to process JSON output.

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+"}

Verify that your Teleport client is connected:

$ tctl status

# Cluster
# Version  8.0.7
# CA pin   sha256:sha-hash-here

To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:

$ tsh login
$ tctl status
Enable Kubernetes for Self-Hosted

For self-hosted Teleport instances the kube_listen_addr setting in the proxy_service is required to enable Kubernetes Access. This is already enabled for Cloud and the Teleport teleport-cluster helm chart.

  # ...


Deployment overview

In this guide, we deploy a Teleport agent that connects kubernetes cluster cookie to Teleport cluster

Kubernetes agent

Step 1/2. Get a join token

Start a lightweight agent in your Kubernetes cluster cookie and connect it to We would need a join token from

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

Step 2/2. Deploy teleport-kube-agent

Switch kubectl to the Kubernetes cluster cookie and run:

Add teleport-agent chart to charts repository

helm repo add teleport
helm repo update

Install Kubernetes agent. It dials back to the Teleport cluster

PROXY=' - replace me with your cluster'
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

----------------- --------


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 `` cluster.

kubectl get pods

Next Steps

Have a suggestion or can’t find something?