For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Review summaries of the main changes in the Gloo Gateway 1.22 release.

Introduction

The release notes include important installation changes and known issues. They also highlight ways that you can take advantage of new features or enhancements to improve your product usage.

For more information, see the following related resources:

• Upgrade guide: Steps to upgrade from the previous minor version to the current version.
• Version reference: Information about Solo’s version support.
• Open source changelog or enterprise changelog

🔥 Breaking changes

Review details about the following breaking changes. To review when breaking changes were released, you can use the comparison feature of the open source changelog or enterprise changelog. The severity is intended as a guide to help you assess how much attention to pay to this area during the upgrade, but can vary depending on your environment.

🚨 High

Review severe changes that can impact production and require manual intervention.

• No high-severity changes are currently reported.

🔔 Medium

Review changes that might have impact to production and require manual intervention, but possibly not until the next version is released.

XSLT transformation removed

The XSLT transformation feature that was previously deprecated is now removed. If you use XSLT transformations, plan to use an external processing server to process this type of transformation. For more information, see External processing.

Caching filter removed

The Envoy-based caching filter, which was deprecated in Gloo Gateway 1.20, is removed in 1.22.

Envoy version upgrade

The Envoy dependency in Gloo Gateway 1.22 was upgraded from 1.36.x to 1.38.x. The following breaking changes are included in these releases. For detailed information, see the Envoy changelog for 1.37 and 1.38.

Envoy v1.37:

• Container-aware CPU detection: Envoy now sizes worker threads by using the minimum of hardware threads, CPU affinity, and cgroup CPU limits. In cgroup-limited containers, this means fewer worker threads than before, which reduces the maximum number of connections. Previously, Envoy ignored cgroup CPU limits and sized threads based only on hardware threads and CPU affinity. This change applies only when the Envoy --concurrency startup flag is not explicitly set. To restore the previous behavior without setting --concurrency, set the ENVOY_CGROUP_CPU_DETECTION environment variable to false.

Envoy v1.38:

• RSA key usage enforcement: Envoy 1.38 sets enforce_rsa_key_usage to true by default for upstream TLS connections. If the keyUsage extension is present in the upstream certificate and is incompatible with the TLS usage, the TLS handshake fails. In a future version of Envoy, this option will be removed and enforcing behavior will always apply. This setting is specific to upstream TLS connections (not downstream client connections). The keyUsage extension tells consumers what the certificate’s public key is allowed to be used for. If the extension is present but does not match the TLS role, the upstream handshake fails. Note that kgateway does not expose this setting in BackendConfigPolicy, so it cannot be set back to false. Common RSA key usage values compatible with TLS are:

  • digitalSignature
  • keyEncipherment
  • keyCertSign (CA certs only)
  • cRLSign (CA certs that sign revocation lists only)

  Verify your upstream certificates include compatible keyUsage values before upgrading.

• Circuit breaker metrics: Added a new upstream_rq_active_overflow counter that is incremented when a request is rejected because the max_requests circuit breaker is exhausted. Previously, this condition incorrectly incremented the upstream_rq_pending_overflow metric, making it impossible to distinguish between pending queue saturation and active request saturation. After the upgrade, only the upstream_rq_active_overflow is incremented for this case, so you might see a drop in upstream_rq_pending_overflow counts. If you have existing dashboards or alerts that rely on the upstream_rq_pending_overflow metric to detect max_requests circuit breaker trips, set the Envoy runtime flag envoy.reloadable_features.skip_pending_overflow_count_on_active_rq to false to increment both counters while you migrate your monitoring to the upstream_rq_active_overflow metric.

• Memory management: Replaced the custom timer-based tcmalloc memory release with tcmalloc’s native ProcessBackgroundActions and SetBackgroundReleaseRate APIs. This provides more comprehensive background memory management, including per-CPU cache reclamation, cache shuffling, and size class resizing, in addition to memory release. The tcmalloc.released_by_timer stat is removed.

• RBAC header matching: Fixed the RBAC header matcher to validate each header value individually instead of concatenating multiple header values into a single string. This prevents potential policy bypasses when requests contain multiple values for the same header. The new behavior is enabled by default and controlled by the runtime guard envoy.reloadable_features.rbac_match_headers_individually.

Upstream admission validation enforced

