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.

Upgrading a distributed system like Teleport requires care. Because the Auth Service, Proxy Service, and Agents all run independently, they can temporarily run different versions during an upgrade window. Teleport’s version compatibility policy defines which version combinations are safe, and the recommended upgrade sequence ensures you never introduce an incompatible combination.

​
Version Compatibility Policy

Teleport guarantees backward compatibility within a one-major-version window:
  • Agents and Proxy instances can run up to one major version behind the Auth Service.
  • Agents must never run a newer version than the Auth Service.
  • Proxy instances must never run a newer version than the Auth Service.
For example, if your Auth Service is on v17, your Proxy Service can be on v17 or v16, and your agents can be on v17, v16, or anywhere in between—but not v18 or later. This policy means:
  • You can upgrade the Auth Service first, and agents will continue working while you roll them out.
  • You cannot skip major versions during an upgrade. Go from v15 → v16 → v17, not v15 → v17 directly.
Multi-version upgrades require sequential steps. If you need to move from v15 to v17, you must first upgrade the entire cluster to v16 and verify it is healthy before upgrading to v17. Skipping a major version is unsupported and may result in data migration failures or loss of connectivity.
To check the current version of your Proxy Service (useful for Teleport Enterprise Cloud): 
curl -s https://mytenant.teleport.sh/webapi/find | jq '.server_version'
To list all connected agents and their versions: 
tctl inventory ls
To list agents that are behind a target version: 
tctl inventory ls --older-than=v17.0.0
Always upgrade in this sequence to maintain compatibility:
1

Back up cluster state

Before upgrading the Auth Service, back up the backend state. The Auth Service may run data migrations on startup that are not reversible without a restore.
# For SQLite (single-node clusters)
cp -r /var/lib/teleport /var/lib/teleport.bak

# For DynamoDB, use AWS Point-in-Time Recovery or an on-demand backup
aws dynamodb create-backup \
  --table-name teleport-cluster-state \
  --backup-name teleport-pre-upgrade-$(date +%Y%m%d)
Follow the Backup and Restore guide for your specific backend.
2

Upgrade the Auth Service

Upgrade all Auth Service instances to the target version first. In a multi-instance HA setup, Auth Service instances can be upgraded simultaneously—they coordinate through the shared backend.
# On each Auth Service host:
curl https://goteleport.com/static/install.sh | bash -s 17 enterprise

# Restart the service
sudo systemctl restart teleport

# Verify the new version is running
teleport version
tctl status
Confirm the cluster is healthy before proceeding.
3

Upgrade the Proxy Service

After all Auth Service instances are on the target version, upgrade Proxy Service instances. Proxy instances are stateless and can be upgraded simultaneously or one at a time.
# On each Proxy Service host:
curl https://goteleport.com/static/install.sh | bash -s 17 enterprise
sudo systemctl restart teleport
teleport version
Test that the Web UI and tsh login still work before continuing.
4

Upgrade Teleport Agents

Finally, upgrade agents (SSH Service, Kubernetes Service, Database Service, Application Service, and Desktop Service nodes). Agents can be upgraded in any order or all at once.
# On each agent host:
curl https://goteleport.com/static/install.sh | bash -s 17 enterprise
sudo systemctl restart teleport
teleport version
If you have many agents, use the automatic updater described below instead of doing this manually.
5

Upgrade client tools and plugins

Update tsh, tctl, tbot, and any Terraform provider or plugin versions to match the cluster version.
curl https://goteleport.com/static/install.sh | bash -s 17 enterprise
tsh version
tctl version

​
Automatic Agent Updates (teleport-update)

For Linux servers running systemd, Teleport provides a built-in updater called teleport-update that automatically keeps agents in sync with the cluster version. This is the recommended approach for production deployments—it eliminates manual upgrade steps for individual agent nodes.

​
How it works

