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.19.0 to 1.19.0-beta2 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.19.0, first upgrade your installation to 1.19.0-beta2 before you upgrade to 1.19.0-beta2. 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.18.2 to 1.19.x, and 1.19.0-beta2 is the latest patch version, upgrade directly to 1.19.0-beta2 and skip any previous patch versions. Do not upgrade to a lower patch version, such as 1.19.0, 1.19.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.
- Find the latest patch of your minor version by checking the Open source changelog or Enterprise changelog.
- Follow this upgrade guide to upgrade to the latest patch for your current minor version.
- 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.
- Review the supported versions for dependencies such as Kubernetes, Istio, Helm, and more.
- Compare the supported version against the versions that you currently use.
- 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.19.0-beta2
) or enterprise (1.18.1
).- Open source:
export NEW_VERSION=1.19.0-beta2
- Enterprise edition:
export NEW_VERSION=1.18.1
- Open source:
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.1" },
Step 3: Upgrade Gloo Gateway
Install the custom resources of the Kubernetes Gateway API version 1.2.1.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/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
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.1/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
- Open source:
- Check the deployed CRDs to ensure that none of them are out of date.
glooctl check-crds
- Download and apply the new CRDs.
Make any changes to your Helm values.
Get the Helm values file for your current version.
helm get values gloo -n gloo-system -o yaml > gloo-gateway.yaml open gloo-gateway.yaml
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
- Open source:
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.
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 gloo/gloo \ -f gloo-gateway.yaml \ --version=$NEW_VERSION
- Enterprise edition:
helm upgrade -n gloo-system gloo glooe/gloo-ee \ -f gloo-gateway.yaml \ --version=$NEW_VERSION
- Open source:
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.1@sha256:...
Confirm that the Gloo Gateway control plane is up and running.
kubectl get pods -n gloo-system