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.

Considerations

Consider the following rules before you plan your Gloo Network for Cilium upgrade.

Patch and minor versions

Patch version upgrades:
You can skip patch versions within the same minor release. For example, you can upgrade from version 2.5.0 to 2.5.0 directly, and skip the patch versions in between.

Minor version upgrades:

  • Always upgrade to the latest patch version of the target minor release. For example, if you want to upgrade from version 2.4.7 to 2.5.x, and 2.5.0 is the latest patch version, upgrade to that version and skip any previous patch versions for that minor release. Do not upgrade to a lower patch version, such as 2.5.0, 2.5.1, and so on.
  • Do not skip minor versions during your upgrade. Upgrade minor release versions one at a time. For example, if you want to upgrade from 2.3.x to 2.5.x, you must first upgrade to the latest patch version of the 2.4 minor release. After you upgrade to 2.4.x, you can then plan your upgrade to the latest patch version of the 2.5.x release.

Multicluster only: Version skew policy for management and remote clusters

Plan to always upgrade your Gloo management server and agents to the same target version. Always upgrade the Gloo management server first. Then, roll out the upgrade to the Gloo agents in your workload clusters. During this upgrade process, your management server and agents can be one minor version apart.

For example, let’s say you want to upgrade from 2.4.7 to 2.5.x. Start by upgrading your management server to the latest patch version of the 2.5 minor release. Your management server and agent are still compliant as they are one minor version apart. Then, roll out the 2.5 minor release upgrade to the agents in your workload clusters.

If you plan to upgrade more than one minor releases, you must perform one minor release upgrade at a time. For example, to upgrade your management server and agent from 2.3.x to 2.5.x, you upgrade your management server to the latest patch version of the 2.4 minor release first. Your management server and agent are compliant because they are one minor version apart. Then, you upgrade your agents to the 2.4 minor release. After you verify the 2.4 upgrade, use the same approach to upgrade the management server and agents from 2.4 to the target 2.5 minor release.

If both your management server and agent run the same minor version, the agent can run any patch version that is equal or lower than the management server’s patch version.

Consider the following example version skew scenarios:

Supported?Management server versionAgent versionRequirement
2.4.42.4.2The management server and agents run the same minor version. The agent patch version is equal to or lower than the management server.
2.4.42.4.5The agent runs the same minor version as the server, but has a patch version greater than the server.
2.4.42.3.4The agent runs a minor version no greater than n-1 behind the server.
2.4.42.2.9The agent runs a minor version that is greater than n-1 behind the server.

Step 1: Prepare to upgrade

  1. Check that your underlying Kubernetes platform and Cilium CNI run supported versions for the Gloo Network version that you want to upgrade to.

    1. Review the supported versions.
    2. Compare the supported version against the versions of Kubernetes and Cilium that you run in your clusters.
    3. If necessary, consult your cluster infrastructure provider to upgrade Kubernetes to a version that is supported by the Gloo Network version that you want to upgrade to.
  2. Set the Gloo Network version that you want to upgrade to as an environment variable. The latest version is used as an example. Append -fips for a FIPS-compliant image, such as 2.5.0-fips. Do not include v before the version number.

      export UPGRADE_VERSION=2.5.0
      

Step 2: Upgrade the meshctl CLI

Upgrade the meshctl CLI to the version of Gloo Network you want to upgrade to.

  1. Re-install meshctl to the upgrade version.

      curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v$UPGRADE_VERSION sh -
      
  2. Verify that the client version matches the version you installed.

      meshctl version
      

    Example output:

      {
    "client": {
      "version": "2.5.0"
    },
      

Step 3: Upgrade Gloo Network

Upgrade your Gloo Network installation. The steps differ based on whether you run Gloo Network in a single-cluster or multicluster environment.

Single cluster

  1. Update the gloo-platform Helm repo.

      helm repo add gloo-platform https://storage.googleapis.com/gloo-platform/helm-charts
    helm repo update
      
  2. Apply the Gloo custom resource definitions (CRDs) for the upgrade version.

      helm upgrade -i gloo-platform-crds gloo-platform/gloo-platform-crds \
        --namespace gloo-mesh \
        --version $UPGRADE_VERSION \
        --set installEnterpriseCrds=false
      
  3. Get the Helm values files for your current version.

      helm get values gloo-platform -n gloo-mesh -o yaml > gloo-network-single-cluster.yaml
    open gloo-network-single-cluster.yaml
      
  4. 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.

      helm show values gloo-platform/gloo-platform --version $UPGRADE_VERSION > all-values.yaml
      
  5. Make any changes that you want by editing your gloo-network-single-cluster.yaml Helm values files or preparing the --set flags. If you do not want to use certain settings, comment them out.

  6. Upgrade the Gloo Network Helm installation.

      helm upgrade gloo-platform gloo-platform/gloo-platform \
        --kube-context $MGMT_CONTEXT \
        --namespace gloo-mesh \
        -f gloo-network-single-cluster.yaml \
        --version $UPGRADE_VERSION
      
  7. Confirm that Gloo components, such as the 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.5.0"
            }
          ]
        },

