Upgrade legacy installations

Upgrade Gloo Platform minor and patch versions for the management server and agent in each cluster.

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.

Before you begin

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

   • AWS Lambda integration: In 2.3, the Gloo custom resources for the AWS Lambda integration are changed in the following breaking ways. If you used the AWS Lambda integration in 2.2, you must create copies of your existing resources in the new format before you upgrade. After the upgrade is complete, you can delete the old resources in the outdated format. To see the updated format, check out the Lambda integration documentation.
     • The CloudProvider and CloudResources CRs are moved from the networking.gloo.solo.io/v2 API group to the infrastructure.gloo.solo.io/v2 API group. You must delete the old cloudproviders.networking.gloo.solo.io and cloudresources.networking.gloo.solo.io CRDs before you upgrade your installation.
     • The logicalName field is removed from the CloudResources CR.
     • Routes for Lambda functions in RouteTable CRs now use a new destination type, awsLambda.
     • The WRAP_AS_API_GATEWAY, UNWRAP_AS_API_GATEWAY, and UNWRAP_AS_ALB transformation settings are removed from the RouteTable CR, as the transformation functionality from these settings is now included in the REQUEST_DEFAULT and RESPONSE_DEFAULT transformations.

2. Check that your underlying Kubernetes platform runs a supported version for the Gloo version that you want to upgrade to.

   1. Review the supported versions.
   2. Compare the supported version against the version of Kubernetes that you run in your clusters.
   3. If necessary, upgrade Kubernetes. Consult your cluster infrastructure provider.

3. In your terminal, set the following environment variables to use in the subsequent steps, such as your target Gloo version.

   # Set the Gloo Gateway version as an environment variable. The latest version is used as an example. You can find other versions in the Changelog documentation.
   export UPGRADE_VERSION=2.3.22
      
   # Save the kubeconfig contexts for your clusters as environment variables. 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
      
   # Set your Gloo Gateway license key as an environment variable. If you do not have one, contact an account representative.
   export GLOO_GATEWAY_LICENSE_KEY=<your-key>
   

Step 1: Upgrade the CRDs for your management cluster

1. Remove CRDs that are deprecated in 2.3.

   kubectl --context $MGMT_CONTEXT delete crd apischemas.apimanagement.gloo.solo.io
   kubectl --context $MGMT_CONTEXT delete crd cloudproviders.networking.gloo.solo.io
   kubectl --context $MGMT_CONTEXT delete crd cloudresources.networking.gloo.solo.io
   

2. Update the Helm repo in the management cluster for Gloo.

   helm repo add gloo-mesh-enterprise https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-enterprise
   helm repo update --kube-context $MGMT_CONTEXT
   

3. Pull the latest Gloo Helm chart files.

   helm pull gloo-mesh-enterprise/gloo-mesh-enterprise --kube-context $MGMT_CONTEXT --version $UPGRADE_VERSION --untar
   

4. Apply the Gloo custom resource definitions (CRDs) on your management cluster.

   kubectl apply --context $MGMT_CONTEXT -f gloo-mesh-enterprise/charts/gloo-mesh-crds/crds/
   

Step 2: Upgrade the CRDs for each workload cluster

1. Update the Helm repo in your workload cluster for Gloo. If you have a single cluster, the $REMOTE_CONTEXT is the same as the $MGMT_CONTEXT.

   helm repo add gloo-mesh-agent https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-agent
   helm repo update --kube-context $REMOTE_CONTEXT
   

2. Pull the latest Gloo agent Helm chart files.

   helm pull gloo-mesh-agent/gloo-mesh-agent --version $UPGRADE_VERSION --kube-context $REMOTE_CONTEXT --untar
   

3. If you used the AWS Lambda integration in Gloo Gateway 2.2, delete the deprecated CRDs.

   kubectl --context $REMOTE_CONTEXT delete crd cloudproviders.networking.gloo.solo.io
   kubectl --context $REMOTE_CONTEXT delete crd cloudresources.networking.gloo.solo.io
   

4. Apply the Gloo CRDs on each workload 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 steps 3 and 4 for each workload cluster.

Step 3: Get your Helm chart values

As part of the upgrade, you can update or reuse the Helm chart values for your Gloo management server, agent, and any add-ons that you might have such as rate limiting and external authentication services.

