Navigation :

Upgrade managed gateway proxies

In Gloo Gateway 2.3 and later, you can easily manage and update gateway proxies in the gloo-platform Helm chart, instead of managing individual gateway lifecycle manager CRDs. If you installed Gloo Gateway by using the legacy gloo-mesh-enterpise, gloo-mesh-agent, and other included Helm charts, or if you used meshctl version 2.2 or earlier to install Gloo Gateway, migrate your legacy installation to the new gloo-platform Helm chart. Then, you can follow the steps in the gloo-platform upgrade guide to perform in-place and canary upgrades for the gateway proxy.

Use the Gloo management plane to upgrade Gloo-managed gateways in your clusters, as part of Istio lifecycle management.

About

After you use the lifecycle manager to deploy Istio installations, changes that you make to the IstioLifecycleManager and GatewayLifecycleManager resources are automatically propagated to your Istio installations. In some cases, these changes might require updates to your control plane or gateway deployments. Depending on the type of change, you apply updates to the installations in one of the following ways:

Canary upgrade (recommended)
In-place upgrade
Testing only: Manually replacing the GatewayLifecycleManager CR

Performing a canary upgrade

Update the minor version of Istio, the repository of the Istio image, or the components, profile, values, or namespace of the Istio installations. Note that you can force Gloo to always use canary upgrades by setting the spec.upgradeStrategy.alwaysUseCanaryUpgrade boolean value to true in the IstioLifecycleManager and GatewayLifecycleManager resources.

Istio version 1.17 does not support the Gloo legacy metrics pipeline. If you run the legacy metrics pipeline, before you upgrade or deploy gateway proxies with Istio 1.17, be sure that you set up the Gloo OpenTelemetry (OTel) pipeline instead in your new or existing Gloo Gateway installation.

OpenShift only: Elevate the permissions of the service account that will be created for the new revision's operator project. This permission allows the ingress gateway proxy to make use of a user ID that is normally restricted by OpenShift. Replace the revision with the revision you plan to use.
```
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-17-2
```

Edit the IstioLifecycleManager resource for the istiod control plane to add another installation entry for the canary revision. For the canary revision, be sure to set defaultRevision to false so that only the existing revision continues to run.

kubectl edit IstioLifecycleManager -n gloo-mesh <installation-name>

For example, if you upgrade to Istio 1.17, add the following 1-17-2 canary revision as a new entry in the installations section:

apiVersion: admin.gloo.solo.io/v2
kind: IstioLifecycleManager
metadata:
  name: istiod-control-plane
  namespace: gloo-mesh
spec:
  installations:
    # Existing revision
    - revision: 1-16-4
      clusters:
      - name: cluster1
        # Keep this field set to TRUE so that only the existing revision continues to run
        defaultRevision: true
      - name: cluster2
        defaultRevision: true
      istioOperatorSpec:
        profile: minimal
        ...
    # Canary revision
    - revision: 1-17-2
      clusters:
      - name: cluster1
        # Set this field to FALSE so that only the existing revision continues to run
        defaultRevision: false
      - name: cluster2
        defaultRevision: false
      istioOperatorSpec:
        profile: minimal
        ...

Updating the minor version of Istio? In your canary revision section, be sure to update both the repo key in the hub field, and the Istio version in the tag field. You can get the repo key for the Istio version that you want to install from the Istio images built by Solo.io support article.

If you created GatewayLifecycleManager resources for east-west or ingress gateways, edit those resources to add another installation entry for the canary revision. Be sure to set activeGateway to false so that only the existing revision continues to run.

kubectl edit GatewayLifecycleManager -n gloo-mesh <installation-name>

For example, if you upgrade to Istio 1.17, add the following 1-17-2 canary revision as a new entry in the installations section:

apiVersion: admin.gloo.solo.io/v2
kind: GatewayLifecycleManager
metadata:
  name: istio-ingressgateway
  namespace: gloo-mesh
