Fork me on GitHub
Teleport

Connect a Kubernetes Cluster to Teleport

Improve

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 jq tool to process JSON output. This is available via common package managers.

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.

Deployment overview

In this guide, we deploy the Teleport Kubernetes Service, which connects Kubernetes cluster cookie to Teleport cluster tele.example.com:

In your Teleport Cloud account, the name of your cluster will be your tenant domain name, e.g., mytenant.teleport.sh, rather than teleport.example.com.

Kubernetes agent

Step 1/3. Get a join token

In order to start the Teleport Kubernetes Service, we will need to request a join token from the Teleport Auth Service:

Create a join token for the Teleport Kubernetes Service to authenticate

TOKEN=$(tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]')
echo $TOKEN

Step 2/3. Deploy teleport-kube-agent

The Teleport agent version should be the same as the Teleport Cluster version or up to one major version back. You can set the version override with the override variable, ex: --set teleportVersionOverride=9.3.7.

Switch kubectl to the Kubernetes cluster cookie and run the following commands, assigning PROXY_ADDR to the address of your Auth Service or Proxy Service.

Add teleport-agent chart to charts repository

PROXY_ADDR=tele.example.com:443
helm repo add teleport https://charts.releases.teleport.dev
helm repo update

Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR

CLUSTER='cookie'
helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent

Switch kubectl to the Kubernetes cluster cookie and run the following commands, assigning PROXY_ADDR to the address of your Teleport Cloud tenant.

Add teleport-agent chart to charts repository

PROXY_ADDR=mytenant.teleport.sh:443
helm repo add teleport https://charts.releases.teleport.dev
helm repo update

Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR

CLUSTER='cookie'
helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent \ --set teleportVersionOverride=9.3.8

Step 3/3 Access your Kubernetes cluster

Grant access to your Teleport user

To use Teleport to interact with a Kubernetes cluster, your Teleport roles must allow access from your Kubernetes user and groups. Ensure that you have a Teleport role that grants access to the cluster you plan to interact with.

Run the following command to get the Kubernetes user for your current context:

kubectl config view \-o jsonpath="{.contexts[?(@.context.cluster==\"$(kubectl config current-context)\")].context.user}"

cookie

Create a file called kube-user.yaml with the following content, replacing USER with the output of the command above.

kind: role
metadata:
  name: kube-user
version: v5
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_groups:
    - view
    kubernetes_users:
    - USER
  deny: {}

Retrieve your user:

TELEPORT_USER=myuser
tctl get user/${TELEPORT_USER?} > user.yaml

Add kube-user to your Teleport user's list of roles:

   roles:
   - access
   - auditor
+  - kube-user

Apply your changes:

tctl create -f kube-user.yaml
tctl create -f user.yaml

Log out of Teleport and log in again.

View pods in your cluster

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

tsh kube ls

Kube Cluster Name Selected

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

cookie

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

kubectl get pods

Next Steps