Teleport

Enroll an agent into automatic updates

Available for:
Enterprise
Cloud
Team

Teleport supports automatic agent updates for systemd-based Linux distributions using apt, yum, or zypper 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

Automatic agent update is available starting from Teleport 13.0.

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 Cloud Tenant is enrolled into automatic updates.

Enroll instructions

If you have a Teleport Enterprise Cloud account, you can find agents that need to be enrolled using tctl inventory ls like so:

tctl inventory ls --upgrader=none
Server ID                            Hostname          Services Version Upgrader------------------------------------ ----------------- -------- ------- --------4fb2d97d-884a-4566-b477-c805d477df09 agent.example.com Node     v1.2.3  none...

If you have a lot of agents on different versions and want to prioritize enrolling your oldest agents, you can limit your search using the --older-than filter:

tctl inventory ls --upgrader=none --older-than=v1.2.3
Server ID                            Hostname        Services Version Upgrader------------------------------------ --------------- -------- ------- --------1e6578b6-9530-448e-8013-d32641324abb old.example.com Node     v1.1.1  none...

Cluster Type

Step 1/3. Ensure the Teleport repository is added and Teleport Enterprise is installed

To verify if the Teleport repository was added to the system, check if either of the follow files exist:

ls /etc/apt/sources.list.d/teleport.list
or
ls /etc/yum.repos.d/teleport.repo

If the Teleport repository is not found, add the appropriate repository and reinstall Teleport:

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

Step 2/3. Configure the updater

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.

Step 3/3. Verify updater is properly configured

Verify that the updater can see your version endpoint by checking for updates:

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<your-agent-release>-0                         1/1     Running   0          14m<your-agent-release>-1                         1/1     Running   0          14m<your-agent-release>-2                         1/1     Running   0          14m<your-agent-release>-updater-d9f97f5dd-v57g9   1/1     Running   0          16m

And by consulting its logs:

kubectl logs deployment/<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\")"}

Step 1/3. Ensure the Teleport repository is added and Teleport Enterprise is installed

To verify if the Teleport repository was added to the system, check if either of the follow files exist:

ls /etc/apt/sources.list.d/teleport.list
or
ls /etc/yum.repos.d/teleport.repo

If the Teleport repository is not found, add the appropriate repository and reinstall Teleport:

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

Step 2/3. Configure the updater

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

Step 3/3. Verify updater is properly configured

Verify that the updater can see your version endpoint by checking for updates:

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   AGEmy-agent-0                         1/1     Running   0          14mmy-agent-1                         1/1     Running   0          14mmy-agent-2                         1/1     Running   0          14mmy-agent-updater-d9f97f5dd-v57g9   1/1     Running   0          16m

And by consulting its logs:

kubectl logs deployment/<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 deployment/<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.