Setting up self-hosted automatic agent updates (Preview)
Automatic agent update is available starting from Teleport
Teleport supports automatic agent updates for
systemd-based Linux distributions using
yum package managers,
and Kubernetes clusters. The automatic updates architecture
page describes how agent
This guide covers how to set up the automatic update infrastructure. If this is already done, or you are a Teleport Cloud user, you can directly enroll agents into automatic updates.
Systemd agents enrolled into automatic updates can only install versions
present in their package repositories. As Teleport 14 won't be published to
stable/v13, those agents will require manual intervention to be updated to
the next major version (adding a new apt/yum repo for
This limitation will be fixed before Teleport 14. We'll provide a rolling update channel for agents to be able to automatically update from one major to another. When this will happen, you will have to update the repos of the existing agents to point to the new repo.
- Self-hosted Teleport cluster running.
tctlexecution on the auth machine or a role allowing verbs
deleteon the resource
- a public S3/GCS bucket,
- a web server accessible from all agents with valid TLS certificates.
Step 1/3. Create release channel files
A release channel contains two pieces of information: the targeted version and if the update is critical. Updaters subscribe to a release channel and will update to the provided version during a maintenance window if possible. If the update is critical, updaters will ignore the maintenance schedule and update as soon as possible.
Create a directory for the new release channel
current release channel target the version 13.0.3:
echo -n "13.0.3" > current/version
And mark the update as not critical:
echo -n "no" > current/critical
Step 2/3. Host the release channel files on the version server
The release channel must be hosted on a webserver with trusted TLS certificates and reachable by all agents.
Public cloud buckets like Amazon S3 or Google Cloud Storage are good candidates as they provide reliable low-maintenance file hosting.
You can also serve the files with a regular webserver like
The release channel needs to be served over HTTPS.
Choose a way to serve the release channel and setup the hosting.
The webserver must answer the following queries:
The web server serving the release channel is called the version server.
Save the version server domain and release channel name (here respectively
current) as they will be required
later to configure the agent updaters.
Step 3/3. Configure the maintenance schedule
At this point the updaters can be configured to pull the version from the release channel and update the agents. However, they still don't know when they should perform updates.
Agents can retrieve the maintenance schedule from the Teleport cluster and pass it to the updater. In this step you'll configure the maintenance schedule for the whole cluster.
Create the following
cmc.yaml manifest allowing maintenances on Monday, Wednesday
and Friday between 02:00 and 03:00 UTC.
kind: cluster_maintenance_config spec: agent_upgrades: # Maintenance window start hour in UTC. # The maintenance window lasts 1 hour. utc_start_hour: 2 # Week days when maintenance is allowed # Possible values are: # - Short names: Sun, Mon, Tue, Wed, Thu, Fri, Sat # - Long names: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday weekdays: - Mon - Wed - Fri
Finally, apply the manifest using
tctl create cmc.yaml
maintenance window has been updated
At this point, the cluster is ready for agent automatic updates. Agents configured to automatically update will fetch their version from the version server. By changing the target version served by the version server you can upgrade or downgrade the agents.
You can now enroll agents into automatic updates.