Agent Update Management

While many Teleport resources support agentless mode, agent deployments are sometimes simpler and more convenient. However, large Teleport deployments can create an additional burden: updating all agents.

Starting with version 13, Teleport supports automatic agent updates for systemd-based Linux distributions using apt or yum package managers, and Kubernetes clusters.

Update logic and failure modes

An updater is a piece of software deployed next to an agent which is responsible for updating it. Updating multiple agents requires multiple updaters.

We designed the updater to be as decoupled from Teleport as possible. The updater can update agents even when they cannot join the Teleport cluster. Pushing a broken version can happen, but a rollback/roll-forward must always be possible without manually connecting to the resource and fixing the agent.

The updater recurrently fetches the target version from a version server and updates the agent to the target version. Because restarting the agent can disrupt currently open sessions, it will only update the agent in two cases: during a maintenance window or when the agent is unhealthy.

When enrolled in a cluster with automatic updates, the agent will retrieve its maintenance schedule from the Teleport cluster and save it. When a maintenance schedule is available, the updater will honour it. However, if the updater cannot find the maintenance schedule, it will consider the agent unhealthy and perform updates as soon as possible. Similarly, if the updater detects the agent is unhealthy, it immediately applies any pending update to try to recover from a degraded state.

We implemented an additional failsafe: the critical maintenance toggle. The version server can specify that an update is critical. Critical updates are applied even if the updater is outside its regular maintenance window.

Security

When updating the agent, the updater will ensure the new version's authenticity before deploying it. On Linux distributions using apt or yum, it relies on the existing package signature system. On Kubernetes-based environments, it validates the OCI image signature (using cosign's signature ).

Version server and source of truth

The agent version is subject to the following constraints:

• the agent must never exceed the Proxy or Auth Service version,
• the agent must always be no more than one major version below the Proxy or Auth Service version.

The best practice is to always align the agent version with the Proxy and Auth ones. To upgrade Auth and Proxy, follow the Teleport Cluster upgrade guide .

For this reason, all updaters must subscribe to a release channel targeting versions that are compatible with their Teleport cluster. Teleport Cloud users must use the Teleport Cloud version server with the stable/cloud release channel. Self-hosted Teleport users must host their own version server and either update their release channel each time they update their Auth and Proxy instances, or use the stable/rolling channel.

Teleport Cloud

Teleport Cloud users can use Teleport Cloud's version server only if their instance is enrolled in automatic updates. This version server will always target the best version from a feature, compatibility, security and stability point of view.

Teleport Cloud users whose control plane is not automatically updated must not use automatic agent updates. This is because their Teleport instance version might differ from the other Teleport Cloud instances and might not yet support the latest agent version.

Self-hosted Teleport

Self-hosted Teleport users can set up automatic agent updates. They must host their version server and choose their target version. They are responsible for ensuring the targeted version is compatible with their current auth/proxy versions. They must also monitor the agent's health and rollout status to ensure every agent is healthy and running the correct version.

Next steps

Self-hosted users must first set up self-hosted automatic agent upgrades .

After that, you can set enroll agents in automatic updates as part of the upgrading procedure.