spec:
  installations:
    # Existing revision
    - gatewayRevision: 1-16-4
      clusters:
      - name: cluster1
        # Keep this field set to TRUE so that only the existing revision continues to run
        activeGateway: true
      - name: cluster2
        activeGateway: true
      istioOperatorSpec:
        profile: empty
        ...
    # Canary revision
    - gatewayRevision: 1-17-2
      clusters:
      - name: cluster1
        # Set this field to FALSE so that only the existing revision continues to run
        activeGateway: false
      - name: cluster2
        activeGateway: false
      istioOperatorSpec:
        profile: empty
        ...

For most use cases, you can set the revision for the IstioLifecycleManager and the gatewayRevision for the GatewayLifecycleManager to the same version. However, gateway installations can point to any istiod control plane revision by using the controlPlaneRevision field. For simplicity, if you do not specify controlPlaneRevision, the gateway installation uses a control plane with the same revision as itself.

Verify that Istio resources for the canary installation are created. For example, if you updated the Istio minor version to 1-17-2, verify that resources are created in the gm-iop-1-17-2 namespace, and that resources for 1-17-2 are created alongside the existing resources for the previous version in the istio-system and gloo-mesh-gateways namespaces. Note that the gateway load balancers for the canary revision contain the revision in the name, such as istio-ingressgateway-1-17-2.
```
kubectl get all -n gm-iop-1-17-2
kubectl get all -n istio-system
kubectl get all -n gloo-mesh-gateways
```
Running into issues or seeing a stuck canary upgrade? In testing environments, you can clear your configuration by manually replacing the GatewayLifecycleManager CR.

After performing any necessary testing, switch to the new istiod control plane revision by changing defaultRevision to false for the old revision and to true for the new revision.

kubectl edit IstioLifecycleManager -n gloo-mesh istiod-control-plane

Example:

apiVersion: admin.gloo.solo.io/v2
kind: IstioLifecycleManager
metadata:
  name: istiod-control-plane
  namespace: gloo-mesh
spec:
  installations:
    # Old revision
    - revision: 1-16-4
      clusters:
      - name: cluster1
        # Set this field to FALSE
        defaultRevision: false
      - name: cluster2
        defaultRevision: false
      istioOperatorSpec:
        profile: minimal
        ...
    # New revision
    - revision: 1-17-2
      clusters:
      - name: cluster1
        # Set this field to TRUE
        defaultRevision: true
      - name: cluster2
        defaultRevision: true
      istioOperatorSpec:
        profile: minimal
        ...

New load balancers are created for the canary gateways. To instead change the control plane revision in use by the existing gateways, you can set the istio.io/rev label on the gateway deployment, which triggers a rolling restart.

Switch to any new gateways by changing activeGateway to false for the old revision and to true for the new revision.

kubectl edit GatewayLifecycleManager -n gloo-mesh <installation-name>

Example:

apiVersion: admin.gloo.solo.io/v2
kind: GatewayLifecycleManager
metadata:
  name: istio-ingressgateway
  namespace: gloo-mesh
spec:
  installations:
    # Old revision
    - gatewayRevision: 1-16-4
      clusters:
      - name: cluster1
        # Set this field to FALSE
        activeGateway: false
      - name: cluster2
        activeGateway: false
      istioOperatorSpec:
        profile: empty
        ...
    # New revision
    - gatewayRevision: 1-17-2
      clusters:
      - name: cluster1
        # Set this field to TRUE
        activeGateway: true
      - name: cluster2
        activeGateway: ture
      istioOperatorSpec:
        profile: empty
        ...

New load balancers are created for the canary gateways. To instead change the control plane revision in use by the existing gateway load balancers, you can set the istio.io/rev label on the gateway deployment, which triggers a rolling restart.

Verify that the active gateways for the new revision are created, which do not have the revision appended to the name. Note that gateways for the inactive revision that you previously ran also exist in the namespace, in the case that a rollback is required.

kubectl get all -n gloo-mesh-gateways

Example output, in which the active gateway (istio-ingressgateway) for the new revision and inactive gateway (such as istio-ingressgateway-1-16-4) for the old revision are created:

