
Teleport
Enroll an agent into automatic updates
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- 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
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 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=noneServer 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.3Server ID Hostname Services Version Upgrader------------------------------------ --------------- -------- ------- --------1e6578b6-9530-448e-8013-d32641324abb old.example.com Node v1.1.1 none...
Cluster Type
- Self-hosted
- Teleport Cloud
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.listor
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.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd 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-utilssudo 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-updaterTip: 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-releaseAdd 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-updaterTip: 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-releaseAdd 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/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.
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)
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<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>-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\")"}
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.listor
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.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd 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-utilssudo 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-updaterTip: 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-releaseAdd 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-updaterTip: 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-releaseAdd 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/schedulesudo 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)
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 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>-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 deployment/<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
.