Skip to main content
Version: 14.x

Upgrade Teleport Cloud Agents on Linux

This guide explains how to upgrade Teleport Cloud agents running on Linux servers. On Teleport Cloud, Auth Service and Proxy Service upgrades are managed for you. To keep agents up to date, you can either enroll them in automatic upgrades or upgrade them manually using the method you used to install Teleport.

Prerequisites​

  • Familiarity with the Upgrading Compatibility Overview guide, which describes the sequence in which to upgrade components in your cluster.

  • A Teleport Enterprise Cloud account. You can determine the current version of the Auth Service and Proxy Service by running the following command, where mytenant is the name of your Teleport Enterprise Cloud account. This requires the jq CLI tool:

    $ curl -s https://mytenant.teleport.sh/webapi/ping | jq '.server_version'

  • The tctl and tsh client tools version >= 16.4.7.

    The tctl and tsh client tools version >= 16.4.7. To install these tools, see the Installation page.

    $ tctl version
    # Teleport Enterprise v16.4.7 go1.21

    $ tsh version
    # Teleport v16.4.7 go1.21

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines.

    For example:

    $ tsh login --proxy=teleport.example.com --user=email@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Teleport supports automatic agent updates for systemd-based Linux distributions using apt, yum, and zypper package managers. The Automatic Update Architecture guide describes how agent updating works. Automatic agent upgrades require:

  • A Teleport Cloud account that supports automatic upgrades. To determine if your account supports automatic upgrades, run the following command, replacing mytenant.teleport.sh with the address of your Teleport Cloud account:

    $ curl -s https://mytenant.teleport.sh/webapi/ping | jq '.automatic_upgrades'
    true

  • At least one Teleport Enterprise agent, started via systemd on a distribution using the apt or yum package managers.

    So you can access each agent, we assume that each agent runs the Teleport SSH Service in addition to any other services. See the Deploy Teleport Agents with Terraform guide for an example.

Step 1/2. Find agents to upgrade​

To list agents that are not enrolled in automatic upgrades, use the tctl inventory ls command with the --upgrader=none flag. This command also uses the --services flag to constrain the search to Teleport processes running agent services:

$ tctl inventory ls \
  --services=node,kube,db,app,windows_desktop,discovery,okta \
  --upgrader=none
Server ID                            Hostname      Services Version Upgrader
------------------------------------ ------------- -------- ------- --------
00000000-0000-0000-0000-000000000000 ip-10-1-6-130 Node     v13.4.5 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
------------------------------------ --------------- -------------- ------- --------
00000000-0000-0000-0000-000000000000 old.example.com Node           v1.1.1  none
00000000-0000-0000-0000-000000000001 teleport-proxy  Proxy          v14.3.6 none
00000000-0000-0000-0000-000000000002 teleport-auth   Auth,Discovery v14.3.6 none
...

Note that the inventory ls command will also list teleport-auth and teleport-proxy services. You do not need to update these services or enroll them in automatic updates. Teleport Cloud manages updates for these services.

When you enroll each agent in automatic updates in the next section, you can run the following commands to fetch the hostname for each agent and access it via Teleport.

For each agent ID returned by the tctl inventory ls command, copy the ID and run the following tctl command to access the host via tsh:

$ HOST=00000000-0000-0000-0000-000000000000
$ USER=root
$ tsh ssh "${USER?}@${HOST?}"

You can then follow the steps in the next section on each agent to enroll it in automatic upgrades.

Step 2/2. Enroll agents in automatic upgrades​

Complete the following instructions on each agent you would like to enroll into automatic upgrades:

  1. 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 exists:

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

    The upgrader checks the repository for available releases, so make sure that it is up to date.

  2. If the repository was added, make sure the Teleport binary installed on the agent can run the automatic upgrader:

    $ which teleport-upgrade || echo "Install the upgrader"
    Install the upgrader

  3. If the Teleport repository is not found, or the Teleport binary you installed does not include the upgrader, 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

    # Provide your Teleport domain to query the latest compatible Teleport version
    $ export TELEPORT_DOMAIN=example.teleport.com
    $ export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    # Update the repo and install Teleport and the Teleport updater
    $ sudo apt-get update
    $ sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

  4. If you changed the agent user to run as non-root, create /etc/teleport-upgrade.d/schedule and grant ownership to your Teleport user. Otherwise, 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

  5. Verify that the upgrader 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)

    The upgrader may display warnings about not having a valid upgrade schedule. This is expected immediately after install as the maintenance schedule might not be exported yet.

  6. Ensure that the upgrader is running:

    $ sudo systemctl status teleport-upgrade

Troubleshooting​

If the agent is not automatically updated, you can invoke the upgrader manually and look at its logs:

$ sudo teleport-upgrade run

To suspend automatic upgrades, 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