Upgrade Gloo Operator-managed service meshes
Use the Gloo Operator to upgrade your managed Istio service meshes.
Considerations
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.
In the Solo distribution of Istio 1.25 and later, you can access enterprise-level features by passing your Solo license in the
license.value
orlicense.secretRef
field of your Solo istiod Helm chart. The Helm chart that is provided by Solo includes safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Although you can pass the license key in thepilot.env.SOLO_LICENSE_KEY
field of the open source Istio Helm chart, this method is not recommended. For best results, we strongly recommend using the Solo Helm chart to install and manage Istio. For example, to install the Solo distribution of 1.25, you can run thehelm install istiod oci://us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}/istiod …
command and provide your installation values in–set
flags or a-f <file.yaml>
config file.
Istio patch versions 1.25.1 and 1.24.4 contain an upstream certificate rotation bug in which requests with more than one trusted root certificate cannot be validated. If you use Gloo Mesh Enterprise to manage root certificate rotation and use Istio 1.25 or 1.24, be sure to use 1.25.2 or 1.24.5 and later only.
Istio 1.22 is supported only as patch version1.22.1-patch0
and later. Do not use patch versions 1.22.0 and 1.22.1, which contain bugs that impact several Gloo Mesh Enterprise routing features that rely on virtual destinations. Additionally, in Istio 1.22.0-1.22.3, theISTIO_DELTA_XDS
environment variable must be set tofalse
. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
If you have multiple external services that use the same host and plan to use Istio 1.21 or 1.22, you must use patch versions 1.21.3 or 1.22.1-patch0 or later to ensure that the Istio service entry that is created for those external services is correct.
Before you begin
- Save your Istio upgrade values in environment variables.
If you do not already have a license, contact an account representative.
Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table.
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
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
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>
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
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
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
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 areTrue
, and that the phase isSUCCEEDED
.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>
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
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.