1.12.0+ Upgrade Notice

Review and apply version-specific changes in Gloo Edge 1.12.x and Gloo Edge Enterprise 1.12.x before upgrading your Gloo Edge installation.

New CRDs are automatically applied to your cluster when performing a helm install operation. However, they are not applied when performing an helm upgrade operation. This is a deliberate design choice on the part of the Helm maintainers, given the risk associated with changing CRDs. Given this limitation, you must apply new CRDs to the cluster before upgrading.

Architectural changes

To reduce cross-pod communication, the gateway functionality is removed from a standalone pod, and is now included in the Gloo Edge control plane pod. Specifically, the validation webhook is moved to the gloo pod, which reduces the number of gRPC calls required for validation.

The following changes apply to your Gloo Edge installation in 1.12.x:

Helm changes

In Gloo Edge v1.12.0 / Gloo Edge Enterprise v1.12.0 and later, the default Gateways, ExtAuth Upstreams, and RateLimit Upstreams are installed via a Job during the Helm installation and upgrade process, instead of being included directly in the Helm chart. After you upgrade to these versions, those resources no longer have Helm annotations (e.g. meta.helm.sh/release-name, meta.helm.sh/release-namespace). If you need to roll back to an earlier Gloo Edge version, you must manually add the Helm release annotations back to these resources before performing the rollback.

Do not manually edit (e.g. kubectl apply or kubectl edit) the Gloo Edge custom resources (e.g. Gateways, Upstreams) that are installed with the Helm chart, as this might cause errors in future upgrades.

If you already manually edited a resource, verify before you upgrade that the resource’s metadata.annotations.kubectl.kubernetes.io/last-applied-configuration annotation does not contain a resourceVersion field. This field can cause conflicts during the upgrade process.

If the field exists, you can remove it in either of the following ways:

  • kubectl edit the resource and manually delete the resourceVersion field from the metadata.annotations.kubectl.kubernetes.io/last-applied-configuration annotation, or
  • remove the metadata.annotations.kubectl.kubernetes.io/last-applied-configuration annotation altogether if not needed, e.g. kubectl annotate gateway -n gloo-system gateway-proxy kubectl.kubernetes.io/last-applied-configuration-

CRD changes

New and updated CRDs

Deprecated CRDs None

Removed CRDs None

Upgrade steps

To upgrade Gloo Edge:

  1. Follow steps 1 - 2 in Upgrade Steps to prepare for upgrading, and to upgrade glooctl.

  2. Apply the new and updated CRDs. Replace the version with the specific patch version that you are upgrading to.

    helm repo update
    helm pull gloo/gloo --version 1.12.0 --untar
    kubectl apply -f gloo/crds
    helm repo update
    helm pull glooe/gloo-ee --version 1.12.0 --untar
    kubectl apply -f gloo-ee/charts/gloo/crds
    # If Gloo Federation is enabled
    kubectl apply -f gloo-ee/charts/gloo-fed/crds
  3. Prepare for any updates you want to make related to the gateway architectural changes. For example, you might want to create a Helm values file to pass gateway environment variables to the gloo pod during the Helm upgrade, or update any systems that watch for snapshot metrics.

  4. Continue to upgrade the Gloo Edge server components via Helm.

  5. If you use the spec.configs.oauth2.oidcAuthorizationCode.headers.accessTokenHeader: "Authorization" setting in any AuthConfig resources, and you do not want to add the “Bearer” prefix to the header, set useBearerSchemaForAuthorization to false. If you do not set this setting, it will default to true in Gloo Edge 1.13.