On this page

Upgrade Gloo-managed service meshes

Use the Gloo operator to upgrade your managed Istio service meshes.

Considerations

Feature maturity

warning

In Gloo Mesh version 2.7, the Gloo operator is an alpha feature. Alpha features are likely to change, are not fully tested, and are not supported for production. For more information, see Gloo feature maturity.

Version requirements

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.
Check the Istio release notes for the upgrade version to prepare for any breaking changes.
Be sure to review the following known Istio version restrictions.
warning
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 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.

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.

Istio 1.20 is supported only as patch version 1.20.1-patch1 and later. Do not use patch versions 1.20.0 and 1.20.1, which contain bugs that impact several Gloo Mesh features that rely on Istio ServiceEntries.

Single cluster

Save the patch version of the Solo distribution of Istio that you want to upgrade to. For supported Istio versions in Gloo Mesh, see 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=1.24.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 the Gloo operator to the latest version.

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

Verify that the operator pod is running.

  kubectl get pods -n gloo-mesh  | grep operator

Example output:

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

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 ServiceMeshController managed-istio
  
```
Save and close the editor to apply your changes in-place.

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>

Verify that the istiod control plane and Istio CNI 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

Multicluster

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 binary repo
export BINARY_REPO=https://console.cloud.google.com/storage/browser/istio-binaries-${REPO_KEY}/${ISTIO_VERSION}-solo

Download the Solo distribution of Istio binary to upgrade istioctl.
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_VERSION}-solo
export PATH=$PWD/bin:$PATH
  
```
5. Verify that the istioctl client runs the Solo distribution of Istio that you want to upgrade to.
```
  istioctl version --remote=false
  
```
  Example output:
```
  client version: 1.24.2-solo
  
```
Save the kubeconfig context of a cluster where you want to upgrade your sidecar 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>
  
```

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

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

Edit the ServiceMeshController custom resource to make changes to your sidecar 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
  
```
Save and close the editor to apply your changes in-place.

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>

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

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

Upgrade Gloo-managed service meshes

Considerations link

Single cluster link

Multicluster link

Considerations

Single cluster

Multicluster