On this page

Upgrade

Upgrade the gloo control plane and any Gloo Gateway proxies that run in your cluster.

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-rc1 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-rc1 before you upgrade to 1.18.0-rc1. 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.16 to 1.18.x, and 1.18.0-rc1 is the latest patch version, upgrade directly to 1.18.0-rc1 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

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.
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.
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.
Set the version to upgrade Gloo Gateway to in an environment variable, such as the latest patch version for open source (1.18.0-rc1) or enterprise (1.18.0-rc1).
- Open source:
```
  export NEW_VERSION=1.18.0-rc1
  
```
- Enterprise edition:
```
  export NEW_VERSION=1.18.0-rc1
  
```

Step 2: Upgrade the `glooctl` CLI

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

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}
  
```
Verify that the client version matches the version you installed.
```
  glooctl version
  
```
Example output:
```
  {
"client": {
  "version": "1.18.0-rc1"
},
  
```

Step 3: Upgrade Gloo Gateway

Install the custom resources of the Kubernetes Gateway API version 1.2.0.

  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

Example output:

  customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created

notifications

If you want to use TCPRoutes to set up a TCP listener on your Gateway, you must install the TCPRoute CRD, which is part of the Kubernetes Gateway API experimental channel. Use the following command to install the CRDs. kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/experimental-install.yaml

Update the Gloo Gateway Helm repositories.
```
  helm repo update
  
```

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

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

Check the deployed CRDs to ensure that none of them are out of date.
```
  glooctl check-crds
  
```

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.
Upgrade the Gloo Gateway Helm installation.
warning
Make sure to include your Helm values when you upgrade either as a configuration file or with --set flags. Otherwise, any previous custom values that you set might be overwritten.
- 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
  
```

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.18.0-rc1@sha256:582ab27a995e9526522f81a9325584aefb528fa4d939455fd285e5148615991b

Confirm that the Gloo Gateway control plane is up and running.
```
  kubectl get pods -n gloo-system
  
```

Upgrade

Considerations link

Testing upgrades link

Patch and minor versions link

Step 1: Prepare to upgrade link

Step 2: Upgrade the glooctl CLI link

Step 3: Upgrade Gloo Gateway link