Considerations

Feature maturity

Version requirements

  1. Verify that the minor version of the Solo distribution of Istio that you want to upgrade to is tested and supported for your Gloo Mesh version. To find the available patch versions, you can get the minor version repo URL from the Istio images built by Solo.io support article, and check the patch version builds in that repo.

  2. Check the Istio release notes for the upgrade version to prepare for any breaking changes.

  3. Be sure to review the following known Istio version restrictions.

Before you begin

  1. Save the patch version of the Solo distribution of Istio that you want to upgrade to.

      # Solo distrubution of Istio patch version
# in the format 1.x.x, with no tags
export ISTIO_VERSION=1.24.2

  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

Upgrade Gloo-managed service meshes

  1. Save the name and kubeconfig context of a workload cluster in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s name and context.

      export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>

  2. Upgrade the Gloo operator to the latest version.

      helm get values gloo-operator -n gloo-mesh --kube-context ${CLUSTER_CONTEXT} -o yaml > gloo-operator.yaml
helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.1.0-rc.1 \
  -n gloo-mesh \
  --kube-context ${CLUSTER_CONTEXT} \
  -f gloo-operator.yaml

  3. Verify that the operator pod is running.

      kubectl --context ${CLUSTER_CONTEXT} get pods -n gloo-mesh | grep operator

    Example output:

      gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s

  4. Edit the ServiceMeshController custom resource to make changes to your ambient mesh. For example, to upgrade the Istio patch or minor version of your service mesh, you might update the value of spec.version. For a description of each configurable field, see the ServiceMeshController reference.

      kubectl --context ${CLUSTER_CONTEXT} edit -n gloo-mesh ServiceMeshController managed-istio

  5. Save and close the editor to apply your changes in-place.

  6. Verify that the ServiceMeshController is ready. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

      kubectl --context ${CLUSTER_CONTEXT} describe servicemeshcontroller -n gloo-mesh managed-istio

    Example output:

      ...
Status:
  Conditions:
    Last Transition Time:  2024-12-27T20:47:01Z
    Message:               Manifests initialized
    Observed Generation:   1
    Reason:                ManifestsInitialized
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               CRDs installed
    Observed Generation:   1
    Reason:                CRDInstalled
    Status:                True
    Type:                  CRDInstalled
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  ControlPlaneDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  CNIDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  WebhookDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               All conditions are met
    Observed Generation:   1
    Reason:                SystemReady
    Status:                True
    Type:                  Ready
  Phase:                   SUCCEEDED
Events:                    <none>

  7. Verify that the istiod control plane, Istio CNI, and ztunnel pods are running.

      kubectl --context ${CLUSTER_CONTEXT} get pods -n istio-system

    Example output:

      NAME                          READY   STATUS    RESTARTS   AGE
istio-cni-node-6s5nk          1/1     Running   0          2m53s
istio-cni-node-blpz4          1/1     Running   0          2m53s
istiod-gloo-bb86b959f-msrg7   1/1     Running   0          2m45s
istiod-gloo-bb86b959f-w29cm   1/1     Running   0          3m
ztunnel-mx8nw                 1/1     Running   0          2m52s
ztunnel-w8r6c                 1/1     Running   0          2m52s

  8. Multicluster setups: Repeat steps 1 - 7 for each cluster where you want to upgrade Istio. Be sure to change the values of the $CLUSTER_NAME and $CLUSTER_CONTEXT environment variables for each cluster.