Connect a Kubernetes Cluster to Teleport

In this guide, we will show you how to register a Kubernetes cluster with Teleport by deploying the Teleport Kubernetes Service on the Kubernetes cluster you want to register.

In this setup, the Teleport Kubernetes Service pod detects that it is running on Kubernetes and registers the cluster automatically.

Prerequisites

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

• Kubernetes >= 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 check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:

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

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Deployment overview

In this guide, we deploy the Teleport Kubernetes Service, which connects a Kubernetes cluster to a Teleport cluster:

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 tokens add --type=kube,app,discovery --ttl=1h --format=text)
echo $TOKEN

Step 2/3. Deploy teleport-kube-agent

To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add:

helm repo add teleport https://charts.releases.teleport.dev

To update the cache of charts from the remote repository, run helm repo update:

helm repo update

PROXY_ADDR=teleport.example.com:443
CLUSTER=cookie
Create the values.yaml file
cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams:  method: "token"  tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"EOF
Install the helm chart with the values.yaml setting
helm install teleport-agent teleport/teleport-kube-agent \  -f values.yaml \  --create-namespace \  --namespace=teleport-agent \  --version 14.0.0

PROXY_ADDR=teleport.example.com:443
CLUSTER=cookie
Create the values.yaml file
cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams:  method: "token"  tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"enterprise: trueEOF
Install the helm chart with the values.yaml setting
helm install teleport-agent teleport/teleport-kube-agent \  -f values.yaml \  --create-namespace \  --namespace=teleport-agent \  --version 14.0.0

Make sure that the Teleport agent pod is running. You should see one Teleport agent pod pod with a single ready container:

kubectl -n teleport get pods
NAME               READY   STATUS    RESTARTS   AGEteleport-agent-0   1/1     Running   0          32s

Step 3/3 Access your Kubernetes cluster

Kubernetes authentication

To authenticate to a Kubernetes cluster via Teleport, your Teleport roles must allow access as at least one Kubernetes user or group. 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[?(@.name==\"$(kubectl config current-context)\")].context.user}"

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

kind: role
metadata:
  name: kube-access
version: v7
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_resources:
      - kind: '*'
        namespace: '*'
        name: '*'
        verbs: ['*']
    kubernetes_groups:
    - viewers
    kubernetes_users:
    # Replace USER with the Kubernetes user for your current context.
    - USER
  deny: {}

Apply your changes:

tctl create -f kube-access.yaml

Assign the kube-access role to your Teleport user by running the appropriate commands for your authentication provider:

Now that Teleport RBAC is configured, you can authenticate to your Kubernetes cluster via Teleport. To interact with your Kubernetes cluster, you will need to configure authorization within Kubernetes.

Kubernetes authorization

To configure authorization within your Kubernetes cluster, you need to create Kubernetes RoleBindings or ClusterRoleBindings that grant permissions to the subjects listed in kubernetes_users and kubernetes_groups.

For example, you can grant some limited read-only permissions to the viewers group used in the kube-access role defined above:

Create a file called viewers-bind.yaml with the following contents:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viewers-crb
subjects:
- kind: Group
  # Bind the group "viewers", corresponding to the kubernetes_groups we assigned our "kube-access" role above
  name: viewers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  # "view" is a default ClusterRole that grants read-only access to resources
  # See: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
  name: view
  apiGroup: rbac.authorization.k8s.io

Apply the ClusterRoleBinding with kubectl:

kubectl apply -f viewers-bind.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". Try 'kubectl version' to test the connection.

kubectl command executed on `cookie` but is routed through the Teleport cluster.
kubectl get pods

Next Steps

• Take a look at a kube-agent helm chart reference for a full list of parameters.