Introduction

After you deploy Gloo-managed service meshes, 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 by using an in-place upgrade or a revisioned canary upgrade.

In-place upgrade

In an in-place upgrade, Gloo upgrades your existing control plane or gateway installations. In-place upgrades behave differently based on whether your installation is revisionless or revisioned.

Revisionless (testing only): If your testing-only installation is revisionless (your settings omit the revision and gatewayRevision fields), in-place upgrades are triggered when you apply changes to any field in the istioInstallations section.

Revisioned: If your installation is revisioned, in-place upgrades are triggered only when you apply changes to one of the following fields in the istioInstallations section. Otherwise, a canary upgrade is required. You can change this behavior by setting the spec.installations.skipUpgradeValidation boolean value to true in the IstioLifecycleManager and GatewayLifecycleManager resources.

  • istioOperatorSpec.tag patch version
    • In-place upgrades are not supported for downgrading the patch version.
    • In-place upgrades are not supported if you do not already specify a tag value, such as if you want to switch from the auto setting to a specific version. This is because you must also specify hub and revision values, which require a canary upgrade.
  • istioOperatorSpec.meshConfig values

Multicluster

  1. Get the names of your managed Istio installation resources.

      kubectl get IstioLifecycleManager -n gloo-mesh --context $MGMT_CONTEXT
    kubectl get GatewayLifecycleManager -n gloo-mesh --context $MGMT_CONTEXT
      
  2. 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 --context $MGMT_CONTEXT <istiod-installation-name>
      
  3. If you created GatewayLifecycleManager resources for ingress or egress 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 --context $MGMT_CONTEXT <ingress-gateway-installation-name>
      
      kubectl edit GatewayLifecycleManager -n gloo-mesh --context $MGMT_CONTEXT <egress-gateway-installation-name>
      
  4. Required for versions earlier than 2.5.9, 2.4.16, and 2.3.24: After your Helm upgrade completes, restart your gateway pods in each workload cluster. For example, you might use the following command to rollout a restart of the istio-ingressgateway-1-20 and istio-egressgateway-1-20 deployments.

      kubectl rollout restart -n gloo-mesh-gateways deployment/istio-ingressgateway-1-20 --context $REMOTE_CONTEXT1
    kubectl rollout restart -n gloo-mesh-gateways deployment/istio-egressgateway-1-20 --context $REMOTE_CONTEXT1
      
      kubectl rollout restart -n gloo-mesh-gateways deployment/istio-ingressgateway-1-20 --context $REMOTE_CONTEXT2
    kubectl rollout restart -n gloo-mesh-gateways deployment/istio-egressgateway-1-20 --context $REMOTE_CONTEXT2
      
  5. Verify that your Istio resources are updated.

      kubectl get all -n gm-iop-1-20 --context $REMOTE_CONTEXT1
    kubectl get all -n istio-system --context $REMOTE_CONTEXT1
    kubectl get all -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
      

Single cluster

  1. Get the names of your managed Istio installation resources.

      kubectl get IstioLifecycleManager -n gloo-mesh
    kubectl get GatewayLifecycleManager -n gloo-mesh
      
  2. 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>
      
  3. If you created GatewayLifecycleManager resources for ingress or egress 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 <egress-gateway-installation-name>
      
  4. Required for versions earlier than 2.5.9, 2.4.16, and 2.3.24: After your Helm upgrade completes, restart your gateway pods in each workload cluster. For example, you might use the following command to rollout a restart of the istio-ingressgateway-1-20 and istio-egressgateway-1-20 deployments.

      kubectl rollout restart -n gloo-mesh-gateways deployment/istio-ingressgateway-1-20
    kubectl rollout restart -n gloo-mesh-gateways deployment/istio-egressgateway-1-20
      
  5. Verify that your Istio resources are updated.

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

Revisioned canary upgrade

In a canary upgrade, you install another Istio installation (canary) alongside your active installation. Each installation is revisioned so that you can easily identify and verify the separate settings and resources for each installation.

Perform a canary upgrade when you change one of the following fields:

  • istioOperatorSpec.tag minor version
  • istioOperatorSpec.hub repository, such as switching to the repository for the minor version of the Solo distribution of Istio that you want to upgrade to
  • components, profile, values, or namespace in the istioOperatorSpec

Keep in mind the following considerations:

  • During a canary upgrade, the validating admissions webhook is enabled only for the canary installation to prevent issues that occur when multiple webhooks are enabled.

