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

These instructions support only upgrades from Aspen Mesh 1.21 to 1.21. They do not support upgrades from earlier minor versions of Aspen Mesh, such as 1.14 or 1.18.

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#

  1. Make sure your computer has access to your cluster using kubectl.

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

  3. Download the Aspen Mesh Platform chart for your server’s operating system (for example, f5-aspen-mesh-platform-linux) and for the version of Aspen Mesh that you want to upgrade to (for example, 1.21.6-am2).

    You can also automate downloading. Learn how to download an Aspen Mesh Platform chart using a script.

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.

Add the location of the istioctl client to your path#

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to—for example, f5-aspen-mesh-platform-linux-1.21.6-am2).

  2. Add the location of the istioctl client, located in the bin directory, to the PATH environment variable.

    $ export PATH=$PWD/bin:$PATH

  3. Verify that the istioctl client is in your path:

    $ which istioctl

  4. Make sure you can run istioctl by checking its version:

    $ istioctl version

  5. If you get an error message that says the binary file can’t be executed, repeat the steps in Download an Aspen Mesh Platform chart, making sure to specify the chart for your computer’s operating system, then go to step 1 of this task.

(Private artifact registry only) Store Helm charts and Docker container images in a private artifact registry#

Log in to the appropriate artifact registry with Helm and set the repository address#

Copy your Aspen Mesh override values file#

  • Copy the Aspen Mesh override values file for the old version (the version you’re upgrading from) to the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to).

Update your Aspen Mesh override values file with any new fields that are required or that you want to override#

Follow these steps for each of the Aspen Mesh Helm charts (base, cni, istiod, istio-egress, and istio-ingress).

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to).

  2. Set the AM_TAG environment variable to the old version of the Aspen Mesh chart (the version you’re upgrading from).

    Example

    $ export AM_TAG=1.21.6-am1

  3. Copy the old chart’s values.yaml file to a temporary file:

    $ helm show values oci://$AM_REPO/charts/<chartName> --version $AM_TAG > <chartName>-values-old.yaml

  4. Set the AM_TAG environment variable to the new version of the Aspen Mesh chart (the version you want to upgrade to).

    Example

    $ export AM_TAG=1.21.6-am2

  5. Copy the new chart’s values.yaml file to a temporary file:

    $ helm show values oci://$AM_REPO/charts/<chartName> --version $AM_TAG > <chartName>-values-new.yaml

  6. Compare the new temporary file with the old temporary file:

    $ diff <chartName>-values-new.yaml <chartName>-values-old.yaml

  7. If there are any new fields that are required or that you want to override:

    • Open the Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

    • Copy the fields to the override values file and change their values if you want to override them.

    • Save and close the file.

  8. Delete the temporary files:

    $ rm <chartName>-values-old.yaml <chartName>-values-new.yaml

Perform an upgrade#

Set the version of Aspen Mesh you want to upgrade to#

  • Set the AM_TAG environment variable to the version of Aspen Mesh you want to upgrade to.

    Example

    $ export AM_TAG=1.21.6-am2

Upgrade the control-plane dependencies#

  1. Pause all application deployments and configuration changes to your cluster.

    Cluster updates may fail while the upgrade is in progress.

  2. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to).

  3. Download the Aspen Mesh base chart archive file:

    $ helm pull oci://$AM_REPO/charts/base --version $AM_TAG

  4. Extract the Aspen Mesh base chart archive file:

    $ tar xvf <chartArchiveFilename>

  5. Upgrade the Istio custom resource definitions (CRDs):

    $ kubectl apply -f base/crds

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

    Kubernetes

    $ helm upgrade istio-base oci://$AM_REPO/charts/base --version $AM_TAG \
    --namespace istio-system \
    --skip-crds \
    --wait

    OpenShift

    $ helm upgrade istio-base oci://$AM_REPO/charts/base --version $AM_TAG \
    --namespace istio-system \
    --skip-crds \
    --set profile=openshift \
    --wait

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

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

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to).

  2. Upgrade the Istio CNI plugin:

    $ helm upgrade istio-cni oci://$AM_REPO/charts/cni --version $AM_TAG \
    --namespace kube-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

Upgrade the control plane and gateway components#

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory for the new version (the version you want to upgrade to).

  2. Upgrade the Istio control plane:

    Kubernetes

    $ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm upgrade istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

  3. Upgrade the Istio ingress gateway components:

    Kubernetes

    $ helm upgrade istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm upgrade istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

  4. If you’re using the Istio egress gateway, upgrade the Istio egress gateway components:

    Kubernetes

    $ helm upgrade istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm upgrade istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

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 all Istio proxies#

  1. Reinject all manually injected sidecars, as in this example for a deployment:

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

  2. 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 \
    --wait

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

  1. Determine the version of the Istio proxy (Envoy) for each on-mesh non-gateway pod and Istio gateway pod:

    $ istioctl proxy-status

  2. If 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:

Verify that the upgrade was successful#

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