Deploy a Teleport Cluster on Linux or Kubernetes

A Teleport cluster requires at minimum the Auth Service and the Proxy Service. For small deployments, you can run both services from a single teleport process on one Linux machine. For high-availability production deployments, you can run them as separate, horizontally-scaled pods on Kubernetes. This guide walks through both approaches.

Linux (Systemd)
Docker (Compose)
Kubernetes (Helm)

Linux deployment

The Linux path is the fastest way to get a self-hosted Teleport cluster running. A single virtual machine (2 vCPUs, 4 GB RAM) is sufficient to get started.

Install Teleport

Teleport provides signed packages for Debian/Ubuntu (apt) and RHEL/CentOS (yum), as well as a tarball for other distributions.

# Debian / Ubuntu
curl https://goteleport.com/static/install.sh | bash -s 17 oss

# RHEL / CentOS / Amazon Linux 2
curl https://goteleport.com/static/install.sh | bash -s 17 oss

# Verify the installation
teleport version

Replace oss with enterprise if you have a Teleport Enterprise license. The installation script automatically detects your package manager (apt, yum, or zypper) and configures the Teleport package repository.

Write a minimal teleport.yaml

Create /etc/teleport.yaml with the configuration below. Replace teleport.example.com with the public DNS name or IP address of your server.

# /etc/teleport.yaml
version: v3

teleport:
  nodename: teleport.example.com
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
  # Store state locally (SQLite). Switch to DynamoDB/etcd for HA.
  storage:
    type: sqlite

auth_service:
  enabled: true
  cluster_name: teleport.example.com

proxy_service:
  enabled: true
  public_addr: teleport.example.com:443
  # Automatically obtain a TLS certificate from Let's Encrypt
  acme:
    enabled: true
    email: admin@example.com

ssh_service:
  enabled: true
  labels:
    env: production

TLS and ACME: When acme.enabled is true, the Proxy Service uses Let’s Encrypt to obtain and auto-renew a certificate for your public_addr. Port 443 must be reachable from the internet for the ACME HTTP-01 challenge to succeed. If you provide your own certificate, set https_keypairs instead.

Create the systemd service and start Teleport

The Teleport package installs a systemd unit file automatically. Enable and start it:

sudo systemctl enable teleport
sudo systemctl start teleport

# Confirm the service is running
sudo systemctl status teleport

Check the logs for any errors:

sudo journalctl -u teleport -f

You should see log lines confirming that the Auth Service and Proxy Service have started and that certificates have been obtained.

Create an admin user

Use tctl (the Teleport admin CLI) to create the first local user. The command prints a one-time invite URL:

sudo tctl users add admin --roles=editor,access --logins=root,ubuntu

Open the printed URL in your browser to set a password and enroll an MFA device.

tctl must be run on the same host as the Auth Service, or with a valid admin certificate from a remote machine.

Install tsh (the Teleport client) on your workstation:

curl https://goteleport.com/static/install.sh | bash -s 17 oss

Then log in:

tsh login --proxy=teleport.example.com --user=admin

Verify that the cluster is healthy:

tsh status
tctl status

You should see your cluster name, version, and CA fingerprints.

Docker deployment

Docker Compose is convenient for local testing and demos. It is not recommended for production because the container filesystem is ephemeral and does not support HA.

# docker-compose.yaml
version: "3"
services:
  teleport:
    image: public.ecr.aws/gravitational/teleport-ent:17
    container_name: teleport
    hostname: teleport.example.com
    volumes:
      - ./config:/etc/teleport
      - ./data:/var/lib/teleport
    ports:
      - "443:443"
      - "3022:3022"
      - "3025:3025"
    command: teleport start --config=/etc/teleport/teleport.yaml

Generate a default configuration file and start the cluster:

# Generate a default teleport.yaml
docker run --rm \
  public.ecr.aws/gravitational/teleport-ent:17 \
  teleport configure --cluster-name=teleport.example.com \
  > ./config/teleport.yaml

docker compose up -d
docker compose exec teleport tctl users add admin --roles=editor,access --logins=root

Kubernetes deployment via Helm

For production Kubernetes deployments, use the official teleport-cluster Helm chart. This deploys the Auth Service and Proxy Service as separate, scalable Deployment resources.

