Fork me on GitHub

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.