Considerations

Before you upgrade your ambient components, review the following limitations and recommendations.

Revision and canary upgrade limitations

Due to an upstream ambient limitation, the ztunnel and Istio CNI pods do not support revisioned canary upgrades, and can only be upgraded in-place. For this reason, creating named revisions for the istiod, cni, ztunnel, and gateways in an ambient mesh is not currently recommended, and the upgrade guides in this documentation set show you how to perform in-place upgrades only.

CNI upgrades

In an ambient installation, the istio-cni pods are enhanced for safe in-place upgrades. When istio-cni is scheduled for removal, it determines whether an upgrade is in process by checking the value of AGENT_UPGRADE_ID in the istio-cni ConfigMap against its internal upgrade ID. If the removal is due to an upgrade, istio-cni creates a “stub” CNI plug-in in its place on the node. This stub CNI plug-in stalls any newly scheduled pods on that node, and does not allow the pods to spin up until the replacement istio-cni is up and running.

ztunnel upgrades

As Kubernetes dynamically upgrades the ztunnel deployment by restarting the old ztunnel pods, all long-lived connections on the node are dropped. You can influence the duration of the downtime with the termination grace period of the ztunnel pod, which determines the drain period. Any TCP connections that are longer than the grace period are dropped. Alternatively, you might cordon nodes and use blue/green node pools to limit the number of active pods that are in the process of upgrading.

Version and license requirements

Single cluster setups:

  • In Gloo Mesh Core version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (1.22.3-solo).
  • In Istio 1.22.0-1.22.3, the ISTIO_DELTA_XDS environment variable must be set to false. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.

Multicluster ambient setups:

  • In Gloo Mesh version 2.7 and later, multicluster ambient setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo), including the Solo distribution of istioctl.
  • A Gloo Mesh Enterprise license. If you do not have one, contact an account representative.

Upgrade istioctl

  1. Save the version that you want to upgrade to in the following environment variables, such as the following examples for 1.24. You can find these values in the Ambient section of the Istio images built by Solo.io support article.

      # Solo distrubution of Istio patch version to upgrade to
# in the format 1.x.x, with no tags
export ISTIO_VERSION=1.24.2
# Repo key for the minor version of the Solo distribution of Istio
# This is the 12-character hash at the end of the repo URL: 'us-docker.pkg.dev/gloo-mesh/istio-<repo-key>'
export REPO_KEY=<repo_key>

# Solo distrubution of Istio patch version and tag,
# image repo, Helm repo, and binary repo
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
export BINARY_REPO=https://console.cloud.google.com/storage/browser/istio-binaries-${REPO_KEY}/${ISTIO_IMAGE}

  2. Upgrade your istioctl CLI client to the new version.

      curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
cd istio-${ISTIO_VERSION}
export PATH=$PWD/bin:$PATH

    Download the Solo distribution of Istio binary and install istioctl, which you use for multicluster linking and gateway commands.

    1. Navigate to the storage repository for the Solo distribution of Istio binaries.
        open ${BINARY_REPO}
    2. Download the tar.gz file for your system, such as istio-1.24.2-solo-osx-amd64.tar.gz.
    3. Extract the downloaded tar.gz file.
    4. Navigate to the package directory and add the istioctl client to your system’s PATH.
        cd istio-${ISTIO_IMAGE}
export PATH=$PWD/bin:$PATH
    5. Verify that the istioctl client runs the Solo distribution of Istio that you want to install.
        istioctl version --remote=false
      Example output:
        client version: 1.24.2-solo

Upgrade CRDs and istiod

  1. Upgrade the Istio CRDs to the new version.

      helm get values istio-base -n istio-system -o yaml > istio-base.yaml
helm upgrade istio-base oci://${HELM_REPO}/base \
--namespace istio-system \
--create-namespace \
--version ${ISTIO_IMAGE} \
-f istio-base.yaml

  2. Get the current values for the istiod Helm release in your cluster.

      helm get values istiod -n istio-system -o yaml > istiod.yaml
open istiod.yaml

  3. Make edits to the istiod Helm values, and save the file. If you update the Istio minor version, such as in the global.tag field, be sure to also update the value of the hub field to the repo for the correct version of the Solo distribution of Istio.

  4. Upgrade your Helm release with the updated values.

      helm upgrade istiod oci://${HELM_REPO}/istiod \
-n istio-system \
--version ${ISTIO_IMAGE} \
-f istiod.yaml

  5. Verify that the istiod pods are successfully restarted. Note that it might take a few seconds for the pods to become available.

      kubectl get pods -n istio-system | grep istiod

    Example output:

      istiod-b84c55cff-tllfr   1/1     Running   0          58s

Upgrade the CNI and ztunnel

  1. For the component that you want to update, get the current values for its Helm release in your cluster.

      helm get values istio-cni -n istio-system -o yaml > cni.yaml
open cni.yaml
  
      helm get values ztunnel -n istio-system -o yaml > ztunnel.yaml
open ztunnel.yaml
  
      helm get values istio-cni -n kube-system -o yaml > cni.yaml
open cni.yaml
  
      helm get values ztunnel -n kube-system -o yaml > ztunnel.yaml
open ztunnel.yaml

  2. Make edits to the Helm values of the components that you want to upgrade, and save the files. If you update the Istio minor version, such as in tag fields, be sure to also update the value of the hub field to the repo for the correct version of the Solo distribution of Istio.

  3. Upgrade your Helm releases with the updated values.

      helm upgrade istio-cni oci://${HELM_REPO}/cni -n istio-system --version ${ISTIO_IMAGE} -f cni.yaml
  
      helm upgrade ztunnel oci://${HELM_REPO}/ztunnel -n istio-system --version ${ISTIO_IMAGE} -f ztunnel.yaml
  
      helm upgrade istio-cni oci://${HELM_REPO}/cni -n kube-system --version ${ISTIO_IMAGE} -f cni.yaml
  
      helm upgrade ztunnel oci://${HELM_REPO}/ztunnel -n kube-system --version ${ISTIO_IMAGE} -f ztunnel.yaml

  4. Verify that the ztunnel and Istio CNI pods are successfully restarted. Note that it might take a few seconds for the pods to become available.

      kubectl get pods -n istio-system
  
      kubectl get pods -n kube-system

    Example output:

      istiod-85c4dfd97f-mncj5            1/1     Running   0             42s
istio-cni-node-pr5rl               1/1     Running   0             42s
istio-cni-node-pvmx2               1/1     Running   0             42s
istio-cni-node-lcrcd               1/1     Running   0             42s
ztunnel-tvtzn                      1/1     Running   0             40s
ztunnel-vtpjm                      1/1     Running   0             40s
ztunnel-hllxg                      1/1     Running   0             40s

Repeat for multicluster setups

If you linked ambient service meshes across multiple clusters, repeat these steps for each cluster in your setup. Note that no multicluster components, such as the east-west gateway or global service entries, require upgrades when you update the version of your other control and data plane components.