Project: Gloo (Orchestration & Management / API Gateway)
File: faq.md

title: Prepare to upgrade weight: 10 description: Prepare your environment, review version changes, and review FAQs before you upgrade Gloo Edge. Before you upgrade Gloo Edge, complete the following preparatory steps: , such as upgrading your current version to the latest patch and upgrading any dependencies to the required supported versions. made to Gloo Edge in version {{< readfile file="static/content/versiongeosslatest_minor.md" markdown="true">}}1.16, including CRD, Helm, CLI, and feature changes. about the upgrade process. Review the following preparatory steps that might be required for your environment. Before you upgrade your minor version, first upgrade your current version to the latest patch. For example, if you currently run Gloo Edge Enterprise version {{< readfile file="static/content/versiongeen-1oldpatch.md" markdown="true">}}, first upgrade your installation to version {{< readfile file="static/content/versiongee_n-1.md" markdown="true">}}. 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. Find the latest patch of your minor version by checking the or . Go to the documentation set for your current minor version. For example, if you currently run Gloo Edge Enterprise version {{< readfile file="static/content/versiongeen-1oldpatch.md" markdown="true">}}, use the drop-down menu in the header of this page to select **v{{< readfile file="static/content/versiongeossn-1minor.md" markdown="true">}}.x. Follow the upgrade guide, using the latest patch for your minor version. If you plan to upgrade to a version that is more than one minor version greater than your current version, such as to version {{< readfile file="static/content/versiongeosslatestminor.md" markdown="true">}} from {{< readfile file="static/content/versiongeossn-2minor.md" markdown="true">}} or older, you must upgrade incrementally. For example, you must first use the upgrade guide in the v{{< readfile file="static/content/versiongeossn-1minor.md" markdown="true">}}.x documentation set to upgrade from {{< readfile file="static/content/versiongeossn-2minor.md" markdown="true">}} to {{< readfile file="static/content/versiongeossn-1minor.md" markdown="true">}}, and then follow the upgrade guide in the v{{< readfile file="static/content/versiongeosslatestminor.md" markdown="true">}}.x documentation set to upgrade from {{< readfile file="static/content/versiongeossn-1minor.md" markdown="true">}} to {{< readfile file="static/content/versiongeosslatestminor.md" markdown="true">}}. Check that your underlying infrastructure platform, such as Kubernetes, and other dependencies run a version that is supported for {{< readfile file="static/content/versiongeosslatest_minor.md" markdown="true">}}. Review the for dependencies such as Kubernetes, Helm, and more. Compare the supported versions against the versions 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. You might deploy Gloo Edge in Kubernetes environments that use the Kubernetes load balancer, or in non-Kubernetes environments. Depending on your setup, you can take additional steps to avoid downtime during the upgrade process. Kubernetes*: Enable during the upgrade. When these probes are set, Kubernetes sends requests only to the healthy Envoy proxy during the upgrade process, which helps to prevent potential downtime. The probes are not enabled in default installations because they can lead to timeouts or other poor getting started experiences. Non-Kubernetes*: Configure on Envoy. Then, configure your load balancer to leverage these health checks, so that requests stop going to Envoy when it begins draining connections. <!-- Review the following changes made to Gloo Edge in version {{< readfile file="static/content/versiongeosslatest_minor.md" markdown="true">}}. For some changes, you might be required to complete additional steps during the upgrade process. --> The Gloo Edge extProc filter implementation was changed to comply with the latest extProc implementation in Envoy. Previously, request and response attributes were included only in a , and were therefore sent to the extProc server only when request header processing messages were configured to be sent. Starting in Gloo Edge version

