Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub


Upgrade Teleport Cloud Agents on Kubernetes

  • Available for:
  • Cloud

This guide explains how to upgrade Teleport Cloud agents running on Kubernetes. 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 updates or upgrade them manually using the method you used to install Teleport.


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

  • Teleport Enterprise Cloud or Teleport Team account. You can determine the current version of these services by running the following command, where mytenant is the name of your Teleport Team or Teleport Enterprise Cloud tenant. This requires the jq CLI tool:

    curl -s | jq '.server_version'
  • The tctl and tsh client tools version >= 14.3.6.

    You can download these from Teleport Cloud Downloads.

    tctl version

    Teleport Enterprise v14.3.6 go1.21

    tsh version

    Teleport v14.3.6 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 --user=[email protected]
    tctl status


    Version 15.1.1

    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 the teleport-kube-agent Helm chart. The Automatic Update Architecture guide describes how agent updating works. Automatic agent upgrades require:

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

    curl -s | jq '.automatic_upgrades'
  • At least one Teleport Enterprise agent deployed via the teleport-kube-agent Helm chart.

Step 1/2. Determine whether any agents require automatic updates

To determine if any agents in your cluster are not configured for automatic upgrades, run the following command. This prints a list of all Teleport services with no upgrader, filtering these to ignore the Auth Service and Proxy Service (which are maintained for you in Teleport Cloud):

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 teleport-agent-0 Kube v13.4.3 none

If the list is nonempty, proceed to the next step to enable automatic updates.

Step 2/2. Enroll agents in automatic updates

This section assumes that the name of your teleport-kube-agent release is teleport-agent, and that you have installed it in the teleport namespace.

  1. Confirm you are using the Teleport Enterprise edition of the teleport-kube-agent chart. You should see the following when you query your teleport-kube-agent release:

    helm -n teleport get values teleport-agent -o json | jq '.enterprise'
  2. Add the following chart values to your existing agent values.yaml to enable the automatic updater:

      enabled: true
  3. Upgrade the Helm chart release with the new values by running helm upgrade. The command should resemble the following:

    helm -n teleport upgrade teleport-agent teleport/teleport-kube-agent \--values=values.yaml \--version=14.3.6
  4. Validate the updater is running properly by checking if its pod is ready:

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

The updater is a controller that periodically reconciles expected Kubernetes resources with those in the cluster. The updater executes a reconciliation loop every 30 minutes or in response to a Kubernetes event. 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 -n teleport annotate statefulset/teleport-agent ''

To suspend automatic updates for an agent, annotate the agent deployment with "true", either by setting the annotations.deployment value in Helm, or by patching the deployment directly with kubectl.

Manually upgrading agents

Run the following commands to upgrade Teleport agents running on Kubernetes.

  1. Update the Teleport Helm chart repository so you can install the latest version of the teleport-kube-agent chart:

    Set up the Teleport Helm repository.

    Allow Helm to install charts that are hosted in the Teleport Helm repository:

    helm repo add teleport

    Update the cache of charts from the remote repository so you can upgrade to all available releases:

    helm repo update
  2. Upgrade the Helm release:

    helm -n teleport upgrade teleport-agent teleport/teleport-kube-agent \--values=values.yaml \--version=14.3.6