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 upgrading your cluster from a BEL version or OSS version that is no more than one major version behind 2.18.

If this 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.

Prerequisites

If you are upgrading an installation of BEL where the Gateway API resources are owned by something other than Linkerd, you will need to insure that the Gateway API version is compatible with Linkerd before proceeding.

If you are upgrading BEL using the CLI, and you do not have the Gateway API resources installed on your cluster (this should be rare), you will either need to install the Gateway API resources first, or ensure that you explicitly instruct Linkerd to install the Gateway API resources using the --set installGatewayAPI=true flag when upgrading Linkerd’s CRDs.

To install the Gateway API resources yourself, run:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml

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.18.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 (optionally using the --set installGatewayAPI=true 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 upgrade linkerd-crds \
  --namespace linkerd \
  linkerd-buoyant/linkerd-enterprise-crds

Next we can upgrade the control plane install itself.

helm upgrade linkerd-control-plane \
  --namespace linkerd \
  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 linkerd-control-plane \
  --namespace linkerd \
  --reset-then-reuse-values --values values.yaml \
  linkerd-buoyant/linkerd-enterprise-control-plane \
  --atomic

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.18.0
Server version: enterprise-2.18.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

To upgrade to the new GitOps-compatible multicluster links in 2.18, you will need to follow these steps:

Start by creating values.yaml file that contains the controllers value listing the links you want to migrate, and declaring any specific config for those controllers. For example:

controllers:
  - link:
      ref:
        name: east

Next update the multicluster extension, providing the values.yaml:

linkerd multicluster install -f values.yaml | \
    kubectl apply -f -

helm upgrade linkerd-multicluster \
  --namespace linkerd-multicluster \
  --values values.yaml \
  linkerd-buoyant/linkerd-enterprise-multicluster

This will deploy a new controller for each link (named controller-<link-name>), while leaving the old controllers (named linkerd-service-mirror-<link-name>) in place. The new controllers won’t do anything yet because the old controllers will hold the Lease object for each Link.

To fully migrate to the new model, delete the old controller deployments and their associated resources, calling for each link:

linkerd multicluster unlink --cluster-name <link-name> --only-controller |
	kubectl delete -f -

After a few seconds the new controllers will reclaim the Lease object and start managing those links.

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.