the Gloo extProc filter sends request and response attributes as part of the top level . That way, attributes can be processed on the first processing request regardless of its type. If you implemented your extProc server to expect request and response attributes as part of the HTTP header processing request, you must change this implementation to read attributes from the top-level processing request instead. For more information, see the in Envoy. The Envoy dependency in Gloo Edge 1.17 was upgraded from 1.27.x to 1.29.x. This upgrade includes the following changes. For more information about these changes, see the . ExtProc attribute processing*: For more information, see . JWT tokens*: The behavior for extracting JWT tokens changed. Previously, the JWT token was cut into non-base64 characters. Now, the entire JWT token is passed for validation. This change can be reverted temporarily by setting `envoy.reloadablefeatures.tokenpassed_entirely` to `false`. HTTP2 host header*: The HTTP2 host header is discarded if the `:authority` header is received. This change makes Envoy compliant with the HTTP2 request pseudo-header field implementation. For more information, see the . You can temporarily revert this change by setting the `envoy.reloadablefeatures.http2discardhostheader` runtime flag to `false`. Transfer encoding header*: The transfer encoding header is removed from downstream request headers. You can temporarily revert this change by setting `envoy.reloadablefeatures.sanitizete` to `false`. Check the changelogs for the type of Gloo Edge deployment that you have. Focus especially on any Breaking Changes that might require a different upgrade procedure. For Gloo Edge Enterprise, you might also review the open source changelogs because most of the proto definitions are open source. : Keep in mind that Gloo Edge Enterprise pulls in Gloo Edge Open Source as a dependency. Although the major and minor version numbers are the same for open source and enterprise, their patch versions often differ. For example, open source might use version `x.y.a` but enterprise uses version `x.y.b`. If you are unfamiliar with these versioning concepts, see . Because of the differing patch versions, you might notice different output when checking your version with `glooctl version`. For example, your API server might run Gloo Edge Enterprise version {{< readfile file="static/content/versiongeelatest.md" markdown="true">}}, which pulls in Gloo Edge Open Source version {{< readfile file="static/content/versiongeosslatest.md" markdown="true">}} as a dependency. ```bash ~ > glooctl version Client: {"version":"{{< readfile file="static/content/versiongeosslatest.md" markdown="true">}}"} Server: {"type":"Gateway","enterprise":true,"kubernetes":...,{"Tag":"{{< readfile file="static/content/versiongeelatest.md" markdown="true">}}","Name":"grpcserver-ee","Registry":"quay.io/solo-io"},...,{"Tag":"{{< readfile file="static/content/versiongeosslatest.md" markdown="true">}}","Name":"discovery","Registry":"quay.io/solo-io"},...} ``` {{% notice tip %}} You can use the changelogs' built-in to compare between your current version and the version that you want to upgrade to. {{% /notice %}} Review the following summary of important new, deprecated, or removed features. {{% notice note %}} The following lists consist of the changes that were initially introduced with the 1.16.0 release. These changes might be backported to earlier versions of Gloo Edge. Additionally, there might be other changes that are introduced in later 1.16 patch releases. For patch release changes, check the . {{% /notice %}} New or improved features: <!-- Deprecated features: N/A Removed features: N/A --> Review the following summary of important new, deprecated, or removed Helm fields. For full details, see the . New and updated Helm fields: <!-- Updated Helm fields: N/A Deprecated Helm fields: N/A Removed Helm fields: N/A --> New CRDs are automatically applied to your cluster when performing a `helm install` operation, but are not applied when performing an `helm upgrade` operation. This is a 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

Review the following summary of important new, deprecated, or removed CRD updates. For full details, see the . New and updated CRDs: <!-- Deprecated CRDs: N/A Removed CRDs: N/A --> You must upgrade `glooctl` before you upgrade Gloo Edge. Because `glooctl` can create resources in your cluster, such as with `glooctl add route`, you might have errors in Gloo Edge if you create resources with an older version of `glooctl`. As part of the 1.16 release, no CLI changes were introduced. <!-- Review the following summary of important new, deprecated, or removed CLI options. For full details, see the . New CLI commands or options: `glooctl create secret encryptionkey`: , such as to use in the `cipherConfig` field of the `ExtAuthConfig` resource. Changed behavior:--> Review the following frequently-asked questions about the upgrade process. If you still aren't sure about the version upgrade impact, or if your use case doesn't quite fit the standard upgrade path, feel free to post in the `#gloo` or `#gloo-enterprise` channels of our . If downtime is not a concern for your use case, you can follow the to update your Gloo Edge installation. Note that for sandbox or exploratory environments, the easiest way to upgrade is to uninstall Gloo Edge by running `glooctl uninstall --all`. Then, re-install Gloo Edge at the desired version by the following one of the . The basic `helm upgrade` process is not suitable for environments in which downtime is unacceptable. Instead, you can follow the guide to deploy multiple version of Gloo Edge to your cluster, and test the upgrade version before uninstalling the existing version. Additionally, you might need to take steps to account for other factors such as Gloo Edge version changes, probe configurations, and external infrastructure like the load balancer that Gloo Edge uses. Consider setting up in your environment. A typical upgrade of Gloo Edge across minor versions should not cause disruptions to the existing Gloo Edge state. In the case of a breaking change, Solo will communicate through the upgrade guides, changelogs, or other channels if you must make a specific adjustment to perform the upgrade. Note that you can always use the `glooctl debug yaml` command to download the current Gloo Edge state to one large YAML manifest. If you are not an administrator of your cluster, you might be unable to create custom resource definitions (CRDs) and other cluster-scoped resources, such as cluster roles and cluster role bindings. If you encounter an error related to these resources, you can disable their creation by including the following setting in your Helm values: ```yaml global: glooRbac: create: false ``` Otherwise, you can try performing an installation of Gloo Edge that is scoped to a single namespace by including the following setting in your Helm values: ```yaml global: glooRbac: namespaced: true ``` Helm v2 does not manage CRDs well, and is not supported in Gloo Edge. Upgrade to Helm v3, delete the CRDs, and try again. The upgrade creates a Kubernetes Job named `gateway-certgen` to generate a certificate for the validation webhook. The job contains the `ttlSecondsAfterFinished` value so that the cluster cleans up the job automatically, but because this setting is still in Alpha, your cluster might ignore this value. In this case, you might have an issue while upgrading in which the upgrade attempts to change the `gateway-certgen` job, but the change fails because the job is immutable. To fix this issue, you can delete the job, which already completed, and re-apply the upgrade.