Upgrade Steps

This upgrade process is not suitable in environments where downtime is unacceptable. Depending on your Gloo version, configured probes, and external infrastructure (e.g. external load-balancer to Gloo) additional steps may need to be taken. This guide is targeted toward users that are upgrading Gloo while experimenting in dev or staging environments.

This guide assumes that you are running open source Gloo in Kubernetes.

In this guide, we’ll walk you through how to upgrade Gloo. First you’ll want to familiarize yourself with our various Changelog entry types so that you can review the changes that have been made in the release you are upgrading to.

Once you have reviewed the changes in the new release, there are two components to upgrade:

Before upgrading, always make sure to check our changelogs (refer to our open-source or enterprise changelogs) for any mention of breaking changes. In some cases, a breaking change may mean a slightly different upgrade procedure; if this is the case, then we will take care to explain what must be done in the changelog notes and an upgrade notice in the docs.

You may also want to scan our frequently-asked questions to see if any of those cases apply to you. Also feel free to post in the #gloo or #gloo-enterprise rooms of our public Slack if your use case doesn’t quite fit the standard upgrade path.

We version open-source Gloo separately from Gloo Enterprise. This is because Gloo Enterprise pulls in open-source Gloo as a dependency. While the patch versions of Gloo and Gloo Enterprise may drift apart from each other, we will maintain the same major/minor versions across the two projects. So for example, we may be at version x.y.a in open-source Gloo and x.y.b in Gloo Enterprise. x and y will always be the same, but a and b will often not be the same. This is why, if you are a Gloo Enterprise user, you may see different versions reported by glooctl version. We will try to ensure that open-source Gloo and Gloo Enterprise will be compatible each other across patch versions, but make no guarantees about compatibility between minor or major versions.


Visit https://semver.org/ for an explanation of semantic versioning if you are unfamiliar with these concepts.


~ > glooctl version # snipped some content for brevity
Client: {"version":"0.20.13"} # glooctl is built from open-source Gloo, which is where its version comes from
Server: {"type":"Gateway","enterprise":true,"kubernetes":...,{"Tag":"0.20.8","Name":"grpcserver-ee","Registry":"quay.io/solo-io"},...,{"Tag":"0.20.13","Name":"discovery","Registry":"quay.io/solo-io"},...}

# above we see the Gloo Enterprise API server running enterprise version 0.20.8,
# which has pulled in open-source Gloo 0.20.13 as a dependency.

If you are an open-source user of Gloo, you will only need to be aware of open-source versions found in our open-source changelogs. If you are an enterprise user of Gloo, you will be selecting versions of Gloo Enterprise from our Enterprise changelogs. However, you may need to be aware of the version of open-source Gloo included as a dependency in Gloo Enterprise, as most of our proto definitions are open-source. Changes to the open-source version will be listed as “Dependency Bumps”, and significant changes may be listed as “Breaking Changes” in our changelog entries.

Upgrading Components

After upgrading a component, you should be sure to run glooctl check immediately afterwards. glooctl check will scan Gloo for problems and report them back to you. A problem reported by glooctl check means that Gloo is not working properly and that Envoy may not be receiving updated configuration.

Upgrading glooctl

It is important to try to keep the version of glooctl in alignment with the version of the Gloo server components running in your cluster. Because glooctl can create resources in your cluster (for example, with glooctl add route), you may see errors in Gloo if you create resources from a version of glooctl that is incompatible with the version of the server components.

Using glooctl Itself

The easiest way to upgrade glooctl is to simply run glooctl upgrade, which will attempt to download the latest binary. There are more fine-grained options available; those can be viewed by running glooctl upgrade --help. One in particular to make note of is glooctl upgrade --release, which can be useful in maintaining careful control over what version you are running.

Here is an example where we notice we have a version mismatch between glooctl and the version of Gloo running in our minikube cluster (1.2.0 and 1.2.1 respectively), and we correct it:

