Perform an upgrade#

Overview#

Introduction#

The following instructions describe how to perform an upgrade of Aspen Mesh. Perform the tasks in order.

If you want to perform a clean installation instead, see Perform a clean installation.

Note

Only upgrades from Aspen Mesh 1.18 to 1.18 are supported. Upgrades from Aspen Mesh 1.14 to 1.18 are not supported.

Types of upgrades#

You can perform the following types of upgrades:

Upgrade type	Description
Single-stack-to-single-stack	Upgrade from an Aspen Mesh version in IPv4 single-stack mode in a single-stack cluster (a cluster with IPv4 single-stack networking enabled) to a later Aspen Mesh version in single-stack mode in a single-stack cluster.
Dual-stack-to-dual-stack	Upgrade from an Aspen Mesh version in IPv4/IPv6 dual-stack mode in a dual-stack cluster (a cluster with IPv4/IPv6 dual-stack networking enabled) to a later Aspen Mesh version running in dual-stack mode in a dual-stack cluster.

Prepare to upgrade#

Before you begin#

Back up your Aspen Mesh configuration:

$ kubectl get crds | grep 'istio.io' | \
    cut -f1-1 -d "." | \
    xargs -n1 -I{} sh -c "kubectl get --all-namespaces -o yaml {}; echo ---" > $HOME/ASPEN_MESH_CONFIG_BACKUP.yaml

Uninstall Packet Inspector 1 and 2#

Important

To ensure a successful upgrade, you must uninstall Packet Inspector 1 and 2 if you previously installed them.

Uninstall Packet Inspector:
- Uninstall Packet Inspector 1.
- Uninstall Packet Inspector 2.

Prepare the release#

Download the Aspen Mesh release archive file (for example, aspenmesh-carrier-grade-1.18.7-am1-linux.tar.gz).

To manually download the release, go to Releases and click or tap the download link. You can also automate downloading. Learn how to download Aspen Mesh using a script.
In the same directory as the Aspen Mesh release archive file, download the corresponding hash file (for example, aspenmesh-carrier-grade-1.18.7-am1-linux.tar.gz.sha256).

Go to Releases and click or tap the hash link.
In the same directory, verify the integrity of the release archive file by generating its hash and comparing it with the hash in the hash file:
```
$ sha256sum -c <hashFilename>
```
If the verification failed, repeat the preceding steps; otherwise, go to step 5.
In the same directory, extract the Aspen Mesh release archive file.
```
$ tar xzvf <releaseArchiveFilename>
```

Add the location of the istioctl client to your path#

Change to the Aspen Mesh release directory (for example, aspenmesh-carrier-grade-1.18.7-am1).
Add the location of the istioctl client, located in the bin directory, to the PATH environment variable.
```
$ export PATH=$PWD/bin:$PATH
```
Verify that the istioctl client is in your path:
```
$ which istioctl
```
Make sure you can run istioctl by checking its version:
```
$ istioctl version
```
Note

If you get an error message that says the binary file can’t be executed, the release archive file you downloaded may be for a different operating system than the one on your computer. To easily fix this, download and extract the release archive file for your computer’s operating system (make sure it’s the same version). Then copy its bin/istioctl file to the same location in the Aspen Mesh release directory that you’ve been working in.

Store Aspen Mesh container images in a private artifact registry#

If you want to store Aspen Mesh container images in a private artifact registry instead of the Aspen Mesh artifact registry, do that now.

For instructions and information on when you might want to do this, see Store Aspen Mesh container images in a private artifact registry.

Perform an upgrade#

Upgrade the control-plane dependencies#

Pause all application deployments and configuration changes to your cluster.

Cluster updates may fail while the installation is in progress.
Change to the Aspen Mesh release directory.
Upgrade the Istio custom resource definitions (CRDs):
```
$ kubectl apply -f manifests/charts/base/crds
```

Upgrade the cluster-wide objects used by the Istio control plane:

$ helm upgrade istio-base \
    --namespace istio-system \
    --skip-crds manifests/charts/base \
    --wait

Verify that the Istio CRDs were committed to the Kubernetes or OpenShift API server:
```
$ kubectl get crds | grep 'istio.io'
```
The output of the command should include the following CRDs:
- authorizationpolicies.security.istio.io
- destinationrules.networking.istio.io
- envoyfilters.networking.istio.io
- gateways.networking.istio.io
- istiooperators.install.istio.io
- peerauthentications.security.istio.io
- proxyconfigs.networking.istio.io
- requestauthentications.security.istio.io
- serviceentries.networking.istio.io
- sidecars.networking.istio.io
- telemetries.telemetry.istio.io
- virtualservices.networking.istio.io
- wasmplugins.extensions.istio.io
- workloadentries.networking.istio.io
- workloadgroups.networking.istio.io

(OpenShift only) Upgrade the Istio CNI plugin#

Important

Perform this task only if you’re performing an upgrade in an OpenShift cluster.

Upgrade the Istio CNI plugin:

$ helm upgrade istio-cni manifests/charts/istio-cni \
    --namespace kube-system \
    --wait

Upgrade the control plane and gateway components#

Copy your Aspen Mesh override values file (aspen-mesh-override-values.yaml) to the Aspen Mesh release directory.

Upgrade the Istio control plane:

$ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

Upgrade the Istio ingress gateway components, making sure to replace <ingressNamespaceName> with the name of the namespace to use for these components:

$ helm upgrade istio-ingress manifests/charts/gateways/istio-ingress \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml

If you’re using the Istio egress gateway, upgrade the Istio egress gateway components, making sure to replace <egressNamespaceName> with the name of the namespace to use for these components:
```
$ helm upgrade istio-egress manifests/charts/gateways/istio-egress \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml
```

Verify that all Aspen Mesh components have been upgraded to the expected version#

Verify that all Aspen Mesh components have been upgraded to the expected version:
```
$ helm list --filter 'istio' -A
```

Upgrade your sidecars#

Upgrade all manually injected sidecars, as in this example for a deployment:

$ kubectl apply -f < (istioctl kube-inject -f <deploymentManifestFilename>)

In each namespace in which automatic sidecar injection should occur, restart all pods with sidecars:

$ kubectl delete pods \
    --namespace <namespaceName> \
    --selector security.istio.io/tlsMode=istio \
    --wait

Verify that your sidecars and gateways are using the new Istio proxy version#

Determine the version of the Istio proxy (Envoy) for each pod and gateway in the mesh:
```
$ istioctl proxy-status
```
Do any objects in the output show an Istio proxy version (in the VERSION field) that is different from the version of Aspen Mesh that you’re upgrading to?
- Yes:
  - If the object is a gateway, make sure it has been upgraded (see the relevant (ingress or egress) step in Upgrade the control plane and gateway components).
  - If the object is a pod, upgrade its sidecar (see the relevant (manual or automatic) step in Upgrade your sidecars).
  - Go to step 1.
- No:
  - Stop. All pods and gateways in the mesh are using the correct version of the Istio proxy.

Verify that the upgrade was successful#

Verify that traffic is flowing between applications as expected.

Upgrade or install optional companion products#

Introduction#

The Aspen Mesh release archive file includes optional companion products that are installed and upgraded separately from Aspen Mesh.

Upgrade optional companion products#

If you’re using any of the Aspen Mesh companion products that are upgradable, upgrade them now. See the following sections:

Install optional companion products#

If you want to use any of the Aspen Mesh companion products that aren’t upgradable, install them now. See the following sections: