1.37.0 (Pending)

Incompatible behavior changes

Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required

  • dynamic modules: Updated the dynamic module ABI to support streaming body manipulation and fixed incorrect behavior when accessing or modifying request or response bodies. See https://github.com/envoyproxy/envoy/issues/40918 for details.

  • http: Added runtime flag envoy.reloadable_features.reject_early_connect_data to reject CONNECT requests that send data before Envoy returns a 200 response. This non-compliant behavior is common for latency reduction, so the option is disabled by default.

  • http: Changed the default reset code from NO_ERROR to INTERNAL_ERROR. This change can be reverted by setting the runtime guard envoy.reloadable_features.reset_with_error to false.

  • server: Added container-aware CPU detection on Linux that respects cgroup CPU limits alongside hardware thread count and CPU affinity when --concurrency is not set. Envoy now uses the minimum of hardware threads, CPU affinity, and cgroup CPU limits to size worker threads by default, improving resource utilization in cgroup-limited containers. This behavior can be disabled by setting ENVOY_CGROUP_CPU_DETECTION to false to restore the previous hardware thread and affinity-based sizing. Uses conservative floor rounding to leave capacity for non-worker threads, which may reduce the total number of connections.

Minor behavior changes

Changes that may cause incompatibilities for some users, but should not for most

  • access_log: Fixed rejection of the truncation-length specifier for DYNAMIC_METADATA():Z in access log format strings. The length parameter now truncates strings and other value types; structured data types are not truncated.

  • ext_authz: Check response header count and size after applying mutations and send a local reply if limits are exceeded.

  • ext_authz: Fixed HTTP ext_authz service to propagate headers (such as set-cookie) back to clients. The filter now uses allowed_client_headers for denied responses and allowed_client_headers_on_success for successful responses.

  • ext_authz: Fixed the HTTP ext_authz client to respect user-configured retry_on in retry_policy. Previously, the value was overridden with 5xx,gateway-error,connect-failure,reset. Controlled by runtime flag envoy.reloadable_features.ext_authz_http_client_retries_respect_user_retry_on (defaults to true); set to false to preserve the old behavior.

  • ext_proc: Close the gRPC stream when Envoy detects no further external processing is needed. This currently excludes BUFFERED and BUFFERED_PARTIAL modes and a few corner cases, which close the stream during filter destruction. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.ext_proc_stream_close_optimization to false.

  • ext_proc: Use a hard-coded set of error messages when a HeaderMutation fails. Removing request-specific details allows grouping by failure type. Detailed messages remain available in debug logs.

  • ext_proc: added immediate_responses_sent counter for ext proc in :ref:’FilterStats <envoy_v3_api_msg_extensions.filters.http.ext_proc.v3.ExternalProcessor.ExtProcFilterStats>’.

  • http: Now the route level body buffer limit will be applied to requests when the route is matched. Previously, it will only be applied when the router filter is reached.

  • http: Now the retrying of async HTTP client calls will respect the set buffer limits and the retry will be ignored if the buffer limit is exceeded. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.http_async_client_retry_respect_buffer_limits to false.

  • mobile: Use mobile-specific network observer registries to propagate network change signals. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.mobile_use_network_observer_registry to false.

  • overload_manager: Fixed downstream connections monitor to trigger configured actions and emit a pressure metric like other resource monitors. Previously, actions never triggered.

  • quic: Switched to QUICHE-provided migration logic to handle port migration on path degradation and migration to the server preferred address. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.use_migration_in_quiche to false.

  • router: Added host_rewrite and path_rewrite to RouteAction to support substitution formatting for host and path header rewriting.

  • tracing: The request header custom tag now only supports fetching values from HTTP request headers. Non-HTTP protocols must use the substitution formatter-based custom tag value. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.get_header_tag_from_header_map to false.

  • wasm: Execute foreign functions on the effective context, when set by Wasm SDKs. Previously, foreign functions called from HTTP or gRPC callbacks could receive a root context instead of a stream context. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.wasm_use_effective_ctx_for_foreign_functions to false.

Bug fixes

