Agent Update Management (Preview)
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
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.
When updating the agent, the updater will ensure the new version's authenticity
before deploying it. On Linux distributions using
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
channel. Self-hosted Teleport users must host their own version server and
updater their release channel each time they update their Auth and Proxy
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 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.
Self-hosted users must first set up self-hosted automatic agent update .
If you're a Teleport Cloud user or self-hosting with automatic update configured, you can enroll your agents into automatic updates .