Upgrade Gloo Mesh

Upgrade Gloo Mesh Enterprise minor and patch versions.

During the upgrade, the data plane continues to run, but you might not be able to modify the configurations through the management plane. Because zero downtime is not guaranteed, try testing the upgrade in a staging environment before upgrading your production environment.

Looking to update certain Helm chart values but not the version? See Modifying Helm chart values.

Before you begin

  1. Review the changelog. Focus especially on any Breaking Changes that might require a different upgrade procedure.

    If you are on version 1.0 or earlier, uninstall and re-install Gloo Mesh Enterprise, as described in one of the setup guides.

  2. Check that your underlying Kubernetes platform and Istio service mesh run supported versions for the Gloo Mesh Enterprise version that you want to upgrade to.

    1. Review the supported versions.
    2. Compare the supported version against the versions of Kubernetes and Istio that you run in your clusters.
    3. If necessary, upgrade Istio or Kubernetes. For example, if you want to upgrade from Gloo Mesh Enterprise 1.1 to 1.2 but currently run Istio 1.7, you must upgrade to Istio 1.8 first.
      • For Istio steps, see Upgrade Istio.
      • For Kubernetes steps, consult your cluster infrastructure provider.
  3. In your terminal, set environment variables for your current and target Gloo Mesh Enterprise versions to use in the subsequent steps.

    # Set the Gloo Mesh Enterprise version. The latest version is used as an example. You can find other versions in the Changelog documentation.
    export UPGRADE_VERSION=2.0.7
    
    # Save the kubeconfig contexts for your clusters. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column.
    export MGMT_CONTEXT=<management_cluster_config>
    export REMOTE_CONTEXT=<remote_cluster_config>
    
    # Set the gloo-mesh namespace.
    export NAMESPACE=gloo-mesh
    
    # Add your Gloo Mesh Enterprise license that you got from your Solo account representative.
    export GLOO_MESH_LICENSE_KEY=<your-key>
    

Step 1: Upgrade the CRDs for your management cluster

  1. Switch your Kubernetes context to the management cluster.
    kubectl config use-context $MGMT_CONTEXT
    
  2. Update the Helm repo for Gloo Mesh Enterprise.
    helm repo update
    
  3. Pull the latest Gloo Mesh Enterprise Helm chart files.
    helm pull gloo-mesh-enterprise/gloo-mesh-enterprise --version $UPGRADE_VERSION --untar
    
  4. Apply the Gloo Mesh Enterprise custom resource definitions (CRDs) on your management cluster.
    kubectl apply -f gloo-mesh-enterprise/charts/gloo-mesh-crds/crds/
    

If you upgrade to a release such as 2.1.0-beta3, you might see an error such as "error":"no matches for kind \"CertificateRequest\" in version \"certificates.mesh.gloo.solo.io/v1\"". The management cluster also needs CRDs for the Gloo Mesh agent. Continue to Step 2, and apply the agent CRDs on your management cluster as well as your remote clusters.

Step 2: Upgrade the CRDs for each remote cluster

  1. Switch your Kubernetes context to the remote cluster.
    kubectl config use-context $REMOTE_CONTEXT
    
  2. Update the Helm repo for Gloo Mesh Enterprise.
    helm repo update
    
  3. Pull the latest Gloo Mesh Enterprise agent Helm chart files.
    helm pull gloo-mesh-agent/gloo-mesh-agent --version $UPGRADE_VERSION --untar
    
  4. Apply the Gloo Mesh CRDs on each remote cluster.
    kubectl apply --context $REMOTE_CONTEXT -f gloo-mesh-agent/charts/gloo-mesh-crds/crds
    kubectl apply --context $REMOTE_CONTEXT-f gloo-mesh-agent/charts/ext-auth-service/crds
    kubectl apply --context $REMOTE_CONTEXT-f gloo-mesh-agent/charts/rate-limiter/crds
    
  5. Repeat the previous step to apply the Gloo Mesh CRDs on the management cluster.

Step 3: Upgrade and verify the Helm installation

  1. Upgrade the Gloo Mesh Helm installation. If you modify Helm chart values, you can pass in the values with --set or --values options.

    helm upgrade gloo-mesh-enterprise gloo-mesh-enterprise/gloo-mesh-enterprise \
    --namespace gloo-mesh \ 
    --set licenseKey=${GLOO_MESH_LICENSE_KEY} \
    --kube-context=${MGMT_CONTEXT} \
    --version ${UPGRADE_VERSION}
    
  2. For each remote cluster, upgrade the Helm installation. If you modify Helm chart values, you can pass in the values with --set or --values options.

    helm upgrade gloo-mesh-agent gloo-mesh-agent/gloo-mesh-agent\
    --kube-context=${REMOTE_CONTEXT1} \
    --namespace gloo-mesh \
    --version ${UPGRADE_VERSION}
    
  3. Set the Kubernetes context to the management cluster and check that your Gloo Mesh Enterprise resources are in a healthy state. This check might take a few seconds to complete.

    kubectl config use-context $MGMT_CONTEXT
    meshctl check server
    
  4. Confirm that the server components such as gloo-mesh-mgmt-server run the version that you upgraded to.

    meshctl version
    

    Example output:

        "server": [
        {
          "Namespace": "gloo-mesh",
          "components": [
            {
              "componentName": "gloo-mesh-mgmt-server",
              "images": [
                {
                  "name": "gloo-mesh-mgmt-server",
                  "domain": "gcr.io",
                  "path": "gloo-mesh-mgmt-server",
                  "version": "2.0.7"
                }
              ]
            },
        

Next steps

Now that you upgraded Gloo Mesh Enterprise, you must upgrade your meshctl CLI to the matching version. Depending on the Gloo Mesh Enterprise version support, you might also want to upgrade Istio or Kubernetes in your clusters.

  1. Upgrade the meshctl CLI to the same version of Gloo Mesh.
  2. Optional: If the new version of Gloo Mesh supports a more recent version of Istio, you can upgrade Istio.
  3. Optional: If the new version of Gloo Mesh supports a more recent version of Kubernetes, you can upgrade Kubernetes on your cluster. For more information, consult your cluster infrastructure provider.