When enabled, teleport-update runs as a systemd timer alongside each agent. It periodically queries the Proxy Service for the target version, downloads the new teleport binary if needed, and restarts the agent in-place during a configured maintenance window.

​
Enabling managed updates on an existing Linux agent

Run the following on each agent host: 
sudo teleport-update enable
Verify the updater is active: 
sudo systemctl status teleport-update.timer
sudo teleport-update status

​
Enabling managed updates on a new agent installation

When installing a new agent using the install script, the updater is automatically configured: 
curl https://goteleport.com/static/install.sh | bash -s 17 enterprise
sudo teleport-update enable

​
Configuring the update schedule

The update schedule is stored as a dynamic resource (autoupdate_config) in the cluster and controls when each group of agents updates. Create or edit the schedule with tctl: 
# autoupdate_config.yaml
kind: autoupdate_config
version: v1
metadata:
  name: autoupdate-config
spec:
  agents:
    mode: enabled
    schedules:
      regular:
        # Monday–Wednesday 02:00–03:00 UTC
        - name: default
          days: ["Mon", "Tue", "Wed"]
          start_hour: 2
          wait_hours: 24

tctl create autoupdate_config.yaml

​
Setting the target version (self-hosted only)

On self-hosted clusters, set which version agents should update to: 
# autoupdate_version.yaml
kind: autoupdate_version
version: v1
metadata:
  name: autoupdate-version
spec:
  agents:
    target_version: "17.1.0"

tctl create autoupdate_version.yaml
On Teleport Enterprise Cloud, the target version is managed by Teleport. You only need to enable the updater on each agent—you do not set the version yourself.

​
Dry-run check

To verify that an agent can see the target version without performing an update: 
sudo teleport-update dry-run
Example output: 
an upgrade is available (16.3.2 -> 17.1.0)
within maintenance window, upgrade will be attempted.

​
Rolling Upgrades for High-Availability Clusters

In an HA deployment with multiple Proxy instances behind a load balancer, you can upgrade without user-facing downtime by performing a rolling upgrade:
  1. Remove one Proxy pod/host from the load balancer.
  2. Upgrade and restart that Proxy.
  3. Verify it is healthy and re-add it to the load balancer.
  4. Repeat for each remaining Proxy instance.
For Kubernetes deployments using the teleport-cluster Helm chart, the chart handles this automatically. The chart automatically waits for the previous Proxy Service version to stop responding before starting the new Auth Service version: 
helm upgrade teleport-cluster teleport/teleport-cluster \
  --version=17.1.0 \
  --values=values.yaml

​
Downgrading and Rollback

Major version downgrades require a backend restore. The Auth Service may apply irreversible data migrations when upgrading between major versions. You cannot simply reinstall the old binary. You must restore the backend from a backup taken before the upgrade.
To roll back a major version upgrade:
  1. Stop all Teleport services in reverse order: agents → Proxy → Auth.
  2. Restore the Auth Service backend from the pre-upgrade backup.
  3. Reinstall the previous Teleport version binaries on all hosts.
  4. Start services in order: Auth → Proxy → agents.
Patch version rollbacks (e.g., v17.1.1 → v17.1.0) are safe and do not require a backend restore.

​
Upgrading Trusted Clusters

When you have a trust relationship between a root cluster and one or more leaf clusters, upgrade in this order:
  1. Upgrade the root cluster (Auth Service, Proxy, then agents).
  2. Verify the root cluster is healthy.
  3. Upgrade each leaf cluster using the same Auth → Proxy → agents sequence.
Like single-cluster upgrades, you must upgrade one major version at a time. Do not upgrade a leaf cluster to a version newer than the root cluster.

Architecture

How the Auth Service, Proxy, and Agents interact.

Deploy Cluster

Install and configure a Teleport cluster from scratch.

Helm Charts

Upgrade the teleport-cluster or teleport-kube-agent Helm releases.

tctl Reference

tctl inventory ls and other administrative commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us