date: Pending

# Changes that are expected to cause an incompatibility with previous versions, such as deletions or modifications to existing APIs.

breaking changes: |

The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. Existing configurations including the template syntax (%) will be interpolated.

The `0s` timeout in SecurityPolicy is now treated as infinite timeout instead of immediate timeout.

`SamplingFraction` behavior changed from raw fraction to percentage ratio. This will lead to 100x more sampling than before. E.g. `numerator: 100` used to result in 1% sampling rate, now will result in 100% sampling.

The controller now uses production logging encoder config by default, which provides better output when using JSON encoder.

SecurityPolicy OIDC now generates a single native `envoy.filters.http.oauth2` HTTP filter in the HCM filter chain and moves route-specific OAuth2 configuration to route `typed_per_filter_config`. This can break existing EnvoyPatchPolicies and extension managers that depend on the previous per-route OAuth2 filter instances or on the old OAuth2 filter configuration shape in the HCM filter chain.

# Updates addressing vulnerabilities, security flaws, or compliance requirements.

security updates: |

# New features or capabilities added in this release.

new features: |

Added support for configuring optional health check configuration.

Added support for shadow mode in local rate limiting.

Added support for MergeType in SecurityPolicy to enable route-level policies to merge with parent Gateway/Listener policies, similar to BackendTrafficPolicy.

Added `egctl config envoy-gateway` commands to retrieve Envoy Gateway admin config dumps.

The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. See https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators for more details.

Added HTTP/2 connection keepalive support to ClientTrafficPolicy and BackendTrafficPolicy.

Implement RoutingType field for BackendTrafficPolicy

Support for configuring weights for locality zones.

Added support for settings of gRPC web in ClientTrafficPolicy.

Added support for Envoy Dynamic Modules.

Added support for weight in BackendRef API to enable traffic splitting for non-x-route resources.

Added support for removing headers based on matching criteria (Exact, Prefix, Suffix, RegularExpression) in ClientTrafficPolicy EarlyRequestHeaders and LateResponseHeaders.

Added support for priorityClassName in KubernetesPodSpec for Envoy Proxy pods.

Added support for Global rate limit shadow mode.

Added support for specifying both text (body) and attributes in access log format by making the type field optional.

Set warning status condition for deprecated fields in xPolicy CRDs.

Added support for URLRewrite filter on individual backendRefs.

Added support for custom headers on OTLP exports (metrics, tracing, access logs).

Added support for custom TLS configuration when pulling WASM code via HTTP or OCI in EnvoyExtensionPolicy.

Added support for settings of gRPC stats in EnvoyProxy.

Added the PostEndpointsModify extension hook, allowing extensions to modify EDS ClusterLoadAssignments generated by Envoy Gateway before they are sent to Envoy.

Added support for stream idle timeout in BackendTrafficPolicy.

Added `namespaceOverride` support to gateway-helm chart

Added support for configuring statusOnError in ExtAuth settings

Added support for GeoIP-based authorization on HTTPRoute and GRPCRoute via `SecurityPolicy.spec.authorization.rules[*].principal.clientIPGeoLocations`, backed by shared GeoIP provider settings in `EnvoyProxy.spec.geoIP`.

Added support for retry budget in BackendTrafficPolicy.

Added support for BackendUtilization load balancing policy in BackendTrafficPolicy.

Added support for upstrean access log.

Added support for invert match in CIDR match RateLimit API.

Added support for ignoring HTTP/1.1 Upgrade requests in ClientTrafficPolicy via `http1.ignoredUpgradeTypes`.

Added support for OpenTelemetry sampler configuration for tracing.

Added support for default EnvoyProxy settings on EnvoyGatewaySpec that can be overridden by GatewayClass or Gateway-level EnvoyProxy configurations. A new MergeType field allows choosing between Replace (default), StrategicMerge, or JSONMerge strategies for combining configurations.

Added support for sending Envoy Gateway route metadata to external authorization backends via `SecurityPolicy.spec.extAuth.includeRouteMetadata`.

bug fixes: |

Fixed local rate limit rules with identical sourceCIDR client selectors producing conflicting descriptors.

Rejected ClientTrafficPolicy if invalid TLS cipher suites are configured.

Fixed ClientTrafficPolicy to disable HTTP/3 and surface a warning on the policy when downstream client TLS validation is configured, instead of generating a rejected QUIC listener.

Fixed validation of XListenerSet certificateRefs

Fixed XListenerSet not allowing xRoutes from the same namespace when configured to allow them

Fixed API key authentication dropping non-first client IDs when credential Secrets contain multiple keys.

Fixed `X-ENVOY-ORIGINAL-HOST` not being set when `headers.enableEnvoyHeaders` is enabled and hostname rewrite is configured for DynamicResolver type of Backends.

Fixed standalone mode emitting non-actionable error logs for missing secrets and unsupported ratelimit deletion on every startup.

Fixed local object reference resolution from parent policy in merged BackendTrafficPolicies.

Fixed xPolicy resources being processed from all namespaces when NamespaceSelector watch mode is configured in the Kubernetes provider.

Fixed route and policy status aggregation across multiple GatewayClasses managed by the same controller, so resources preserve status from all relevant parents and ancestors instead of being overwritten by the last processed GatewayClass.

Fixed route status parent aggregation when the number of parents exceeds the Gateway API cap of 32.

Made ConnectionLimit.Value optional so users can configure MaxConnectionDuration, MaxRequestsPerConnection, or MaxStreamDuration without setting a max connections value.

Fixed endpoint hostname is not respected when doing active health check.

Fixed ratelimit deployment missing metrics container port (19001), which prevented PodMonitor/ServiceMonitor from targeting the metrics endpoint.

Fixed GRPCRoute RequestMirror filter backend not being indexed, causing "service not found" errors for mirror targets that exist in the cluster.

Fixed GRPCRoute not detecting conflicting RequestMirror and DirectResponse filters, which caused the mirror to be silently dropped.

Fixed BackendTrafficPolicy `requestBuffer` coexisting with route upgrades by disabling the default WebSocket upgrade on buffered routes and rejecting explicit `requestBuffer` + `httpUpgrade` combinations.

Fixed per-endpoint hostname override not working because the auto-generated wildcard hostname.

Fixed Basic Authentication failing when htpasswd secrets use CRLF line endings by normalizing to LF before passing to Envoy.

BackendTLSPolicy was ignored when configuring TLS for telemetry backends (access logs, tracing, metrics).

Fixed client certificate secret never delivered when it is exclusively referenced by a SecurityPolicy `extAuth`/`jwt`/`oidc` Backend

Fixed xRoute status condition when route has mirror filter and the mirror backend has no endpoints.

Fixed gateway-helm RBAC in GatewayNamespace mode with explicit `watch.namespaces` list by adding controller-namespace secret read permissions to infra-manager.

# Enhancements that improve performance.

performance improvements: |

Reduce chances of listener drain due to Lua policy updates by migrating to LuaPerRoute.

# Deprecated features or APIs.

deprecations: |

# Other notable changes not covered by the above sections.

Other changes: |

Moved Envoy Gateway CRDs into a sub-chart to avoid the Helm release secret exceeding the 1MB size limit when adding new API fields. Upgrade/Install behavior is unchanged for users.

The maximum number of rules in a RateLimit policy is increased from 128 to 256.

The maximum number of JWT providers allowed in `SecurityPolicy.spec.jwt.providers` is increased from 4 to 16.