Changes expected to improve the state of the world and are unlikely to have negative effects

  • adaptive concurrency: Fixed a race condition in the gradient controller that allowed more outstanding requests than the concurrency limit, bounded by the number of worker threads.

  • aws: Changed web identity token file watching in AWS signing components to pick up rotated tokens.

  • bootstrap: Fixed a startup crash when custom header_prefix was set.

  • composite: Fixed per-route configuration for the composite filter to match on response headers and trailers. Previously, matchers using HttpResponseHeaderMatchInput or HttpResponseTrailerMatchInput silently failed, skipping the delegated filter.

  • connection: Fixed connection handling to propagate transport failure reasons to StreamInfo before close events, ensuring connection.transport_failure_reason and DOWNSTREAM_TRANSPORT_FAILURE_REASON are populated for all connection types.

  • connection pool: Fixed a crash in the TCP connection pool during downstream teardown when large requests or responses triggered flow control.

  • dns_resolver: Removed unnecessary getifaddrs() system calls when filter_unroutable_families is disabled.

  • dynamic modules: Fixed a soundness bug in the Rust SDK by tightening bounds on the HttpFilterConfig trait.

  • ext_proc: Fixed missing attributes based on request headers (for example, request.host) when ext_proc was configured to run only on the encode path.

  • http: Fixed shouldDrainConnectionUponCompletion() to send GOAWAY frames for HTTP/2 and HTTP/3 instead of aggressively closing connections, preventing interrupted response bodies and ERR_DRAINING client errors. HTTP/1.1 behavior is unchanged.

  • http: Fixed a remote jwt_auth token fetch crash when two or more auth headers were present and allow_missing_or_failed was set.

  • http2: Fixed a memory leak when an HTTP/2 stream was reset before request headers were sent (for example, if an upstream HTTP filter sent a local reply after the connection was established but before headers were sent).

  • http2: Optimized HTTP/2 header processing by avoiding allocations and string copies for well-known header names. Common headers (:method, :path, :status, content-type, user-agent, etc.) now reference static strings, reducing allocations and improving performance.

  • http_11_proxy: Fixed http_11_proxy transport socket buffering of bytes written after the initial HTTP CONNECT request was sent but before the response was received, which could buffer until connection timeout.

  • lua: Fixed a crash when Lua filters set the response body to a payload larger than the body buffer limit.

  • router: Fixed a bug where the vhost per request buffer limit bytes will take precedence over the route per request buffer limit bytes.

  • router: Fixed a regression where router-set headers (for example, x-envoy-expected-rq-timeout-ms, x-envoy-attempt-count) were not accessible in request_headers_to_add on the initial request. These headers can now be referenced via formatters such as %REQ(x-envoy-expected-rq-timeout-ms)%.

  • router: Fixed an upstream HTTP filter issue when a route retried on 5xx and the filter returned FilterHeadersStatus::StopIteration in encodeHeaders().

  • tap: Added missing conversion support to ensure tapped messages are handled correctly for multi-event submissions.

  • tcp_proxy: Fixed a connection leak in TCP proxy when receive_before_connect is enabled and the downstream connection closes before the upstream connection is established.

  • tls: Fixed truncation of OTHERNAME SANs with embedded null octets in TLS certificates, which caused incorrect SAN validation.

  • udp_proxy: Fixed cases where addresses could be moved from the data packet being processed.

Removed config or runtime

Normally occurs at the end of the deprecation period

  • http: Removed runtime guard envoy.reloadable_features.http1_balsa_allow_cr_or_lf_at_request_start and legacy code paths.

  • http: Removed runtime guard envoy.reloadable_features.http1_balsa_delay_reset and legacy code paths.

  • http: Removed runtime guard envoy.reloadable_features.http1_balsa_disallow_lone_cr_in_chunk_extension and legacy code paths.

  • http: Removed runtime guard envoy.reloadable_features.http2_propagate_reset_events and legacy code paths.

  • http: Removed runtime guard envoy.reloadable_features.original_src_fix_port_exhaustion and legacy code paths.

  • jwt_authn: Removed runtime guard envoy.reloadable_features.jwt_fetcher_use_scheme_from_uri and legacy code paths.

  • quic: Removed runtime guard envoy.reloadable_features.http3_remove_empty_cookie and legacy code paths.

  • router: Removed runtime guard envoy.reloadable_features.router_filter_resetall_on_local_reply and legacy code paths.

  • tcp: Removed runtime guard envoy.reloadable_features.tcp_proxy_retry_on_different_event_loop and legacy code paths.

  • xds: Removed runtime guard envoy.reloadable_features.report_load_with_rq_issued and legacy code paths.

  • xds: Removed runtime guard envoy.restart_features.skip_backing_cluster_check_for_sds and legacy code paths.