Add the Teleport Helm repository

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

Create a values file

Create values.yaml for a standalone cluster that stores state in Kubernetes-native PersistentVolumes:

# values.yaml
clusterName: teleport.example.com
chartMode: standalone

# TLS certificate for the public endpoint
# Use cert-manager or supply your own secret
acme: true
acmeEmail: admin@example.com

# Scale Auth and Proxy (requires HA-capable backend like DynamoDB/Firestore)
# highAvailability:
#   replicaCount: 2

For AWS production deployments, use chartMode: aws and configure DynamoDB and S3 as the storage backends. For GCP, use chartMode: gcp with Firestore and GCS.

Install the chart

kubectl create namespace teleport

helm install teleport-cluster teleport/teleport-cluster \
  --namespace teleport \
  --values values.yaml \
  --version 17.0.0

Watch the pods come up:

kubectl -n teleport get pods -w

Create an admin user

kubectl -n teleport exec deploy/teleport-cluster-auth -- \
  tctl users add admin --roles=editor,access --logins=root,ubuntu

Open the printed URL to finish registration.

Verify the deployment

Get the external load balancer address:

kubectl -n teleport get service teleport-cluster

Point your DNS record to the load balancer IP/hostname, then log in:

tsh login --proxy=teleport.example.com --user=admin
tctl status

Minimal Production teleport.yaml

The following is a more complete teleport.yaml suitable for a self-hosted production deployment. It uses DynamoDB for cluster state and S3 for session recordings.

version: v3

teleport:
  nodename: teleport.example.com
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
    format:
      output: json

  # High-availability DynamoDB backend
  storage:
    type: dynamodb
    region: us-east-1
    table_name: teleport-cluster-state
    audit_table_name: teleport-audit-events
    audit_sessions_uri: s3://my-teleport-recordings?region=us-east-1

auth_service:
  enabled: true
  cluster_name: teleport.example.com
  listen_addr: 0.0.0.0:3025

  # Authentication policy
  authentication:
    type: local
    second_factor: otp        # "on", "otp", "webauthn", or "off"
    webauthn:
      rp_id: teleport.example.com

  # Session recording (node-sync is most secure)
  session_recording: node-sync

proxy_service:
  enabled: true
  public_addr: teleport.example.com:443
  listen_addr: 0.0.0.0:443

  # Bring your own TLS certificate
  https_keypairs:
    - key_file: /var/lib/teleport/certs/proxy.key
      cert_file: /var/lib/teleport/certs/proxy.crt

  # Enable TLS routing to multiplex all protocols on port 443
  tunnel_listen_addr: 0.0.0.0:443

ssh_service:
  enabled: false  # run SSH service only on agent nodes, not control-plane

Systemd Service Configuration

The Teleport package installs the following systemd unit at /lib/systemd/system/teleport.service. Review it to customize resource limits or add environment files:

[Unit]
Description=Teleport SSH Service
After=network.target

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/teleport start --config=/etc/teleport.yaml --pid-file=/run/teleport.pid
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport.pid
LimitNOFILE=524288

[Install]
WantedBy=multi-user.target

To apply configuration changes without a full restart, send SIGHUP:

sudo systemctl reload teleport

Next Steps

Configuration Reference

Complete annotated reference for every teleport.yaml option.

Helm Charts

Deep-dive into teleport-cluster and teleport-kube-agent Helm values.

Enroll Servers

Add Linux servers to your new cluster with the SSH Service.

Upgrading

How to safely upgrade your cluster and agents.

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Deploy a Teleport Cluster on Linux or Kubernetes

Linux deployment

Docker deployment

Kubernetes deployment via Helm

Minimal Production teleport.yaml

Systemd Service Configuration

Next Steps

Configuration Reference

Helm Charts

Enroll Servers

Upgrading

Build docs developers (and LLMs) love

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Documentation Index

​Linux deployment

​Docker deployment

​Kubernetes deployment via Helm

​Minimal Production teleport.yaml

​Systemd Service Configuration

​Next Steps

Configuration Reference

Helm Charts

Enroll Servers

Upgrading

Build docs developers (and LLMs) love

Linux deployment

Docker deployment

Kubernetes deployment via Helm

Minimal Production teleport.yaml

Systemd Service Configuration

Next Steps