Multicluster

  1. OpenShift only: Elevate the permissions of the service account that will be created for the new revision’s operator project. This permission allows the Istio sidecar 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-20 --context $REMOTE_CONTEXT1
    oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-20 --context $REMOTE_CONTEXT2
      
  2. Get the names of your managed Istio installation resources.

      kubectl get IstioLifecycleManager -n gloo-mesh --context $MGMT_CONTEXT
    kubectl get GatewayLifecycleManager -n gloo-mesh --context $MGMT_CONTEXT
      
  3. 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 --context $MGMT_CONTEXT <installation-name>
      

    For example, if you upgrade to Istio 1.20.7-patch0, add the following 1-20 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-19
          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:
            ...
        # Canary revision
        - revision: 1-20
          clusters:
          - name: cluster1
            # Set this field to FALSE so that only the existing revision continues to run
            defaultRevision: false
          - name: cluster2
            defaultRevision: false
          istioOperatorSpec:
            ...
      
  4. If you created GatewayLifecycleManager resources for ingress or egress 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 --context $MGMT_CONTEXT <installation-name>
      

    For example, if you upgrade to Istio 1.20.7-patch0, add the following 1-20 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-19
          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-20
          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
            ...
      
  5. Verify that Istio resources for the canary installation are created. For example, if you updated the Istio minor version to 1.20.7-patch0, verify that resources are created in the gm-iop-1-20 namespace, and that resources for 1-20 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-20.

      kubectl get all -n gm-iop-1-20 --context $REMOTE_CONTEXT1
    kubectl get all -n istio-system --context $REMOTE_CONTEXT1
    kubectl get all -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
      
      kubectl get all -n gm-iop-1-20 --context $REMOTE_CONTEXT2
    kubectl get all -n istio-system --context $REMOTE_CONTEXT2
    kubectl get all -n gloo-mesh-gateways --context $REMOTE_CONTEXT2
      
  6. 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 --context $MGMT_CONTEXT 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-19
          clusters:
          - name: cluster1
            # Set this field to FALSE
            defaultRevision: false
          - name: cluster2
            defaultRevision: false
          istioOperatorSpec:
            ...
        # New revision
        - revision: 1-20
          clusters:
          - name: cluster1
            # Set this field to TRUE
            defaultRevision: true
          - name: cluster2
            defaultRevision: true
          istioOperatorSpec:
            ...
      
  7. In your workload clusters, update the labels on your service namespaces to use the new revision.

    1. For any namespace where you run Istio-managed apps, change the label to use the new revision, such as in these example commands.

        kubectl label ns <namespace> --overwrite istio.io/rev=1-20 --context $REMOTE_CONTEXT1
      kubectl label ns <namespace> --overwrite istio.io/rev=1-20 --context $REMOTE_CONTEXT2
        

      For example, if you installed the Bookinfo sample app:

        kubectl label ns bookinfo --overwrite istio.io/rev=1-20 --context $REMOTE_CONTEXT1
      kubectl label ns bookinfo --overwrite istio.io/rev=1-20 --context $REMOTE_CONTEXT2
        
    2. Update any Istio-managed apps by rolling out restarts. The Istio sidecars for each microservice are updated to use the new Istio version. Make sure that you only restart one microservice at a time. For example, in the following commands to update the Bookinfo microservices, 20 seconds elapse between each restart to ensure that the pods have time to start running.

        kubectl rollout restart deployment -n bookinfo details-v1 --context $REMOTE_CONTEXT1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo ratings-v1 --context $REMOTE_CONTEXT1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo productpage-v1 --context $REMOTE_CONTEXT1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v1 --context $REMOTE_CONTEXT1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v2 --context $REMOTE_CONTEXT1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v3 --context $REMOTE_CONTEXT2
      sleep 20s
      kubectl rollout restart deployment -n bookinfo ratings-v1 --context $REMOTE_CONTEXT2
      sleep 20s
        
    3. Verify that your workloads and new gateways point to the new revision.

        istioctl proxy-status --context $REMOTE_CONTEXT1
        

      Example output:

        NAME                                                              CLUSTER     ...     ISTIOD                           VERSION
      details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      istio-ingressgateway-1-20-bdc4fd65f-ftmz9.gloo-mesh-gateways    cluster1    ...     istiod-1-20-6495985689-rkwwd     1.20.7-patch0-solo
      productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
        
  8. 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 --context $MGMT_CONTEXT <installation-name>
      

    Example:

      apiVersion: admin.gloo.solo.io/v2
    kind: GatewayLifecycleManager
    metadata:
      name: istio-ingressgateway
      namespace: gloo-mesh
    spec:
      installations:
        # Old revision
        - gatewayRevision: 1-19
          clusters:
          - name: cluster1
            # Set this field set to FALSE
            activeGateway: false
          - name: cluster2
            activeGateway: false
          istioOperatorSpec:
            profile: empty
            ...
        # New revision
        - gatewayRevision: 1-20
          clusters:
          - name: cluster1
            # Set this field to TRUE
            activeGateway: true
          - name: cluster2
            activeGateway: true
          istioOperatorSpec:
            profile: empty
            ...
      
  9. 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 --context $REMOTE_CONTEXT1
    kubectl get all -n gloo-mesh-gateways --context $REMOTE_CONTEXT2
      

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

      NAME                            TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                                                      AGE
    istio-ingressgateway            LoadBalancer   10.44.4.140    34.150.235.221  15021:31321/TCP,80:32525/TCP,443:31826/TCP                   48s
    istio-ingressgateway-1-19       LoadBalancer   10.56.15.36    34.145.163.61   15021:31936/TCP,80:30196/TCP,443:32286/TCP,15443:31851/TCP   45s
      
  10. 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.

