Teleport

Enroll an agent into automatic updates (Preview)

Enterprise
Cloud

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 or yum package managers
- deployed with the teleport-kube-agent Helm chart
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 or yum package managers
- deployed with the teleport-kube-agent Helm chart
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 version
Teleport 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/schedule
sudo 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

Note

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-updater
or
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)

Note

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 pods
NAME                               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>-updater
2023-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 version
Teleport 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/schedule
sudo 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-updater
or
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)

Note

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 pods
NAME                               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>-updater
2023-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

Note

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.

Have a suggestion or can’t find something?

IMPROVE THE DOCS