Multicluster

  1. Update the gloo-platform Helm repo.

      helm repo add gloo-platform https://storage.googleapis.com/gloo-platform/helm-charts
    helm repo update
      
  2. Get the Helm values files for your current version.

    1. Get your current values for the management cluster.
        helm get values gloo-platform -n gloo-mesh -o yaml --kube-context $MGMT_CONTEXT > control-plane.yaml
      open control-plane.yaml
        
    2. Get your current values for the workload clusters.
        helm get values gloo-platform -n gloo-mesh -o yaml --kube-context $REMOTE_CONTEXT > data-plane.yaml
      open data-plane.yaml
        
  3. 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.

      helm show values gloo-platform/gloo-platform --version $UPGRADE_VERSION > all-values.yaml
      
  4. Make any changes that you want by editing your control-plane.yaml and data-plane.yaml Helm values files or preparing the --set flags. If you do not want to use certain settings, comment them out.

  5. Upgrade the Gloo Network Helm releases in your management cluster.

    1. Apply the Gloo custom resource definitions (CRDs) for the upgrade version in the management cluster.
        helm upgrade -i gloo-platform-crds gloo-platform/gloo-platform-crds \
          --kube-context $MGMT_CONTEXT \
          --namespace gloo-mesh \
          --version $UPGRADE_VERSION \
          --set installEnterpriseCrds=false
        
    2. Upgrade your Helm release in the management cluster. Make sure to include your Helm values when you upgrade either as a configuration file in the --values flag or with --set flags. Otherwise, any previous custom values that you set might be overwritten.
        helm upgrade gloo-platform gloo-platform/gloo-platform \
          --kube-context $MGMT_CONTEXT \
          --namespace gloo-mesh \
          -f control-plane.yaml \
          --version $UPGRADE_VERSION
        
    3. Confirm that the control plane components, such as the 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.5.0"
              }
            ]
          },
  6. Upgrade the Gloo Network Helm releases in your workload clusters. Repeat these steps for each workload cluster, and be sure to update the cluster context each time.

    1. Apply the Gloo custom resource definitions (CRDs) for the upgrade version in each workload cluster.

        helm upgrade -i gloo-platform-crds gloo-platform/gloo-platform-crds \
          --kube-context $REMOTE_CONTEXT \
          --namespace=gloo-mesh \
          --version=$UPGRADE_VERSION \
          --set installEnterpriseCrds=false
        
    2. Upgrade your Helm release in each workload cluster. Make sure to include your Helm values when you upgrade either as a configuration file in the --values flag or with --set flags. Otherwise, any previous custom values that you set might be overwritten.

        helm upgrade gloo-platform gloo-platform/gloo-platform \
          --kube-context $REMOTE_CONTEXT \
          --namespace gloo-mesh \
          -f data-plane.yaml \
          --version $UPGRADE_VERSION
        
    3. Confirm that the data plane components, such as the gloo-mesh-agent, run the version that you upgraded to.

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

  7. Check that the Gloo management and agent components are connected.

      meshctl check --kubecontext $MGMT_CONTEXT
      

Upgrade the Cilium CNI

To upgrade the Cilium CNI in your clusters, such as to update the version of the Solo distribution of the Cilium image or to change a setting, you can follow the upgrade guide in the Cilium documentation.

  1. To ensure your Helm values are not overwritten, save your current Helm values for the Cilium CNI installation.

      helm get values cilium -n kube-system -o yaml > solo-cilium.yaml
      
  2. Follow the upgrade guide in the Cilium documentation. In the helm install and helm upgrade commands, be sure to pass in your Helm values by using the -f solo-cilium.yaml flag.

Update your Gloo license

Before your Gloo license expires, you can update the license by patching the license key secret.

For example, if you notice that your Gloo control plane deployments are in a crash loop, your Gloo license might be expired. You can check the status of your license with the following command:

  meshctl check
  

Example output for an expired license:

  🔴 License status

ERROR A license is expired. To update, see https://docs.solo.io/gloo-mesh-enterprise/main/setup/prepare/licensing/#update-licenses
INFO  gloo-network license expiration is 06 Feb 23 13:05 CDT
  

To update your license key in your Gloo installation:

  1. Get a new Gloo license key by contacting your account representative.
  2. Save the new license key as an environment variable.
      export GLOO_NETWORK_LICENSE_KEY=<new-key-string>
      
  3. Update the license secret to use the new Gloo Network license key.
      kubectl -n gloo-mesh patch secret license-keys -p "stringData: { gloo-network-license-key: $GLOO_NETWORK_LICENSE_KEY }"
      
  4. Optional: If your license expired and the management server pods are in a crash loop, restart the management server pods. If you updated the license before expiration, skip this step.
      kubectl rollout restart -n gloo-mesh deployment/gloo-mesh-mgmt-server --context ${MGMT_CONTEXT}
      
  5. Verify that your license check is now valid, and no errors are reported.
      meshctl check --kubecontext ${MGMT_CONTEXT}
      
    Example output:
      🟢 License status
    
    INFO  gloo-network enterprise license expiration is 25 Aug 24 10:38 CDT