Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport gives you a unified control plane for Kubernetes access across every cluster in your environment — whether on-premises, in the cloud, or at the edge. Instead of distributing kubeconfig files with long-lived credentials, users authenticate once with tsh and request access to any registered cluster. The Teleport Kubernetes Service intercepts all kubectl traffic, enforces role-based access controls, and streams session activity to the audit log.

​
How the Teleport Kubernetes Service works

The Teleport Kubernetes Service runs as a pod (or a standalone process) and maintains a reverse tunnel to the Teleport Proxy Service. When a user runs a kubectl command, the traffic flows: 
[kubectl] ──► [tsh / kubeconfig proxy] ──► [Proxy Service] ──► [Kubernetes Service] ──► [API Server]
Before forwarding a request, the Kubernetes Service:
  1. Validates the user’s short-lived Teleport certificate.
  2. Checks the user’s Teleport roles for kubernetes_labels, kubernetes_groups, and kubernetes_resources permissions.
  3. Impersonates the appropriate Kubernetes user and groups using the Kubernetes API server’s built-in impersonation headers.
  4. Records the session and emits audit events.
No cluster credentials ever reach the end user’s machine.

​
Prerequisites

  • A running Teleport cluster (cloud or self-hosted). See Deploy a Cluster.
  • Helm 3 installed on your workstation.
  • kubectl configured with admin access to the Kubernetes cluster you want to enroll.
  • tctl authenticated to your Teleport cluster.

​
Enrolling a Kubernetes cluster

1

Create a Teleport role for Kubernetes access

Teleport users need a role that grants access to Kubernetes clusters. The following role grants access to all clusters and maps the user to the viewers Kubernetes group:
kind: role
metadata:
  name: kube-access
version: v7
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_resources:
      - kind: '*'
        namespace: '*'
        name: '*'
        verbs: ['*']
    kubernetes_groups:
      - viewers
  deny: {}
Apply the role and assign it to your Teleport user:
tctl create -f kube-access.yaml
tctl users update alice --set-roles=access,kube-access
2

Create Kubernetes RBAC bindings

The viewers Kubernetes group doesn’t have permissions inside the cluster yet. Create a ClusterRoleBinding to bind the viewers group to the built-in view role:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viewers-crb
subjects:
  - kind: Group
    name: viewers
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f viewers-bind.yaml
3

Deploy the Teleport Kubernetes Service

The fastest way to enroll a cluster is to deploy the teleport-kube-agent Helm chart directly onto the cluster you want to protect. Generate a join token first:
tctl tokens add --type=kube --format=text > /tmp/kube-token
Then install the chart:
helm repo add teleport https://charts.releases.teleport.dev
helm repo update

JOIN_TOKEN=$(cat /tmp/kube-token)
helm install teleport-agent teleport/teleport-kube-agent \
  --create-namespace \
  --namespace teleport-agent \
  --set roles=kube \
  --set proxyAddr=mytenant.teleport.sh:443 \
  --set authToken="${JOIN_TOKEN}" \
  --set kubeClusterName=my-cluster \
  --version (=teleport.version=)
Verify the agent pod is running:
kubectl -n teleport-agent get pods
# NAME               READY   STATUS    RESTARTS   AGE
# teleport-agent-0   1/1     Running   0          45s
You can also deploy the Kubernetes Service on a dedicated VM outside the cluster and point it at a kubeconfig. See the Static kubeconfig registration guide for details.
4

Log in and connect to the cluster

From your workstation, authenticate to Teleport and then log in to the cluster:
# Authenticate to Teleport
tsh login --proxy=mytenant.teleport.sh --user=alice

# List all available Kubernetes clusters
tsh kube ls
# Kube Cluster Name   Labels                  Selected
# ─────────────────── ─────────────────────── ────────
# my-cluster          env=prod                

# Request credentials for the cluster
tsh kube login my-cluster
After tsh kube login, your local kubeconfig is updated so that kubectl commands are automatically proxied through Teleport:
kubectl get pods -n teleport-agent
# NAME               READY   STATUS    RESTARTS   AGE
# teleport-agent-0   1/1     Running   0          8m

kubectl get nodes
You can switch between registered clusters at any time with tsh kube login <cluster-name>. Run tsh kube ls to see every cluster your role grants access to.

​
Kubernetes RBAC and impersonation

Teleport translates its own role system into Kubernetes RBAC via impersonation headers. The key fields in a Teleport role are:
FieldPurpose
kubernetes_labelsWhich clusters the user can access, by label
kubernetes_groupsKubernetes groups to impersonate on each request
kubernetes_usersKubernetes user to impersonate (defaults to the Teleport username)
kubernetes_resourcesFine-grained resource/verb restrictions (pods, namespaces, etc.)
Here is an example role that restricts a developer to the development namespace only: 
kind: role
version: v8
metadata:
  name: dev-namespace-access
spec:
  allow:
    kubernetes_labels:
      env: development
    kubernetes_groups:
      - dev-team
    kubernetes_resources:
      - kind: '*'
        api_group: '*'
        namespace: development
        name: '*'
        verbs: ['*']
  deny: {}
Teleport enforces kubernetes_resources at the Teleport layer, but the Kubernetes API server enforces permissions based on the impersonated groups. Make sure your Kubernetes ClusterRoleBinding or RoleBinding grants the necessary permissions to the groups defined in kubernetes_groups.

​
Recording kubectl sessions

All kubectl exec and kubectl port-forward sessions are recorded and available for playback in the Teleport Web UI under Audit → Session Recordings. The audit log also captures every API call made through the Kubernetes Service.

​
Next steps

Access Controls & RBAC

Build fine-grained Teleport roles that map to Kubernetes groups and namespaces.

Access Requests

Require just-in-time approval before granting elevated Kubernetes access.

Helm Deployment Reference

All available values for the teleport-kube-agent Helm chart.

Deployment Architecture

Understand how the Proxy, Auth, and agent services interact at scale.

Build docs developers (and LLMs) love

Get started for freeTalk to us