Upgrading Compatibility Overview
Since Teleport is a distributed system with a number of services that run on potentially many hosts, you should take care when upgrading the cluster to ensure that all components remain compatible.
This guide provides an overview of how to upgrade the components in your Teleport cluster while preserving compatibility.
Component compatibility
Teleport uses Semantic Versioning. Version numbers
include a major version, minor version, and patch version, separated by dots.
When running multiple teleport binaries within a cluster, the following rules
apply:
- Servers support clients that are one major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
instance is compatible with 7.x.x agents and 7.x.x
tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. 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 Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. For example, an 8.x.x Proxy Service or agent is not compatible with an 7.x.x Auth Service.
In Teleport Enterprise Cloud, we manage the Auth Service and Proxy Service for
you. You can determine the current version of these services by running the
following command, where mytenant is the name of your Teleport Enterprise
Cloud tenant:
curl -s https://mytenant.teleport.sh/webapi/ping | jq '.server_version'
Upgrading a self-hosted Teleport cluster
Because of the component compatibility guarantees we described in the previous section, you must adhere to the following sequence when upgrading a self-hosted Teleport cluster.
If you are upgrading more then one major version, you must repeat the following steps for each major version until you reach your target version. For example, if your cluster is on v10 and you wish to upgrade to v13, you must first follow the sequence below for v11, then v12, before finally upgrading to v13. You must not upgrade directly from v10 to v13.
- Back up your Teleport cluster state as a precaution against any unforeseen incidents while upgrading the Auth Service, which may perform data migrations on its backend. Follow the instructions in Backup and Restore.
- Upgrade all Auth Service instances to the target version first. Auth Service instances may be upgraded in any sequence or at the same time. After the upgrade confirm that the cluster is in a healthy state before continuing.
- Upgrade Proxy Service instances to the same version as the Auth Service. Proxy Service instances are stateless and can be upgraded in any sequence or at the same time. After the upgrade confirm that the cluster is in a healthy state before continuing.
- Upgrade your Teleport Agents to the same version as the Auth Service. You can upgrade resource agents in any sequence or at the same time. After the upgrade confirm that the cluster is in a healthy state before continuing.
- Upgrade your Teleport clients and plugins (tctl, tsh, tbot, terraform-provider, event-handler, etc.).
Upgrading multiple Teleport clusters
When upgrading multiple Teleport clusters with a trust relationship, you must upgrade in the following sequence to avoid compatibility issues.
You must upgrade all clusters one major version at a time. For example, if you would like to upgrade your clusters from v10 to v12, you must follow the sequence below to upgrade clusters from v10 to v11, then repeat the sequence to upgrade from v10 to v11.
- Upgrade the root cluster—that is, the cluster that other clusters trust—first.
- Verify the upgrade was successful.
- Upgrade the trusted leaf clusters.
Next steps
Return to the Upgrading Introduction for how to upgrade individual components within your Teleport cluster.