Considerations

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 your Istio upgrade values in environment variables.
    1. If you do not already have a license, contact an account representative.

    2. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table.

    3. Save each value in an environment variable. If you prefer to specify license keys in a secret instead, see Licensing. Note that the Gloo Operator installs the Solo distribution of Istio by default for the version you specify, so neither the -solo image tag nor the repo key are required.

           export GLOO_MESH_LICENSE_KEY=<license_key>
         export ISTIO_VERSION=1.26.0
           
    4. Install or upgrade istioctl with the same version of Istio that you saved.

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

Upgrade Gloo Operator-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 -o yaml > gloo-operator.yaml
    helm upgrade gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
      --version 0.2.4 \
      -n gloo-mesh \ 
      --kube-context ${CLUSTER_CONTEXT} \ 
      -f gloo-operator.yaml
      
  3. Verify that the operator pod is running.

      kubectl get pods -n gloo-mesh --context ${CLUSTER_CONTEXT} -l app.kubernetes.io/name=gloo-operator
      

    Example output:

      gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s
      
  4. Edit the ServiceMeshController custom resource to make changes to your 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 edit -n gloo-mesh --context ${CLUSTER_CONTEXT} 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 describe servicemeshcontroller -n gloo-mesh --context ${CLUSTER_CONTEXT} 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 and Istio CNI pods are running.

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

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