You can use this guide to upgrade the version of your Gloo Gateway components, or to apply changes to the components’ configuration settings.

Considerations

Consider the following rules before you plan your Gloo Gateway upgrade.

Testing upgrades

During the upgrade, pods that run the new version of the control plane and proxies are created. Then, the old pods are terminated. Because zero downtime is not guaranteed, try testing the upgrade in a staging environment before upgrading your production environment.

Patch and minor versions

Patch version upgrades:

  • You can skip patch versions within the same minor release. For example, you can upgrade from version 1.18.0 to 1.18.0-beta18 directly, and skip the patch versions in between.

Minor version upgrades:

  • Before you upgrade the minor version, always upgrade your current minor version to the latest patch. For example, if you currently run Gloo Gateway open source version 1.18.0, first upgrade your installation to 1.18.0-beta18 before you upgrade to 1.18.0-beta18. This ensures that your current environment is up-to-date with any bug fixes or security patches before you begin the minor version upgrade process.
  • Always upgrade to the latest patch version of the target minor release. For example, if you want to upgrade from open source version 1.17.7 to 1.18.x, and 1.18.0-beta18 is the latest patch version, upgrade directly to 1.18.0-beta18 and skip any previous patch versions. Do not upgrade to a lower patch version, such as 1.18.0, 1.18.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 1.16.x to 1.18.x, you must first upgrade to the latest patch version of the 1.17 minor release. After you upgrade to 1.17.x, you can then plan your upgrade to the latest patch version of the 1.18.x release.

Step 1: Prepare to upgrade

  1. Minor version upgrades: Before you upgrade to a new minor version, first upgrade your current minor version to the latest patch.

    1. Find the latest patch of your minor version by checking the Open source changelog or Enterprise changelog.
    2. Follow this upgrade guide to upgrade to the latest patch for your current minor version.
    3. Then, you can repeat the steps in this guide to upgrade to the latest patch of the next minor version.

  2. Review changes from the previous version. Make sure that you review the breaking changes 🔥 that were introduced in this release and the impact that they have on your current environment.

  3. Check that your underlying infrastructure platform, such as Kubernetes, and other dependencies run supported versions for the Gloo Gateway version that you want to upgrade to.

    1. Review the supported versions for dependencies such as Kubernetes, Istio, Helm, and more.
    2. Compare the supported version against the versions that you currently use.
    3. If necessary, upgrade your dependencies, such as consulting your cluster infrastructure provider to upgrade the version of Kubernetes that your cluster runs.

  4. Set the version to upgrade Gloo Gateway to in an environment variable, such as the latest patch version for open source (1.18.0-beta18) or enterprise (1.17.1).

    • Open source:
        export NEW_VERSION=1.18.0-beta18
    • Enterprise edition:
        export NEW_VERSION=1.17.1

Step 2: Upgrade the glooctl CLI

Upgrade the glooctl CLI to the version of Gloo Gateway you want to upgrade to.

  1. Upgrade glooctl to the new version. Note that this command only updates the CLI binary version, and does not upgrade your Gloo Gateway installation.

      glooctl upgrade --release v${NEW_VERSION}

  2. Verify that the client version matches the version you installed.

      glooctl version

    Example output:

      {
"client": {
  "version": "1.17.1"
},

Step 3: Upgrade Gloo Gateway

  1. Update the Gloo Gateway Helm repositories.

      helm repo update

  2. Apply the Gloo custom resource definitions (CRDs) for the upgrade version.

    1. Download and apply the new CRDs.
      • Open source:
          helm pull gloo/gloo --version $NEW_VERSION --untar
kubectl apply -f gloo/crds
      • Enterprise edition:
          helm pull glooe/gloo-ee --version $NEW_VERSION --untar
kubectl apply -f gloo-ee/charts/gloo/crds
    2. Check the deployed CRDs to ensure that none of them are out of date.
        glooctl check-crds

  3. Make any changes to your Helm values.

    1. Get the Helm values file for your current version.

        helm get values gloo-gateway -n gloo-system -o yaml > gloo-gateway.yaml
open gloo-gateway.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.

      • Open source:
          helm show values gloo/gloo --version $NEW_VERSION > all-values.yaml
open all-values.yaml
      • Enterprise edition:
          helm show values glooe/gloo-ee --version $NEW_VERSION > all-values.yaml

    3. Make any changes that you want, such as modifications required for breaking changes or to enable new features, by editing your gloo-gateway.yaml Helm values file or preparing the --set flags.

  4. Upgrade the Gloo Gateway Helm installation.

    • Open source:
        helm upgrade -n gloo-system gloo-gateway gloo/gloo \
   -f gloo-gateway.yaml \
   --version=$NEW_VERSION
    • Enterprise edition:
        helm upgrade -n gloo-system gloo-gateway glooe/gloo-ee \
   -f gloo-gateway.yaml \
   --version=$NEW_VERSION

  5. Verify that Gloo Gateway runs the upgraded version.

      kubectl -n gloo-system get pod -l gloo=gloo -ojsonpath='{.items[0].spec.containers[0].image}'

    Example output:

      quay.io/solo-io/gloo-ee:1.17.1@sha256:582ab27a995e9526522f81a9325584aefb528fa4d939455fd285e5148615991b

  6. Confirm that the Gloo Gateway control plane is up and running.

      kubectl get pods -n gloo-system