Teleport

Upgrading a Teleport Cluster

Available for:
OpenSource
Team
Cloud
Enterprise

This guide demonstrates how to upgrade all of the components in your Teleport cluster.

Teleport Team takes care of this setup for you so you can provide secure access to your infrastructure right away.

Get started with a free trial of Teleport Team.

Production releases

Avoid running pre-releases (release candidates) in production environments.

The Teleport development team uses Semantic Versioning, which makes it easy to tell if a specific version is recommended for production use.

Component compatibility

In Teleport Cloud, we manage the Auth and Proxy Services for you. You can determine the current version of these services by running the following command, where mytenant is the name of your Teleport Team or Teleport Enterprise Cloud tenant:

curl -s https://mytenant.teleport.sh/webapi/ping | jq '.server_version'

Read the following rules to ensure that your Teleport resource services (for example, the SSH Service and Database Service) are compatible with the Teleport Auth and Proxy Services. You should check the version of the Auth and Proxy Services regularly to make sure that your Teleport resource services are compatible.

When running multiple teleport binaries within a cluster, the following rules apply:

Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

Backup

Back up before upgrading. We have more instructions in Backing up Teleport.

Upgrade sequence

Teleport requires upgrading the Teleport Cluster from one major version to another in sequence. If you are currently on version 11.x, you must upgrade to the latest version 12.x before going to version 13.x. To upgrade in sequence, upgrade the Teleport cluster and confirm a healthy start before continuing to the next version.

When upgrading a single Teleport cluster:

Upgrade the Auth Service to the next major version first. The Auth Service keeps the cluster state. If there are data format changes introduced in the new version, the Auth Service performs the necessary migrations.
After the upgrade, start the Auth Service and CONFIRM that it's in a healthy state before continuing.
Upgrade Proxy Service instances to the same version number as the Auth Service. Proxy Service instances are stateless and can be upgraded in any sequence or at the same time.
Upgrade your Teleport resource services to the same version number as the Auth Service. You can upgrade resource agents in any sequence or at the same time.

If you are upgrading more then one version number, repeat these steps until you reach your target major version number.

Warning

If several Auth Service instances are running in the High Availability configuration (for example, in an AWS Auto Scaling group), you must shrink the group to just one Auth Service before performing an upgrade.

While Teleport will attempt to perform any necessary migrations, we recommend users create a backup of their backend before upgrading the Auth Server as a precaution. This allows for a safe rollback in case the migration itself fails.

When upgrading multiple clusters:

Upgrade the root cluster—that is, the cluster that other clusters trust—first.
Verify the upgrade was successful.
Upgrade the trusted leaf clusters.

The Teleport Auth Service and Proxy Service are upgraded automatically. When upgrading resource services, you may upgrade in any sequence or at the same time.