
Automatic agent update is available starting from Teleport 13.0
.
Automatic agent update is available starting from Teleport 13.0
.
Teleport Cloud does not run Teleport 13 yet.
Teleport supports automatic agent updates for
systemd-based Linux distributions using apt
or yum
package managers,
and Kubernetes clusters. The automatic updates architecture
page describes how agent
updating works.
This guide explains how to enroll an existing Teleport agent into automatic updates.
Requirements
- A Teleport Enterprise agent, either:
- started via systemd on a distribution using the
apt
oryum
package managers - deployed with the
teleport-kube-agent
Helm chart
- started via systemd on a distribution using the
- automatic update infrastructure set up. For Self-Hosted users this means you already followed this guide and know your version server URL and release channel
- A Teleport Enterprise agent, either:
- started via systemd on a distribution using the
apt
oryum
package managers - deployed with the
teleport-kube-agent
Helm chart
- started via systemd on a distribution using the
- as a Teleport Cloud user, you must check if your Could Tenant is enrolled into automatic updates.
Enroll instructions
Cluster Type
Confirm you have the Teleport Enterprise edition installed.
teleport versionTeleport Enterprise v13.0.3 go1.20
Create the upgrade configuration directory:
sudo mkdir -p /etc/teleport-upgrade.d/
If you changed the agent user to run as non-root, create
/etc/teleport-upgrade.d/schedule
and grant ownership to your Teleport user.
Else, you can skip this step:
sudo touch /etc/teleport-upgrade.d/schedulesudo chown your-teleport-user /etc/teleport-upgrade.d/schedule
Configure the updater to connect to your custom version server and subscribe to the right release channel:
echo version-server-url/path/release-channel | sudo tee /etc/teleport-upgrade.d/endpoint
Make sure not to include https://
as a prefix to the server address.
Install the teleport-ent-updater
package (note: your teleport agent will be restarted during install):
sudo apt install teleport-ent-updateror
sudo yum install teleport-ent-updater
Finally, verify that the updater can see your version endpoint:
sudo teleport-upgrade dry-run
You should see one of the following messages, depending on the target version you are currently serving:
no upgrades available (1.2.3 == 1.2.3)
an upgrade is available (1.2.3 -> 2.3.4)
teleport-upgrade
may complain about not having a valid upgrade schedule.
This is expected immediately after install as the maintenance schedule might
not be exported yet.
Confirm you are using the Teleport Enterprise image. The enterprise
value setting
should have been set to true
for the Helm chart installation.
Add the following chart values to your existing agent values.yaml
:
updater:
enabled: true
versionServer: https://<version-server-domain-and-path>
releaseChannel: <release-channel>
Update the Helm chart release with the new values by running helm upgrade
.
You can validate the updater is running properly by checking if its pod is ready:
kubectl get podsNAME READY STATUS RESTARTS AGE
my-agent-0 1/1 Running 0 14m
my-agent-1 1/1 Running 0 14m
my-agent-2 1/1 Running 0 14m
my-agent-updater-d9f97f5dd-v57g9 1/1 Running 0 16m
And by consulting its logs:
kubectl logs <your-agent-release>-updater2023-04-28T13:13:30Z INFO StatefulSet is already up-to-date, not updating. {"controller": "statefulset", "controllerGroup": "apps", "controllerKind": "StatefulSet", "StatefulSet": {"name":"my-agent","namespace":"agent"}, "namespace": "agent", "name": "my-agent", "reconcileID": "10419f20-a4c9-45d4-a16f-406866b7fc05", "namespacedname": "agent/my-agent", "kind": "StatefulSet", "err": "no new version (current: \"v12.2.3\", next: \"v12.2.3\")"}
Confirm you have the Teleport Enterprise edition installed.
teleport versionTeleport Enterprise v13.0.3 go1.20
If you changed the agent user to run as non-root, create
/etc/teleport-upgrade.d/schedule
and grant ownership to your Teleport user.
Else, you can skip this step:
sudo mkdir -p /etc/teleport-upgrade.d/sudo touch /etc/teleport-upgrade.d/schedulesudo chown <your-teleport-user> /etc/teleport-upgrade.d/schedule
Install the teleport-ent-updater
package (note: your teleport agent will be restarted during install):
sudo apt install teleport-ent-updateror
sudo yum install teleport-ent-updater
Finally, verify that the updater can see your version endpoint:
sudo teleport-upgrade dry-run
You should see one of the following messages, depending on the target version you are currently serving:
no upgrades available (1.2.3 == 1.2.3)
an upgrade is available (1.2.3 -> 2.3.4)
teleport-upgrade
may complain about not having a valid upgrade schedule.
This is expected immediately after install as the maintenance schedule might
not be exported yet.
Confirm you are using the Teleport Enterprise image. The enterprise
value setting
should have been set to true
for the Helm chart installation.
Add the following chart values to your existing agent values.yaml
:
updater:
enabled: true
Update the Helm chart release with the new values by running helm upgrade
.
You can validate the updater is running properly by checking if its pod is ready:
kubectl get podsNAME READY STATUS RESTARTS AGE
my-agent-0 1/1 Running 0 14m
my-agent-1 1/1 Running 0 14m
my-agent-2 1/1 Running 0 14m
my-agent-updater-d9f97f5dd-v57g9 1/1 Running 0 16m
And by consulting its logs:
kubectl logs <your-agent-release>-updater2023-04-28T13:13:30Z INFO StatefulSet is already up-to-date, not updating. {"controller": "statefulset", "controllerGroup": "apps", "controllerKind": "StatefulSet", "StatefulSet": {"name":"my-agent","namespace":"agent"}, "namespace": "agent", "name": "my-agent", "reconcileID": "10419f20-a4c9-45d4-a16f-406866b7fc05", "namespacedname": "agent/my-agent", "kind": "StatefulSet", "err": "no new version (current: \"v12.2.3\", next: \"v12.2.3\")"}
Troubleshooting
Manually running an update
If the agent is not automatically updated, you can:
Invoke manually the updater and look at its logs.
sudo teleport-upgrade run
Consult the teleport-kube-agent-updater
logs:
kubectl logs <your-agent-release>-updater
The Kubernetes updater responds to events, or is woken up every 30 minutes. If you don't want to wait until the next reconciliation, you can trigger an event. Any deployment update will send an event, so the updater can be triggered by annotating the resource:
kubectl annotate statefulset/<your-agent-release> 'debug.teleport.dev/trigger-event=1'
Suspending automatic updates
You can suspend automatic updates for an agent:
Disable the systemd timer:
sudo systemctl disable --now teleport-upgrade.timer
To enable and start the systemd timer after suspending:
sudo systemctl enable --now teleport-upgrade.timer
Annotate the agent deployment with teleport.dev/skipreconcile: "true"
.
Either by setting the annotations.deployment
value in Helm, or by patching
the deployment directly with kubectl
.