1. Get your Helm chart values configuration file for your current version. Review the following options:

   • Reuse the existing Helm chart values configuration file for your current installation
   • Get the Helm chart values for your current installation
   • Show the default Helm chart values for the current version
   • Reuse values file
   • Get current values
   • Show default values

   When you installed Gloo, you might have used a Helm chart values configuration file to customize your installation. This file might be stored in your CI/CD pipeline, such as in a Git repository. The installation instructions used the following file names.
   
   Helm installations:

   • Single cluster: Both Gloo management server and agent in single-cluster-values.yaml, based on this sample values file.
   • Multicluster: Separate installations for the Gloo management server and agent.
     • Management server: mgmt-server-values.yaml, based on this sample values file.
     • Agent: agent-values.yaml, based on this sample values file.
   • Rate limiting and external authentication add-ons: values.yaml.

   Getting started or meshctl installations:

   • Single cluster: Both Gloo management server and agent in gs-single-values.yaml, based on this sample values file.
   • Multicluster: values-register.yaml. Note that this sample values file was used only for the agent installation, because default Helm values were used for the management server installation. To get a values file for the management server installation, you can run helm -n gloo-mesh get all gloo-mgmt --kube-context $MGMT_CONTEXT > values-mgmt-plane-env.yaml, and use the values listed after COMPUTED VALUES: for your Helm values file.

   If you do not have the original values files that you used at installation time, you can get the values for the current Helm release in your clusters.

   1. Get the values for the current Helm releases.
      • Management server: Note that if the release name gloo-mgmt is not found, your Helm release might be named gloo-mesh-enterprise instead.

        helm -n gloo-mesh get all gloo-mgmt --kube-context $MGMT_CONTEXT > values-mgmt-plane-env.yaml
        open values-mgmt-plane-env.yaml
        

      • Agent: Note that if the release name gloo-agent is not found, your Helm release might be named gloo-mesh-agent instead.

        helm -n gloo-mesh get all gloo-agent --kube-context $REMOTE_CONTEXT > values-data-plane-env.yaml
        open values-data-plane-env.yaml
        

      • Rate limiting and external authentication add-ons:

        helm -n gloo-mesh get all gloo-agent-addons --kube-context $REMOTE_CONTEXT > values.yaml
        open values.yaml
        

   2. In each file, delete the lines up to and including the USER-SUPPLIED VALUES: line, and delete all lines including and after the COMPUTED VALUES line. Save the file.

   You can get the default values for the Helm chart at the version of your installation, which you can check by running meshctl version.

   • Management server:

     helm show values gloo-mesh-enterprise/gloo-mesh-enterprise --version $CURRENT_VERSION > mgmt-server-values.yaml
     

   • Agent:

     helm show values gloo-mesh-agent/gloo-mesh-agent --version $CURRENT_VERSION > agent-values.yaml
     

2. Compare your current Helm chart values with the version that you want to upgrade to. You can get a values file for the upgrade version with the helm show values command.

   • Management server:

     helm show values gloo-mesh-enterprise/gloo-mesh-enterprise --version $UPGRADE_VERSION > mgmt-server-values-env.yaml
     

   • Agent:

     helm show values gloo-mesh-agent/gloo-mesh-agent --version $UPGRADE_VERSION > agent-values-env.yaml
     

3. Review the changelog for any Helm Changes that might require modifications to your Helm chart.

4. Edit the Helm chart values file or prepare the --set flags to make any changes that you want. If you do not want to use certain settings, comment them out.

   For example, you might modify the following settings during an upgrade.

   • The Gloo image.tag value for the version that you want to upgrade to.
   • Istio images.hub and images.tag fields for the Solo distribution of Istio that you want to use.
   • The relay section for custom certificates to use to establish mTLS between the management server and agent.
   • The rate-limiter and ext-auth-service sections in the agent chart.

   Need to make changes after you upgrade? You can update these settings later. For more information, see Modify Helm chart values.

Step 4: Upgrade and verify the Helm installation

1. Upgrade the Gloo Gateway Helm installation. Make sure to update any --set or --values options, such as the values file name. For example, if you installed Gloo in a single-cluster environment using meshctl, your values file might be named gs-single-values.yaml instead. Note: If the release name gloo-mgmt is not found, your Helm release might be named gloo-mesh-enterprise instead.

   helm upgrade gloo-mgmt gloo-mesh-enterprise/gloo-mesh-enterprise \
   --namespace gloo-mesh \
   --set glooGatewayLicenseKey=${GLOO_GATEWAY_LICENSE_KEY} \
   --kube-context=${MGMT_CONTEXT} \
   --version ${UPGRADE_VERSION} \
   --values values-mgmt-plane-env.yaml
   

2. Multicluster installations: Upgrade the Helm installation in your workload cluster. Make sure to update any --set or --values options, such as the values file name. For example, if you installed Gloo in a multicluster environment using meshctl, your values file might be named values-register.yaml instead. Note: If the release name gloo-agent is not found, your Helm release might be named gloo-mesh-agent instead.

   helm upgrade gloo-agent gloo-mesh-agent/gloo-mesh-agent \
   --kube-context=${REMOTE_CONTEXT} \
   --namespace gloo-mesh \
   --version ${UPGRADE_VERSION} \
   --values values-data-plane-env.yaml
   

3. Optional: Upgrade the Gloo external auth or rate limiting services. If you already enabled these services in the single cluster or agent installation, or you do not use these services, you can skip this step.

   helm upgrade gloo-agent-addons gloo-mesh-agent/gloo-mesh-agent \
   --kube-context=${REMOTE_CONTEXT} \
   --namespace gloo-mesh-addons \
   --version ${UPGRADE_VERSION} \
   --values values.yaml
   

4. Multicluster installations: Repeat steps 2 - 3 for each workload cluster.

5. Optional: Check that the Gloo management and agent resources are connected. See Step 1 of Debug the management server and relay connection.

6. Confirm that the server components such as gloo-mesh-mgmt-server run the version that you upgraded to.

   meshctl version --kubecontext ${MGMT_CONTEXT}
   

   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.3.22"
              }
            ]
          },
      

7. Confirm that the agent components such as gloo-mesh-agent run the version that you upgraded to. If you have a single cluster, the $REMOTE_CONTEXT is the same as the $MGMT_CONTEXT.

   meshctl version --kubecontext ${REMOTE_CONTEXT}
   

   Example output:

      {
            "componentName": "gloo-mesh-agent",
            "images": [
              {
                "name": "gloo-mesh-agent",
                "domain": "gcr.io",
                "path": "gloo-mesh/gloo-mesh-agent",
                "version": "2.3.22"
              }
            ]
          },
      

Next steps

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

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

Update your Gloo license

Before your Gloo license expires, you can update the license by patching the license key secret. If you use Gloo Gateway along with other Gloo products such as Gloo Mesh and Gloo Network, you can also update those licenses.

To update your license, see the Licensing documentation.