Upgrade Self-Hosted Teleport Clusters on Kubernetes

This guide explains how to upgrade self-hosted Teleport clusters running on Kubernetes.

Prerequisites

• Familiarity with the Upgrading Compatibility Overview guide, which describes the sequence in which to upgrade components of your cluster.
• A self-hosted Teleport cluster in which the Auth Service and Proxy Service run on Kubernetes. This guide assumes that you have deployed the Teleport cluster using the teleport-cluster Helm chart.
• The tctl and tsh client tools version >= 15.2.4. Read Installation for how to install these.
• 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 protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.4
  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.

This guide assumes that you have configured the teleport-cluster Helm chart with a values file called values.yaml, and that your teleport-cluster release is called teleport-cluster.

Step 1/2. Shrink the Auth Service pool

You must reduce the number of Auth Service instances to one in order to ensure a consistent cluster state during the upgrade.

Ensure that your teleport-cluster values file includes the following configuration:

auth:
  highAvailability:
    replicaCount: 1

Once you have completed this guide and upgraded the cluster, you can configure your cluster for high availability again.

Step 2/2. Upgrade the Auth Service and Proxy Service

Run the following commands to upgrade Auth Service and Proxy Service instances running on Kubernetes.

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

   Set up the Teleport Helm repository.

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

   helm repo add teleport https://charts.releases.teleport.dev

   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 upgrade teleport-cluster teleport/teleport-cluster \  --version=15.2.4 \  --values=values.yaml

The teleport-cluster Helm chart automatically waits for the previous version of the Proxy Service to stop responding to requests before running a new version of the Auth Service.

Step 3/3. Upgrade 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 https://charts.releases.teleport.dev

   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=15.2.4