Previously, an Upstream resource with a corrupt or invalid protoDescriptorBin in grpcJsonTranscoder was accepted by the admission webhook. Envoy later rejected the entire RouteConfiguration and entered a continuous retry loop that caused silent routing failures. Setting fullEnvoyValidation: true had no effect in this mode.

Upstream admission validation is now enforced. Invalid protoDescriptorBin values are now rejected at admission time.

Action required: Before upgrading, verify that any Upstream resources that set the grpcJsonTranscoder field have a valid protoDescriptorBin. Upstreams with corrupt descriptors are rejected on update or re-apply after the upgrade.

ℹ️ Low

Review informational updates that you might want to implement but that are unlikely to materially impact production.

• No low-severity changes are currently reported.

⚒️ Installation changes

In addition to comparing differences across versions in the changelog, review the following installation changes from the previous minor version to version 1.22.

Default Redis image upgraded to v8

The default Redis image that is bundled with Gloo Gateway was upgraded from 7.2.11-alpine to 8.6.4-alpine to address high and critical CVEs present in Redis 7.x. Review the Redis 8 release notes for any breaking changes that are relevant to your usage. If you need to stay on a different version, you can override the image tag by setting gloo.redis.deployment.image.tag in your Helm values.

gloo:
  redis:
    deployment:
      image:
        tag: <version>

🌟 New features

Review the following new features that are introduced in version 1.22 and that you can enable in your environment.

Forward headers to client on ext-auth success

The PassThroughHttp.Response configuration in the AuthConfig resource now supports an allowedClientHeadersOnSuccess field. When set, headers that are returned by the HTTP passthrough auth server are forwarded to the downstream client on a successful auth check. Headers that are already present on the client response are overwritten. Previously, you could only forward headers to the client on denial (allowedClientHeadersOnDenied) or to the upstream on success (allowedUpstreamHeaders). For more information, see the HTTP passthrough auth guide.

Configure connection pool settings for HTTP passthrough auth

The PassThroughHttp configuration in the AuthConfig resource now supports a connectionPool block and a responseHeaderTimeout field to tune the HTTP client that the ext-auth service uses when calling the passthrough auth server. Use connectionPool.maxConns to cap the number of concurrent connections per host, connectionPool.idleTimeout to control how long idle connections are kept open, and responseHeaderTimeout to set the maximum time to wait for the auth server to return response headers before the request is considered timed out. For more information, see the HTTP passthrough auth guide.

IPv4-only listener bind addresses

By default, Gloo Gateway binds listeners to the IPv6 wildcard address ::, which listens for traffic on all interfaces. In IPv4-only Kubernetes environments, this causes gateways to fail to bind and proxies to receive an invalid xDS fallback configuration. You can now set settings.ipV4Only: true in your Helm values to switch the bind address to 0.0.0.0 instead. For more information, see IPv4-only environments.

Set the gateway proxy workload type

You can now configure the type of workload that you want to use for your gateway proxies by using the gloo.gatewayProxies.<NAME>.kind.workloadType Helm value. Set this field to "Deployment" or "DaemonSet" to control whether the gateway proxy is deployed as a Deployment or a DaemonSet. For more information, see the Helm values reference.

Tune GOMEMLIMIT settings

You can now set goMemLimitPercent on Gloo Gateway deployments to compute GOMEMLIMIT as a percentage of resources.limits.memory at Helm render time. Previously, GOMEMLIMIT was set to 100% of the cgroup limit, leaving no headroom for the Go garbage collector and causing OOM kills during HPA prescale events. The recommended value is 80–90. Setting the field to 0 or leaving it unset preserves the existing behavior. For all available Helm values, see the Enterprise Helm values reference.

Control the Host header for shadow traffic

The RouteShadowing configuration in the RouteOption resource now supports two new fields for controlling the Host/:authority header of mirrored requests.

• disableShadowHostSuffixAppend: By default, Envoy appends -shadow to the Host/:authority header of mirrored requests. Set this field to true to send the original Host header unchanged. This is useful when the shadow destination has strict host-based routing rules that reject the modified header.
• hostRewriteLiteral: Replaces the Host/:authority header of mirrored requests with the specified value. Include a port if the shadow destination needs one, as the port from the original request is not carried over.

For more information, see the Traffic shadowing guide.