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.

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.
Single-stack-to-dual-stack (from 1.11.5-am1 or later to 1.11.8-am2 or later)	First, 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. Then enable IPv4/IPv6 dual-stack networking for Aspen Mesh and the cluster. This staged approach ensures your applications remain available throughout the upgrade and conversion to dual-stack networking.
Dual-stack-to-dual-stack (from 1.11.8-am2 or later to 1.11.8-am3 or later)	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#

Decide which type of upgrade you want to perform.

Use this table to determine which Aspen Mesh versions are eligible and which tasks you should complete for the type of upgrade you want to perform:

If you want to perform this type of upgrade	Then your current version of Aspen Mesh must be	And you can upgrade to this version of Aspen Mesh	And you should complete all tasks
Single-stack-to-single-stack	Any version	Any later version	Except those marked “(Single-stack-to-dual-stack upgrade only).”
Single-stack-to-dual-stack	1.11.5-am1 or later	1.11.8-am2 or later	Including those marked “(Single-stack-to-dual-stack upgrade only).”
Dual-stack-to-dual-stack	1.11.8-am2 or later	1.11.8-am3 or later	Except those marked “(Single-stack-to-dual-stack upgrade only).”

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

In case the upgrade fails and must be rolled back, save a list of all Helm releases in the istio-system namespace:
```
$ helm ls --namespace istio-system > $HOME/ASPEN_MESH_HELM_RELEASES_BACKUP
```

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.

Is your current version of Aspen Mesh 1.11?
- Yes:
  - Uninstall Packet Inspector 1 (1.11 version).
  - Uninstall Packet Inspector 2 (1.11 version).
- No:
  - Uninstall Packet Inspector 1.
  - Uninstall Packet Inspector 2.

Prepare the release#

Download the Aspen Mesh release archive file (for example, aspenmesh-carrier-grade-1.14.5-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.14.5-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.14.5-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 image registry#

If you want to store the Aspen Mesh container images in a private image registry instead of the Aspen Mesh image 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 image 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

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
- requestauthentications.security.istio.io
- serviceentries.networking.istio.io
- sidecars.networking.istio.io
- telemetries.telemetry.istio.io
- virtualservices.networking.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 \
    --set components.cni.enabled=true

Upgrade the control plane and gateway components#

Upgrade the Istio control plane, making sure to replace <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values <aspenMeshOverrideValuesFilename>
```
Upgrade the Istio ingress gateway components, making sure to replace <ingressNamespaceName> with the name of the namespace to use for these components and <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm upgrade istio-ingress manifests/charts/gateways/istio-ingress \
    --namespace <ingressNamespaceName> \
    --values <aspenMeshOverrideValuesFilename>
```
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 and <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm upgrade istio-egress manifests/charts/gateways/istio-egress \
    --namespace <egressNamespaceName> \
    --values <aspenMeshOverrideValuesFilename>
```

Upgrade all Istio proxies#

Reinject 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 is enabled or an Istio gateway resides, restart all pods with Istio proxies:
```
$ kubectl delete pods \
    --namespace <namespaceName> \
    --selector security.istio.io/tlsMode=istio
```

Verify that the upgrade was successful#

Verify that traffic is flowing between applications as expected.

(Single-stack-to-dual-stack upgrade only) Enable dual-stack networking#

Enable dual-stack networking#

Perform the tasks in Enable dual-stack networking.

(Single-stack-to-dual-stack upgrade only) Verify dual-stack functionality and configure your services#

Verify dual-stack functionality and configure your services#

Perform the tasks in Verify dual-stack functionality and configure your services.

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: