In this guide, we will show you how to upgrade all of the components in your Teleport cluster.
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 Cloud tenant:
curl -s https://mytenant.teleport.sh/webapi/ping | jq '.server_version'
Read the following rules to ensure that your Teleport Nodes 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 Nodes are compatible.
When running multiple binaries of Teleport within a cluster, the following rules apply:
- Patch and minor versions are always compatible, for example, any 5.0.1 component will work with any 5.0.3 component and 6.1.0 component will work with any 6.7.0 component.
- Major versions are always compatible with the previous major release. This means you must not attempt to upgrade from 5.x.x straight to 7.x.x. You must upgrade to 6.x.x first.
- The above applies to both clients and servers. For example, a 6.x.x Proxy Service is
compatible with 5.x.x Nodes and 5.x.x
tsh
. But we don't guarantee that a 7.x.xtsh
will work with a 5.x.x Proxy Service.
Backup
Back up before upgrading. We have more instructions in Backing up Teleport.
Upgrade Sequence
When upgrading a single Teleport cluster:
- Upgrade the Auth Service first. The Auth Service keeps the cluster state and, if there are data format changes introduced in the new version, will perform necessary migrations.
- Upgrade Proxy Service instances. These are stateless and can be upgraded in any sequence or at the same time.
- Finally, upgrade your Teleport Nodes in any sequence or at the same time.
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:
- First, upgrade the root cluster, i.e. the one that other clusters trust.
- Upgrade the Trusted Clusters.
The Teleport Auth Service and Proxy Service are upgraded automatically. When upgrading Nodes, you may upgrade in any sequence or at the same time.
When upgrading multiple clusters:
- First, upgrade the root cluster, i.e. the one that other clusters trust.
- Upgrade the Trusted Clusters.
Further reading
If you would like to learn how to upgrade a single teleport
binary, read
Upgrade the Teleport Binary.