New features

  • access_log: Added a new access logger that emits configurable metrics.

  • access_log: Added process-level rate limiting on access log emission via ProcessRateLimitFilter.

  • admin: Added allow_paths to admin interface to restrict access to specific admin endpoints. When configured, only paths matching the specified string matchers will be accessible. All other paths will return 403 Forbidden.

  • admin: Added /memory/tcmalloc admin endpoint providing TCMalloc memory statistics.

  • attributes: Added attributes for looking up request or response header bytes.

  • aws: Added match_included_headers to the request signing extension to allow positive header matching while excluding other non-SigV4-required headers.

  • c-ares: Added optional reinit_channel_on_timeout to the c-ares resolver to reinitialize the channel after DNS timeouts.

  • cel: Added per-expression configuration options for the CEL evaluator to control string conversion, concatenation, and string extension functions. CEL expressions in RBAC policies and access log filters can enable functions such as replace() and split() through new cel_config and cel_config fields. See CelExpressionConfig for details.

  • dns_filter: Added access_log for the DNS filter.

  • dynamic modules: Added support for loading dynamic modules globally by setting load_globally to true.

  • dynamic modules: Added support for streamable HTTP callouts in dynamic modules. Modules can create streaming HTTP connections to upstream clusters using start_http_stream, send request data and trailers incrementally, and receive streaming response headers, data, and trailers through dedicated callbacks.

  • dynamic modules: Enhanced dynamic module ABIs to support header addition and body size retrieval. See the latest ABI header for details.

  • ext_authz: Added configuration field enforce_response_header_limits to the HTTP ext_authz filter to enable or disable dropping response headers once header count or size limits are reached.

  • ext_authz: Added support for error_response in the external authorization API. Authorization services can return custom HTTP status codes, headers, and response bodies on internal errors, reusing DeniedHttpResponse.

  • ext_authz: Added support for metadata_context_namespaces and typed_metadata_context_namespaces in the ext-authz network filter. This allows passing connection metadata (such as proxy protocol TLV data) to the external authorization server for making authorization decisions.

  • ext_proc: Added per HTTP event :ref:’procesing effects <envoy.filters.http.ext_proc.ProcessingEffect’ in the ExtProcLoggingInfo in the FilterState. This new data will be automatically collected and can be accesses via method processingEffects.

  • ext_proc: Added support for forwarding cluster metadata to ext_proc server.

  • ext_proc: The MappedAttributeBuilder ext_proc extension now supports re-mapping response attributes (in addition to request attributes).

  • formatter: Added US_RX_BODY_BEG time point to %COMMON_DURATION% to indicate when upstream response body reception begins.

  • formatter: Added support for the following new access log formatters:

    1. %REQUEST_HEADER(X?Y):Z% as full name version of %REQ(X?Y):Z%.

    2. %RESPONSE_HEADER(X?Y):Z% as full name version of %RESP(X?Y):Z%.

    3. %RESPONSE_TRAILER(X?Y):Z% as full name version of %TRAILER(X?Y):Z%.

    This provides a more consistent naming scheme for users to understand and use.

  • generic_proxy: Added custom substitution format specifier support in tracing custom tags for the generic_proxy filter. The %REQUEST_PROPERTY% and %RESPONSE_PROPERTY% specifiers can now be used in value for generic proxy.

  • geoip: Added custom_header_config to allow extracting the client IP address from a custom request header which can be used instead of x-forwarded-for header or downstream connection source address.

  • geoip: Added support for MaxMind Country database via country_db_path.

  • http: Added vhost_header to RouteConfiguration to allow using a different header for vhost matching.

  • http filter: Added transform http filter to modify request and response bodies in any position of the HTTP filter chain. This also makes it possible to refresh routes based on attributes in the request body.

  • http2: Added a parameter to sendGoAwayAndClose to support graceful closure of HTTP/2 connections.

  • json_to_metadata: Added support for per-route configuration override in the json_to_metadata http filter. Routes can now specify different JSON to metadata conversion rules via per-route configuration, allowing different routes to extract different metadata from request or response bodies.

  • listener: Marked filter_chain_matcher as stable by removing the work-in-progress annotation. The xDS matcher API for filter chain selection has been thoroughly tested and is ready for production use.

  • listener_filters: Added Postgres Inspector listener filter for detecting PostgreSQL connections, extracting metadata, and supporting SNI-based routing for PostgreSQL traffic.

  • logging: Added support for the not-equal operator in access log filter rules via ComparisonFilter.

  • lua: Added drainConnectionUponCompletion() to the Lua filter stream info API, allowing Lua scripts to mark connections for draining (adds Connection: close for HTTP/1.1 or sends GOAWAY for HTTP/2 and HTTP/3).

  • lua: Added an executions counter to the Lua filter to track script execution count.

  • matcher: Removed work-in-progress annotations from RBAC filter matcher and shadow_matcher fields in HTTP and network filters, marking the feature stable.

  • mcp: Added MCP filter for parsing Model Context Protocol (MCP) JSON-RPC requests. The filter extracts the method and id fields from incoming requests and stores them in dynamic metadata for use by downstream filters and access logging. Notifications (methods starting with notifications/) are correctly handled as they don’t have an id field per the JSON-RPC specification.

  • mcp: Added mcp_router HTTP filter which routes MCP (Model Context Protocol) requests to more backend servers. The filter supports fanout to multiple backends for initialize and tools-list requests, single-backend routing for tools-call based on tool name prefix, session management with composite session IDs, and response aggregation.

  • metrics_service: Added batch_size to the Metrics Service to batch metrics into multiple gRPC messages. When positive, metrics are batched with at most batch_size metric families per message to avoid gRPC size limits. If unset or 0, all metrics are sent in one message.

  • network: Added logging info for network ext_proc to filter state.

  • network: Started populating filter state envoy.network.network_namespace when a connection is accepted on a listener with network_namespace_filepath configured, providing read-only access to the network namespace for filters, access logs, and other components.

  • network_filter: Added geoip network filter to perform geolocation lookups at the network layer and store results in filter state. This enables geolocation data to be used for access logging, routing, and other purposes without requiring HTTP traffic.

  • oauth2: Added support for configuring cookie path in the OAuth2 filter. The path field can now be set for each cookie type to control the scope of OAuth2 cookies.

  • on_demand: Added runtime guard envoy.reloadable_features.on_demand_track_end_stream. When enabled, the on_demand filter tracks downstream end_stream state to support stream recreation with fully read request bodies. Previously, the filter rejected all requests with bodies by checking only for a decoding buffer.

  • otlp_stat_sink: Added support for dropping stats via DropAction during custom metric conversion.

  • otlp_stat_sink: Fixed start_time_unix_nano for exported metrics.

  • overload management: The fixed heap resource monitor can calculate memory pressure as currently allocated memory divided by maximum heap size, providing more accurate and lower pressure values. This can avoid unnecessary load shedding. Enable via envoy.reloadable_features.fixed_heap_use_allocated. The default algorithm (heap_size - pageheap_unmapped - pageheap_free) does not discount free memory in TCMalloc caches.

  • proxy_protocol: Added tlv_location configuration field to control where proxy protocol TLV values are stored. When set to FILTER_STATE, TLV values are stored in a single filter state object with key envoy.network.proxy_protocol.tlv, enabling HTTP filters to access TLV values via FilterStateInput without requiring custom HTTP filters to copy metadata. Individual TLV values can be accessed via field access: %FILTER_STATE(envoy.network.proxy_protocol.tlv:FIELD:key)%. Defaults to DYNAMIC_METADATA to maintain existing behavior.

  • quic: Added QUIC protocol option max_sessions_per_event_loop to limit the maximum number of new QUIC sessions created per event loop. The default is 16, preserving the previous hardcoded limit.

  • redis: Added support for redis_proxy to use separate credentials for each upstream Redis cluster.

  • redis: Optimized the INFO command to provide limited metrics with a consolidated cluster view and added INFO.SHARD to retrieve shard-specific metrics.

  • router: Added hash_policy to HttpProtocolOptions for cluster-level hash policies.

  • router: Added request_mirror_policies to HttpProtocolOptions for cluster-level request mirroring. Cluster-level policies override route-level policies when both are configured.

  • router: Added retry_policy to HttpProtocolOptions for cluster-level retry policies.

  • router: Added substitution formatting for direct response bodies via body_format in DirectResponseAction.

  • tcp_proxy: Added upstream_connect_mode and max_early_data_bytes to control when upstream connections are established and early data buffering behavior. This enables use cases like extracting TLS certificate information or SNI before establishing upstream connections.

  • tls: Enhanced TLS certificate validation failure messages in access logs to include detailed error information. The %DOWNSTREAM_TRANSPORT_FAILURE_REASON% and %UPSTREAM_TRANSPORT_FAILURE_REASON% access log formatters now include specific validation failure reasons such as verify cert failed: SAN matcher, verify cert failed: cert hash and spki, or the OpenSSL verification error string (e.g., certificate has expired, unable to get local issuer certificate). This provides better visibility into TLS handshake failures without requiring debug-level logging.

  • tls_inspector: Added configuration parameter to TLS inspector for maximum acceptable client hello size.

  • tls_inspector: Propagated transport errors from tls_inspector to DownstreamTransportFailureReason in StreamInfo for access logging prior to the TLS handshake.

  • tracing: Added new tracing operation and upstream tracing operation fields in the tracing configuration to set custom operation names for spans with the substitution format specifier.

  • tracing: Added new value field and support for substitution format specifier to extract values from request and response data for custom tags.

  • tracing: Dynatrace sampler parses and propagates trace capture reason in tracestate.

  • udp_sink: Enhanced the UDP sink to support tapped messages larger than 64KB.

  • upstream: Added transport_socket_matcher to clusters. This matcher uses the generic xDS matcher framework to select a named transport socket from transport_socket_matches based on endpoint metadata, locality metadata, and transport socket filter state.

  • upstream: Added an extension to override the upstream bind address Linux network namespace using a shared filter state object.

  • wasm: Added sign foreign function to create cryptographic signatures. See Wasm foreign functions for details.

  • xds: Added runtime guard envoy.reloadable_features.report_load_when_rq_active_is_non_zero. When enabled, LRS continues to send locality_stats reports to the config server even when no requests were issued in the poll cycle.