~ > glooctl version
Client: {"version":"1.2.0"}
Server: {"type":"Gateway","kubernetes":{"containers":[{"Tag":"1.2.1","Name":"discovery","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gateway","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gloo-envoy-wrapper","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gloo","Registry":"quay.io/solo-io"}],"namespace":"gloo-system"}}
~ > glooctl upgrade --release v1.2.1
downloading glooctl-darwin-amd64 from release tag v1.2.1
successfully downloaded and installed glooctl version v1.2.1 to /usr/local/bin/glooctl
~ > glooctl version
Client: {"version":"1.2.1"}
Server: {"type":"Gateway","kubernetes":{"containers":[{"Tag":"1.2.1","Name":"discovery","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gateway","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gloo-envoy-wrapper","Registry":"quay.io/solo-io"},{"Tag":"1.2.1","Name":"gloo","Registry":"quay.io/solo-io"}],"namespace":"gloo-system"}}
~ > glooctl check
Checking deployments... OK
Checking pods... OK
Checking upstreams... OK
Checking upstream groups... OK
Checking secrets... OK
Checking virtual services... OK
Checking gateways... OK
Checking proxies... OK
No problems detected.

Download Release Asset

You can find glooctl built for every platform in our release artifacts. For example, see our release assets for v1.0.0: https://github.com/solo-io/gloo/releases/tag/v1.0.0

Upgrading the Server Components

Note that you may encounter downtime without the proper probes and healthchecks setup before attempting the upgrade. For more detailed upgrade instructions for production setup, we recommend looking at the upgrade guide associated for your version (for example, the 1.3.0+ upgrade guide).

We create a Kubernetes Job named gateway-certgen to generate a cert for the validation webhook. We attempt to put a ttlSecondsAfterFinished value on the job so that it gets cleaned up automatically, but as this setting is still in Alpha, your cluster may ignore this value. If that is the case, you may run into an issue while upgrading where the upgrade attempts to change the gateway-certgen job, but the update fails because the job is immutable. If you run into this, simply delete the job, which should have completed long before, and re-apply the upgrade.

Using Helm

For Enterprise users of Gloo, the process with either Helm 2 or 3 is the same. You’ll just need to set your license key during installation by using --set license_key="$license" (or include the line license_key: $LICENSE-KEY in your values file).

Get a trial Enterprise license at https://www.solo.io/gloo-trial.

While it is possible to upgrade from open source Gloo to enterprise Gloo using helm upgrade, you may have to take additional steps to ensure there is no downtime because the charts do not have the exact same helm values.

Helm 3

If we have Gloo released under the Helm release name gloo to gloo-system, upgrading the server components is easy:

~ > helm upgrade -n gloo-system gloo gloo/gloo --version=v1.2.1
Release "gloo" has been upgraded. Happy Helming!
NAME: gloo
LAST DEPLOYED: Thu Dec 12 12:22:16 2019
NAMESPACE: gloo-system
STATUS: deployed
REVISION: 2
TEST SUITE: None

Verify that Gloo has the expected version:

~ > kubectl -n gloo-system get pod -l gloo=gloo -ojsonpath='{.items[0].spec.containers[0].image}'
quay.io/solo-io/gloo:1.2.1
Helm 2

Using Helm 2 with open source Gloo v1.2.3 and later or Gloo Enterprise v1.2.0 and later requires explicitly setting crds.create=true on the first install, as this is how we are managing compatibility between Helm 2 and 3.

Helm upgrade command should just work:

~ > helm upgrade gloo gloo/gloo --namespace gloo-system

If you’d rather delete and reinstall to get a clean slate, take care to manage your CRDs as Helm v2 does not support managing CRDs. As a result, if you try to upgrade through deleting a helm release (helm delete --purge gloo) and reinstalling via helm install, you may encounter an error stating that a CRD already exists.

~ > helm install gloo/gloo --name gloo --namespace gloo-system --set crds.create=true
Error: customresourcedefinitions.apiextensions.k8s.io "authconfigs.enterprise.gloo.solo.io" already exists

To successfully reinstall, run the same install command with crds.create=false.