NAME                            TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)     
istio-ingressgateway            LoadBalancer   10.44.4.140   34.150.235.221   15021:31321/TCP,80:32525/TCP,443:31826/TCP   48s                                                 AGE
istio-ingressgateway-1-16-4       LoadBalancer   10.56.15.36    34.145.163.61   15021:31936/TCP,80:30196/TCP,443:32286/TCP,15443:31851/TCP   45s

To uninstall the previous installation, or if you need to uninstall the canary installation, you can edit the IstioLifecycleManager and GatewayLifecycleManager resources to remove the revision's entry from the installations list.

Performing an in-place upgrade

Update the patch version of Istio or update meshConfig values of the Istio installations.

If you also use Gloo Mesh Enterprise alongside Gloo Gateway, follow the steps to upgrade Istio in the Gloo Mesh documentation instead. The Gloo Mesh guide shows you how to upgrade your workload sidecars along with your control planes and gateways.

Upgrade your istiod control plane by editing the IstioLifecycleManager resource. For example, you might update the patch version of Istio by changing the value of istioOperatorSpec.tag. After you save and close the editor, Gloo starts an in-place upgrade of the istiod control planes.
```
kubectl edit IstioLifecycleManager -n gloo-mesh <istiod-installation-name>
```
If you created GatewayLifecycleManager resources for ingress or east-west gateways, you can upgrade your gateways by editing each resource. For example, if you updated the patch version of the control plane, you can also update your gateway patch versions by changing the value of istioOperatorSpec.tag. After you save and close the editor, Gloo starts an in-place upgrade of the gateways.
```
kubectl edit GatewayLifecycleManager -n gloo-mesh <ingress-gateway-installation-name>
```
```
kubectl edit GatewayLifecycleManager -n gloo-mesh <eastwest-gateway-installation-name>
```
After your Helm upgrade completes, restart your gateway proxy pods. For example, you might use the following command to rollout a restart of the istio-ingressgateway-1-17-2 deployment.
```
kubectl rollout restart -n gloo-mesh-gateways deployment/istio-ingressgateway-1-17-2
```

Verify that your Istio resources are updated.

kubectl get all -n gm-iop-1-17-2
kubectl get all -n istio-system
kubectl get all -n gloo-mesh-gateways

Testing only: Manually replacing the GatewayLifecycleManager CR

In testing or demo setups, you can quickly upgrade your managed gateway proxies by manually deleting the GatewayLifecycleManager CR, and upgrading your Gloo Gateway installation with your updated gateway values in your Helm values file. Note that you can also use this method to clear your managed gateway configurations if a canary upgrade becomes stuck.

This method is supported only for testing scenarios, because your ingress gateway proxies are temporarily removed in this process.

Get the name of your GatewayLifecycleManager resource. Typically, this resource is named istio-ingressgateway.
```
kubectl get GatewayLifecycleManager -A
```

Delete the resource.

kubectl delete GatewayLifecycleManager istio-ingressgateway -n gloo-mesh

Verify that your gateway proxy is removed.

kubectl get svc -n gloo-mesh-gateways istio-ingressgateway

Optional: If you also need to make changes to your Istio control plane, clear the istiod configuration.
1. Get the name of your IstioLifecycleManager resource. Typically, this resource is named gloo-platform.
```
kubectl get IstioLifecycleManager -A
```
2. Delete the resource.
```
kubectl delete IstioLifecycleManager gloo-platform -n gloo-mesh
```
3. Verify that your istiod control plane is removed.
```
kubectl get all -n istio-system
```
Follow the steps in this guide to perform a regular upgrade of your Gloo Gateway installation and include your Istio changes in your Helm values file. After you apply the updates in your Helm upgrade of the gloo-platform chart, Gloo re-creates the ingress gateway proxy, and if applicable, the istiod control plane.

After your Helm upgrade completes, verify that your Istio resources are re-created.

# Change the revision as needed
kubectl get all -n gm-iop-1-17-2
kubectl get all -n istio-system
kubectl get all -n gloo-mesh-gateways