Single cluster

  1. OpenShift only: Elevate the permissions of the service account that will be created for the new revision’s operator project. This permission allows the Istio sidecar 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-20 --context $REMOTE_CONTEXT1
    oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-20 --context $REMOTE_CONTEXT2
      
  2. Get the names of your managed Istio installation resources.

      kubectl get IstioLifecycleManager -n gloo-mesh
    kubectl get GatewayLifecycleManager -n gloo-mesh
      
  3. 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.20.7-patch0, add the following 1-20 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-19
          clusters:
          - name: cluster1
            # Keep this field set to TRUE so that only the existing revision continues to run
            defaultRevision: true
          istioOperatorSpec:
            ...
        # Canary revision
        - revision: 1-20
          clusters:
          - name: cluster1
            # Set this field to FALSE so that only the existing revision continues to run
            defaultRevision: false
          istioOperatorSpec:
            ...
      
  4. If you created GatewayLifecycleManager resources for ingress or egress 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.20.7-patch0, add the following 1-20 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-19
          clusters:
          - name: cluster1
            # Keep this field set to TRUE so that only the existing revision continues to run
            activeGateway: true
          istioOperatorSpec:
            profile: empty
            ...
        # Canary revision
        - gatewayRevision: 1-20
          clusters:
          - name: cluster1
            # Set this field to FALSE so that only the existing revision continues to run
            activeGateway: false
          istioOperatorSpec:
            profile: empty
            ...
      
  5. Verify that Istio resources for the canary installation are created. For example, if you updated the Istio minor version to 1.20.7-patch0, verify that resources are created in the gm-iop-1-20 namespace, and that resources for 1-20 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-20.

      kubectl get all -n gm-iop-1-20
    kubectl get all -n istio-system
    kubectl get all -n gloo-mesh-gateways
      
  6. 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-19
          clusters:
          - name: cluster1
            # Set this field to FALSE
            defaultRevision: false
          istioOperatorSpec:
            ...
        # New revision
        - revision: 1-20
          clusters:
          - name: cluster1
            # Set this field to TRUE
            defaultRevision: true
          istioOperatorSpec:
            ...
      
  7. Update the labels on your service namespaces to use the new revision.

    1. For any namespace where you run Istio-managed apps, change the label to use the new revision, such as in these example commands.

        kubectl label ns <namespace> --overwrite istio.io/rev=1-20
        

      For example, if you installed the Bookinfo sample app:

        kubectl label ns bookinfo --overwrite istio.io/rev=1-20
        
    2. Update any Istio-managed apps by rolling out restarts. The Istio sidecars for each microservice are updated to use the new Istio version. Make sure that you only restart one microservice at a time. For example, in the following commands to update the Bookinfo microservices, 20 seconds elapse between each restart to ensure that the pods have time to start running.

        kubectl rollout restart deployment -n bookinfo details-v1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo productpage-v1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v1
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v2
      sleep 20s
      kubectl rollout restart deployment -n bookinfo reviews-v3
      sleep 20s
      kubectl rollout restart deployment -n bookinfo ratings-v1
      sleep 20s
        
    3. Verify that your workloads and new gateways point to the new revision.

        istioctl proxy-status
        

      Example output:

        NAME                                                              CLUSTER     ...     ISTIOD                           VERSION
      details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      istio-ingressgateway-1-20-bdc4fd65f-ftmz9.gloo-mesh-gateways    cluster1    ...     istiod-1-20-6495985689-rkwwd     1.20.7-patch0-solo
      productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
      reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-1-20-7c8f6fd4c4-m9k9t     1.20.7-patch0-solo
        
  8. 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-19
          clusters:
          - name: cluster1
            # Keep this field set to FALSE
            activeGateway: false
          istioOperatorSpec:
            profile: empty
            ...
        # New revision
        - gatewayRevision: 1-20
          clusters:
          - name: cluster1
            # Set this field to TRUE
            activeGateway: true
          istioOperatorSpec:
            profile: empty
            ...
      
  9. 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-19) for the old revision are created:

      NAME                            TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                                                      AGE
    istio-ingressgateway            LoadBalancer   10.44.4.140    34.150.235.221  15021:31321/TCP,80:32525/TCP,443:31826/TCP                   48s
    istio-ingressgateway-1-19       LoadBalancer   10.56.15.36    34.145.163.61   15021:31936/TCP,80:30196/TCP,443:32286/TCP,15443:31851/TCP   45s
      
  10. 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.