Gloo Operator

Use the Gloo Operator to upgrade your managed sidecar service meshes.

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

Before you begin

Verify that the minor version of the Solo distribution of Istio that you want to upgrade to is tested and supported for your Solo Enterprise for Istio 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 Solo Enterprise for Istio release notes for changes from the previous version.
Before you proceed with the upgrade, make sure that you review the breaking changes that were introduced in this release and the impact that they have on your current environment. For more information, see the Breaking changes.
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.
- If you use Istio versions 1.27.7, 1.28.4, 1.29.0 or later, and you install the Solo Enterprise for Istio management plane into a namespace other than gloo-mesh, you must allow that namespace by listing it in the DEBUG_ENDPOINT_AUTH_ALLOWED_NAMESPACES environment variable of your istiod installation. For more information, see the release notes.
- Patch versions 1.26.0 and 1.26.1 of the Solo distribution of Istio lack support for FIPS-tagged images and ztunnel outlier detection. When upgrading or installing 1.26, be sure to use patch version 1.26.1-patch0 and later only.
- 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 or license.secretRef field of the Solo distribution of the istiod Helm chart. The Solo istiod Helm chart is strongly recommended due to the included safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Though it is not recommended, you can pass your license key in the open source istiod Helm chart by using the --set pilot.env.SOLO_LICENSE_KEY field.
- Multicluster setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo), including the Solo distribution of istioctl.
- Due to a lack of support for the Istio CNI and iptables for the Istio proxy, you cannot run Istio (and therefore Solo Enterprise for Istio) on AWS Fargate. For more information, see the Amazon EKS issue.

Single cluster

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 URL are required.
  export SOLO_ISTIO_LICENSE_KEY=<license_key> export ISTIO_VERSION=1.28.5
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 the custom resources of the Kubernetes Gateway API to the latest supported version, 1.4.0.

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

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

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

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
```
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, 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

Set environment variables for the Solo distribution of Istio that you want to upgrade to.
You can find these values in the Istio images built by Solo.io support article.

# Solo distribution 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}

Upgrade your istioctl CLI client to the new version. This script automatically detects your OS and architecture, downloads the appropriate Solo distribution of Istio binary, and verifies the installation.
```
bash <(curl -sSfL https://raw.githubusercontent.com/solo-io/doc-examples/main/istio/install-istioctl.sh)
export PATH=${HOME}/.istioctl/bin:${PATH}
```
Save the kubeconfig context of a cluster where you want to upgrade an ambient mesh in an environment variable. Each time you repeat the steps in this guide, you change this variables to the next cluster’s context.
```
export ctx=<cluster-context>
```

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

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

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

Verify that the operator pod is running.

kubectl --context ${ctx} get pods -n gloo-mesh -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 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 ${ctx} 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 ${ctx}

Example output:

... class=nt>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 class=nt>Events:                    <none>

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

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

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 - 10. Be sure to change the value of the $ctx environment variable for each cluster.

Helm