Upgrading BEL

In this guide, we’ll walk you through how to perform a zero-downtime upgrade for Buoyant Enterprise for Linkerd. This guide covers two scenarios:

1. You are upgrading your cluster from an earlier BEL version; or
2. You are upgrading your cluster to BEL from open source Linkerd.

If either of those options describes your situation, read on!

All BEL stable releases follow semantic versioning rules, which use version numbers to describe the degree of change and level of risk involved in an upgrade. To understand BEL stable version numbering, please see Releases and Versions.

Step 0: Get your license key

BEL requires a valid license key to run, which is freely available through the Buoyant portal. If you don’t already have a license key, follow the instructions there, and you should end up with an environment variable like this:

export BUOYANT_LICENSE=[LICENSE]

The commands below require that you have this environment variable set.

Step 1: Upgrading the CLI tool

The first step is to download and install the updated BEL CLI:

curl --proto '=https' --tlsv1.2 -sSfL https://enterprise.buoyant.io/install | sh

Alternatively, you can download the CLI directly via the BEL releases page.

Verify that the CLI is installed and running the expected version with:

linkerd version --client

You should see:

Client version: enterprise-2.17.0

Step 2: Upgrading the control plane

With the CLI

For users who have installed Linkerd via the CLI, the linkerd upgrade command will upgrade the control plane. This command ensures that all of the control plane’s existing configuration and TLS secrets are retained.

First upgrade Linkerd’s CRDs using the --crds flag, then upgrade the control plane itself:

linkerd upgrade --crds | kubectl apply -f -
linkerd upgrade        | kubectl apply -f -

Next, use the linkerd prune command to remove any resources that were present in the previous version but should not be present in this one:

linkerd prune | kubectl delete -f -

With Helm

For users who have installed Linkerd via Helm, the linkerd-buoyant Helm repo provides the necessary Helm charts for upgrade.

Start by adding/updating the linkerd-buoyant repo:

helm repo add linkerd-buoyant https://helm.buoyant.cloud
helm repo update linkerd-buoyant

Now we can upgrade the chart containing Linkerd’s CRDs.

helm get values -n linkerd linkerd-crds -oyaml |
  yq eval '. + .linkerd-crds | del(.linkerd-crds)' \
  > values.yaml

Upgrade the linkerd-crds chart (optionally providing the values.yaml from above with the -f flag):

helm upgrade linkerd-crds -n linkerd linkerd-buoyant/linkerd-enterprise-crds

Now we can upgrade the control plane install itself.

helm get values -n linkerd linkerd-control-plane -oyaml |
  yq eval '. + .linkerd-control-plane | del(.linkerd-control-plane)' \
  > values.yaml

helm upgrade linkerd-control-plane \
  -n linkerd \
  -f values.yaml \
  linkerd-buoyant/linkerd-enterprise-control-plane \
  --atomic

cat <<EOF > values.yaml
license: $BUOYANT_LICENSE
$(helm get values -n linkerd linkerd-control-plane -oyaml)
EOF

helm upgrade -n linkerd linkerd-control-plane \
  -f values.yaml \
  linkerd-buoyant/linkerd-preview-control-plane \
  --atomic

For additional information about managing your values.yaml file across upgrades, see the Upgrading with Helm documentation.

The --atomic flag will ensure that all changes are rolled back in case the upgrade operation fails.

Verifying the control plane upgrade

After the upgrade, run the health checks:

linkerd check

This will run through a set of checks against your control plane and make sure that it is operating correctly.

To verify the Linkerd control plane version, run:

linkerd version

You should see:

Client version: enterprise-2.17.0
Server version: enterprise-2.17.0

Step 3: Upgrading extensions

Linkerd’s extensions provide additional functionality to Linkerd in a modular way. Generally speaking, extensions are versioned separately from Linkerd releases and follow their own schedule; however, some extensions are updated alongside Linkerd releases and you may wish to update them as part of the same process.

Each extension can be upgraded independently. If using Helm, the procedure is similar to the control plane upgrade, using the respective charts. For the CLI, the extension CLI commands don’t provide upgrade subcommands, but using install again is fine. For example:

linkerd viz install          | kubectl apply -f -
linkerd multicluster install | kubectl apply -f -
linkerd jaeger install       | kubectl apply -f -

Most extensions also include a prune command for removing resources which were present in the previous version but should not be present in the current version. For example:

linkerd viz prune | kubectl delete -f -

Upgrading the multicluster extension

Upgrading the multicluster extension doesn’t cause downtime in the traffic going through the mirrored services, unless otherwise noted in the version-specific notes below. Note however that for the service mirror deployments (which control the creation of the mirrored services) to be updated, you need to re-link your clusters through linkerd multicluster link.

Step 4: Upgrading the data plane

Upgrading the data plane requires updating the proxy added to each meshed workload. Since pods are immutable in Kubernetes, Linkerd is unable to simply update the proxies in place. Thus, the standard option is to restart each workload, allowing the proxy injector to inject the latest version of the proxy as they come up.

For example, you can use the kubectl rollout restart command to restart a meshed deployment:

kubectl -n <namespace> rollout restart deploy

A skew of one major version between data plane and control plane is always supported. Thus, for some systems it is possible to do this data plane upgrade “lazily”, and simply allow workloads to pick up the newest proxy as they are restarted for other reasons (e.g. for new code rollouts). However, newer features may only be available on workloads with the latest proxy.

A skew of more than one major version between data plane and control plane is not supported.

Verify the data plane upgrade

Check to make sure everything is healthy by running:

linkerd check --proxy

This will run through a set of checks to verify that the data plane is operating correctly, and will list any pods that are still running older versions of the proxy.

Congratulations! You have successfully upgraded to the latest version of BEL.