Setting up self-hosted automatic agent updates
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
Teleport supports automatic agent updates for
systemd-based Linux distributions using
zypper 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/zypper repo for
Alternatively, you can use the
stable/rolling channel, which contains
Teleport v13.3.2 forward, including future major releases.
- Self-hosted Teleport cluster v13.0 or higher.
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.
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 14.2.1:
echo -n "14.2.1" > current/version
And mark the update as not critical:
echo -n "no" > current/critical
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:
curl https://<hosting-domain-and-path>/current/version14.2.1curl https://<hosting-domain-and-path>/current/criticalno
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.
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.yamlmaintenance 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.