# 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.15.

If this describes your situation, read on!

> [!NOTE]
> This guide contains instructions to upgrade BEL using the
> CLI or Helm. If you have installed BEL's lifecycle automation operator, please
> see our [lifecycle automation upgrade guide](/buoyant-enterprise-linkerd/2.15/upgrade/operator/).

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](/buoyant-enterprise-linkerd/latest/overview/versions/).

Before upgrading, see the [release
notes](/release-notes/buoyant-enterprise-linkerd/#version=2.15)
for details about any breaking changes.

## Step 0: Get your license key

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

```bash
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:

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

Alternatively, you can download the CLI directly via the
[BEL releases page](https://github.com/BuoyantIO/linkerd-buoyant/releases?q=%22enterprise-2%22).

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

```bash
linkerd version --client
```

You should see:

```bash
Client version: enterprise-2.15.7
```

## 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:

```bash
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:

```bash
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:

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

**Upgrading from: BEL**

Now we can upgrade the chart containing Linkerd's CRDs:

```bash
helm upgrade linkerd-crds \
  --version 2.15.7 \
  --namespace linkerd \
  linkerd-buoyant/linkerd-enterprise-crds
```

Next we can upgrade the `linkerd-control-plane` chart:

```bash
helm upgrade linkerd-control-plane \
  --version 2.15.7 \
  --namespace linkerd \
  linkerd-buoyant/linkerd-enterprise-control-plane \
  --atomic
```

**Upgrading from: OSS**

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

If you’re moving from an OSS release, you'll need to create a `values.yaml` file
to use for the upgrade:

```bash
cat <<EOF > values.yaml
linkerd-crds:
$(helm get values -n linkerd linkerd-crds -oyaml | sed 's/^/  /')
EOF
```

Then use the `values.yaml` file to upgrade the `linkerd-crds` chart:

```bash
helm upgrade linkerd-crds \
  --version 2.15.7 \
  --namespace linkerd \
  --reset-then-reuse-values --values values.yaml \
  linkerd-buoyant/linkerd-enterprise-crds
```

Next we can upgrade the control plane install itself.

You'll need to add a license value to your helm values for the
`linkerd-control-plane` chart, as follows:

```bash
cat <<EOF > values.yaml
license: $BUOYANT_LICENSE
linkerd-control-plane:
$(helm get values -n linkerd linkerd-control-plane -oyaml | sed 's/^/  /')
EOF
```

Then use the `values.yaml` file to upgrade the `linkerd-control-plane` chart:

```bash
helm upgrade linkerd-control-plane \
  --version 2.15.7 \
  --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:

```bash
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:

```bash
linkerd version
```

You should see:

```bash
Client version: enterprise-2.15.7
Server version: enterprise-2.15.7
```

## 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.

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.

### Upgrading the multicluster extension

Upgrading the multicluster extension doesn't cause downtime in the traffic going
through the mirrored services. 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:

```bash
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:

```bash
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.
