Upgrade managed ambient meshes with the Gloo Operator

By using the Gloo Operator, you can perform safe in-place upgrades of your manage ambient service meshes, without the hassle of upgrading multiple Helm charts for each component.

Considerations link

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

Revision and canary upgrade limitations

The upgrade guides in this documentation show you how to perform in-place upgrades for your Istio components, which is the recommended upgrade strategy.

Version and license requirements

Single cluster setups:

• In Gloo Mesh 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 setups:

• In Gloo Mesh version 2.7 and later, multicluster setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo), including the Solo distribution of istioctl.
• This feature requires your mesh to be installed with the Solo distribution of Istio and an Enterprise-level license for Gloo Mesh. Contact your account representative to obtain a valid license.

Single cluster link

1. Save your Istio upgrade values in environment variables.

   1. If you do not already have a license, decide the level of licensed features that you want, and contact an account representative to obtain the license.

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

   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
           

2. Upgrade the custom resources of the Kubernetes Gateway API to the latest supported version, .

     kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v/standard-install.yaml
     

3. 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.3 \
     -n gloo-mesh \
     -f gloo-operator.yaml
     

4. Verify that the operator pod is running.

     kubectl get pods -n gloo-mesh -l app.kubernetes.io/name=gloo-operator
     

   Example output:

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

5. 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 edit -n gloo-mesh ServiceMeshController managed-istio
     

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

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

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

     kubectl 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
     

Multicluster link

1. Upgrade the Solo distribution of Istio binary.

   1. Get the operating system, architecture, and Istio repository details and save them in environment variables.

        OS=$(uname | tr '[:upper:]' '[:lower:]' | sed -E 's/darwin/osx/')
      ARCH=$(uname -m | sed -E 's/aarch/arm/; s/x86_64/amd64/; s/armv7l/armv7/')
      echo $OS
      echo $ARCH
      ISTIO_VERSION=1.25.2
      ISTIO_IMAGE=${ISTIO_VERSION}-solo
      HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-e038d180f90a
      REPO=us-docker.pkg.dev/gloo-mesh/istio-e038d180f90a
        

   2. Download the Solo distribution of Istio binary and upgrade istioctl.

        mkdir -p ~/.istioctl/bin
      curl -sSL https://storage.googleapis.com/istio-binaries-e038d180f90a/${ISTIO_IMAGE}/istioctl-${ISTIO_IMAGE}-${OS}-${ARCH}.tar.gz | tar xzf - -C ~/.istioctl/bin
      chmod +x ~/.istioctl/bin/istioctl
      
      export PATH=${HOME}/.istioctl/bin:${PATH}
        

   3. Verify that the istioctl client is upgraded.

        istioctl version --remote=false
        

      Example output:

        client version: 1.25.2-solo
        

   1. Get the OS and architecture that you use on your machine.

        OS=$(uname | tr '[:upper:]' '[:lower:]' | sed -E 's/darwin/osx/')
      ARCH=$(uname -m | sed -E 's/aarch/arm/; s/x86_64/amd64/; s/armv7l/armv7/')
      echo $OS
      echo $ARCH
        

   2. Set environment variables for the Solo distribution of Istio that you want to upgrade to. 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
      # in the format 1.x.x, with no tags
      export ISTIO_VERSION=<istio_version>
      # 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>
      export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
      export ISTIO_IMAGE=${ISTIO_VERSION}-solo
      export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
        

   3. Download the Solo distribution of Istio binary and upgrade istioctl.

        mkdir -p ~/.istioctl/bin
      curl -sSL https://storage.googleapis.com/istio-binaries-$REPO_KEY/$ISTIO_IMAGE/istioctl-$ISTIO_IMAGE-$OS-$ARCH.tar.gz | tar xzf - -C ~/.istioctl/bin
      chmod +x ~/.istioctl/bin/istioctl
      
      export PATH=${HOME}/.istioctl/bin:${PATH}
        

   4. Verify that the istioctl client is upgraded

        istioctl version --remote=false
        

      Example output:

        client version: 1.24.3-solo
        

2. Save the kubeconfig context of a cluster where you want to upgrade an ambient mesh in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s context.

     export CLUSTER_CONTEXT=<cluster-context>
     

3. Upgrade the custom resources of the Kubernetes Gateway API to the latest supported version, .

     kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v/standard-install.yaml
     

4. 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.3 \
     -n gloo-mesh \
     --kube-context ${CLUSTER_CONTEXT} \
     -f gloo-operator.yaml
     

5. Verify that the operator pod is running.

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

   Example output:

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

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

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

8. 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 managed-istio --context ${CLUSTER_CONTEXT}
     

   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>
        

9. Verify that the istiod control plane, Istio CNI, and ztunnel 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
   ztunnel-mx8nw                 1/1     Running   0          2m52s
   ztunnel-w8r6c                 1/1     Running   0          2m52s
     

10. For each cluster, repeat steps 3 - 10. Be sure to change the value of the $CLUSTER_CONTEXT environment variable for each cluster.