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 provides two official Helm charts for Kubernetes deployments. The teleport-cluster chart deploys the control plane—Auth Service and Proxy Service—as a self-contained cluster inside your Kubernetes environment. The teleport-kube-agent chart connects an existing Kubernetes cluster (or other infrastructure) to a running Teleport cluster as a set of agents. You only ever need one teleport-cluster deployment; teleport-kube-agent can be deployed to as many clusters as you want. Both charts are published to the Teleport Helm repository and are versioned alongside Teleport itself. Use the chart version that matches your target Teleport version.

​
Adding the Teleport Helm Repository

Before installing either chart, add the official Teleport repository: 
helm repo add teleport https://charts.releases.teleport.dev
helm repo update teleport
Verify that the charts are available: 
helm search repo teleport/teleport-cluster
helm search repo teleport/teleport-kube-agent
The chart source code is available on GitHub:

​
The teleport-cluster Chart

The teleport-cluster chart deploys a complete Teleport control plane in two sets of Kubernetes Deployment pods:
PodsServicesPurpose
auth Deploymentauth_service, kubernetes_serviceCertificate authority, audit log, cluster state
proxy Deploymentproxy_servicePublic HTTPS/SSH endpoint, Web UI, reverse tunnel listener
The chart supports four deployment modes, controlled by the chartMode value:
chartModeStorageBest for
standaloneKubernetes PersistentVolumesSingle-node clusters, test environments
awsDynamoDB + S3Production on AWS/EKS
gcpFirestore + GCSProduction on GCP/GKE
azureAzure Blob + CosmosDBProduction on Azure/AKS

​
Choosing Community Edition vs Enterprise

# Community Edition – no license required
clusterName: teleport.example.com
chartMode: standalone

# TLS via Let's Encrypt
acme: true
acmeEmail: admin@example.com

# Authentication: local users + OTP
authentication:
  type: local
  secondFactor: otp

​
Installing teleport-cluster

# Create the namespace
kubectl create namespace teleport

# (Enterprise only) Create the license secret
kubectl -n teleport create secret generic teleport-enterprise-license \
  --from-file=license.pem=/path/to/license.pem

# Install the chart
helm install teleport-cluster teleport/teleport-cluster \
  --namespace teleport \
  --values values.yaml \
  --version 17.0.0

# Watch pods come up
kubectl -n teleport get pods -w
Once all pods are Running, get the external load balancer address and create a DNS record pointing your clusterName to it: 
kubectl -n teleport get service teleport-cluster
Create the first admin user: 
kubectl -n teleport exec deploy/teleport-cluster-auth -- \
  tctl users add admin --roles=editor,access --logins=root,ubuntu

​
Advanced Auth and Proxy Configuration

You can pass any teleport.yaml option directly to Auth or Proxy pods using auth.teleportConfig and proxy.teleportConfig. These values are deep-merged into the chart-generated configuration: 
auth:
  teleportConfig:
    auth_service:
      client_idle_timeout: 2h
      session_recording: node-sync

proxy:
  teleportConfig:
    proxy_service:
      # Annotate the Proxy Service Kubernetes Service for external-dns
      public_addr: teleport.example.com:443
  annotations:
    service:
      external-dns.alpha.kubernetes.io/hostname: "teleport.example.com"

​
The teleport-kube-agent Chart

The teleport-kube-agent chart connects a Kubernetes cluster (or any other supported infrastructure resource) to an existing Teleport cluster. It runs a Teleport Agent as a StatefulSet inside the target cluster. The agent establishes a reverse tunnel to your Teleport cluster’s Proxy Service—no inbound ports required on the target cluster. The chart can run any combination of these services:
Serviceroles valueWhat it provides
kubernetes_servicekubeKubernetes API proxy for this cluster
app_serviceappHTTP/TCP application proxy
db_servicedbDatabase protocol proxy
discovery_servicediscoveryAuto-discover and enroll cloud resources

​
Connecting a Kubernetes Cluster

1

Generate a join token

On the Teleport cluster (or via tctl), create a token that allows the agent to join with kube role:
tctl tokens add \
  --type=kube \
  --ttl=5m
Copy the printed token value. You will use it in the next step.
2

Create a values file

# agent-values.yaml
# Address of your Teleport cluster's Proxy Service
proxyAddr: teleport.example.com:443

# Token generated in the previous step
authToken: "your-join-token-here"

# Name of the Kubernetes cluster as it will appear in 'tsh kube ls'
kubeClusterName: my-remote-cluster

# Enable the Kubernetes service
roles: kube

# Labels for RBAC matching
labels:
  env: production
  cloud: aws
  region: us-east-1
3

Install the chart

helm install teleport-agent teleport/teleport-kube-agent \
  --namespace teleport \
  --create-namespace \
  --values agent-values.yaml \
  --version 17.0.0
Verify the pod is running and has connected:
kubectl -n teleport get pods
4

Verify from the cluster

tsh kube ls
# NAME                STATUS
# my-remote-cluster   online

​
Connecting Multiple Resource Types

A single teleport-kube-agent deployment can enroll Kubernetes access, databases, and applications simultaneously: 
# multi-service-values.yaml
proxyAddr: teleport.example.com:443
authToken: "your-join-token-here"

# Enable multiple services
roles: kube,db,app

kubeClusterName: my-cluster

# Register databases
databases:
  - name: postgres-prod
    uri: postgres.namespace.svc.cluster.local:5432
    protocol: postgres
    labels:
      env: production

# Register internal applications
apps:
  - name: grafana
    uri: http://grafana.monitoring.svc.cluster.local:3000
    labels:
      team: platform

​
Enabling Automatic Agent Updates (Enterprise)

For Teleport Enterprise, enable the built-in updater to keep the agent synchronized with the cluster version: 
# Add to your agent-values.yaml
enterprise: true

updater:
  enabled: true

helm upgrade teleport-agent teleport/teleport-kube-agent \
  --namespace teleport \
  --values agent-values.yaml
Verify the updater pod is running: 
kubectl -n teleport get pods
# NAME                                    READY   STATUS    RESTARTS
# teleport-agent-0                        1/1     Running   0
# teleport-agent-updater-xxx-yyy          1/1     Running   0

​
Upgrading Helm Releases

Always upgrade the teleport-cluster (control plane) before upgrading any teleport-kube-agent releases. See the Upgrading guide for the full compatibility policy.

​
Upgrading teleport-cluster

helm repo update teleport

helm upgrade teleport-cluster teleport/teleport-cluster \
  --namespace teleport \
  --values values.yaml \
  --version 17.1.0
The chart automatically waits for the previous Proxy Service version to stop responding before starting a new version of the Auth Service, ensuring a safe rolling update.

​
Upgrading teleport-kube-agent

helm repo update teleport

helm upgrade teleport-agent teleport/teleport-kube-agent \
  --namespace teleport \
  --values agent-values.yaml \
  --version 17.1.0
If you have enabled the automatic updater (updater.enabled: true), the agent pods are updated automatically and you do not need to run helm upgrade for version bumps. You only need to run helm upgrade when changing chart values.

​
Helm Chart Reference

For a complete list of all available chart values, see the official Helm references:

teleport-cluster Reference

All values for deploying the Teleport control plane on Kubernetes.

teleport-kube-agent Reference

All values for connecting agents to an existing Teleport cluster.

Deploy Cluster

Step-by-step deployment guide including the Linux path.

Upgrading

Version compatibility and upgrade order for self-hosted clusters.

Build docs developers (and LLMs) love

Get started for freeTalk to us