.. _version_history_1.38.0: 1.38.0 (Pending) ================= Incompatible behavior changes ----------------------------- *Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required* * **boringssl/fips**: The previous flag for specifying FIPS builds (i.e., ``--define=boringssl=fips``) will no longer work and has been replaced by ``--config=boringssl-fips``. This change will allow us to better support custom SSL libraries, and will allow FIPS-compliant Envoy to be built with the imminent switch to Bazel bzlmod. * **ext_proc**: The ``processing_effect_lib`` has been moved from the :ref:`extensions/filters/http/ext_proc ` namespace to the ``extensions/filters/common/processing_effect`` namespace. All path references within the Envoy codebase have been updated. * **on_demand**: The on-demand filter, when doing on-demand CDS, will no longer do internal redirects after CDS is successful. Filters appearing in the filter chain before the on-demand filter will no longer be invoked twice. This behavior can be temporarily reverted by setting the runtime guard ``envoy.reloadable_features.on_demand_cluster_no_recreate_stream`` to ``false``. * **tcp_proxy**: The TCP proxy filter now requires :ref:`max_early_data_bytes ` to be explicitly set when using :ref:`upstream_connect_mode ` modes other than ``IMMEDIATE`` (i.e., ``ON_DOWNSTREAM_DATA`` or ``ON_DOWNSTREAM_TLS_HANDSHAKE``). The field can be set to ``0`` to disable early data buffering while still using delayed connection modes. Configurations using these modes without ``max_early_data_bytes`` will now fail validation at startup. * **tls**: Set :ref:`enforce_rsa_key_usage ` to ``true`` by default. The handshake will fail if the keyUsage extension is present and incompatible with the TLS usage. In the next version of Envoy, this option will be removed and the enforcing behavior will always be used. Minor behavior changes ---------------------- *Changes that may cause incompatibilities for some users, but should not for most* * **compressor**: Strong ``ETag`` removal when compressing now uses the same weak ``W/`` check as :ref:`weaken_etag_on_compress `. Previously removal applied only when ``ETag`` length was greater than 2; two-character strong values are now removed as well (the only two-character weak form is ``W/``). * **dynamic_modules**: Now all the dynamic module extension factories (HTTP, network, listener, UDP listener, and so on) will serialize the ``google.protobuf.Struct`` configuration message to JSON string and pass it to the dynamic module side as the configuration. * **ext_authz**: Added tracking bits for processing effect for request headers and failed open occurrence in the ``ExtAuthzLoggingInfo``. This new data will be automatically collected and can be accessed via ``requestProcessingEffect()`` and ``failedOpen()``. * **ext_authz**: Changed the behavior of ``timeout: 0s`` in the HTTP ext_authz filter to mean "no timeout" (infinite) instead of immediate timeout. Previously, ``timeout: 0s`` would cause requests to fail immediately. This aligns with other Envoy timeout configurations where ``0`` means disabled or infinite. * **ext_proc**: Added ``received_immediate_response`` flag in the ``ExtProcLoggingInfo`` filter state. * **happy_eyeballs**: Happy Eyeballs handles interleaving of non-IP addresses. The restriction against ``additional_addresses`` containing non-IP addresses is removed. This behavior can be reverted by setting the runtime guard ``envoy.reloadable_features.happy_eyeballs_sort_non_ip_addresses`` to ``false``. * **histograms**: Updated libcircllhist to 0.3.2, which changes how bucket bounds are interpreted. This should not impact production monitoring if the number of samples in the histograms is high. Affected tests were adjusted to account for histogram changes. * **http**: The ``route()``, ``clusterInfo()`` and ``virtualHost()`` methods on the HTTP filter callbacks and stream info interfaces now are refactored to return ``OptRef`` instead of shared pointers. And additional methods ``routeSharedPtr()``, ``clusterInfoSharedPtr()`` and ``virtualHostSharedPtr()`` are added to return shared pointers. The shorter ``route()``, ``clusterInfo()`` and ``virtualHost()`` methods are preferred for most use cases where the returned reference is not used beyond the scope of the current function and the caller does not want to manage shared pointer ownership. The new shared pointer methods are intended for use cases where the caller needs to keep the ownerships to the route, cluster, or virtual host. * **mcp**: Changed the default metadata namespace for the MCP filter from ``mcp_proxy`` to ``envoy.filters.http.mcp``. This change can be reverted by setting the runtime guard ``envoy.reloadable_features.mcp_filter_use_new_metadata_namespace`` to ``false``. * **mcp**: Relaxed the MCP filter POST Content-Type check from an exact match on ``application/json`` to a prefix match, so that ``application/json; charset=utf-8`` and similar media-type parameters are accepted. * **memory**: 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 has been removed. * **proto_api_scrubber**: If :ref:`scrub_unknown_fields ` is set to ``true`` in the :ref:`ProtoApiScrubberConfig `, unknown fields will now be scrubbed. This is disabled by default. * **ratelimit**: Changed the behavior of ``timeout: 0s`` in the HTTP rate limit filter to mean "no timeout" (infinite) instead of immediate timeout. Previously, ``timeout: 0s`` would cause requests to fail immediately. This aligns with other Envoy timeout configurations where ``0`` means disabled or infinite. * **stat_sinks**: OpenTelemetry :ref:`SinkConfig ` stopped reporting empty delta counters and histograms. * **stat_sinks**: OpenTelemetry :ref:`SinkConfig ` stopped reporting empty delta counters and histograms. * **upstream**: EDS host metadata comparison during ``updateDynamicHostList`` now uses a cached metadata hash instead of ``MessageDifferencer::Equivalent``. The hash is computed once when metadata is set, making per-host comparison O(1). In rare cases where two semantically equivalent metadata messages have different serializations, this may cause a spurious metadata update (false positive) but will never miss an actual change. Bug fixes --------- *Changes expected to improve the state of the world and are unlikely to have negative effects* * **access_log**: Fixed a crash on listener removal with a process-level access log rate limiter :ref:`ProcessRateLimitFilter `. * **contrib**: Fixed a segfault from a timer thread-safety violation, a ring buffer overflow, and incorrect alpha calculation in the ``peak_ewma`` load balancer. * **drop_overload**: Fixed a bug where ``drop_overload`` failed to use cached EDS resources. * **dynamic_modules**: Fixed a bug where dynamic module extensions do not handle the ``google.protobuf.Struct`` configuration properly as the API definition requires. The dynamic module extension factories now serialize the ``Struct`` to JSON string and pass the string to the dynamic module side as the configuration. * **dynamic_modules**: Fixed a bug where dynamic module filter may result in a incomplete body being sent to upstream or downstream when some filters before or after the dynamic module filter in the chain buffered the body and the dynamic module filter did not. * **dynamic_modules**: Fixed the dynamic modules network filter to always set a local close reason when closing connections. This resolves an error when a dynamic modules network filter closes a connection that has an HTTP filter present. * **ext_authz**: Fixed a bug where headers from a denied authorization response (non-200) were not properly propagated to the client. * **ext_authz**: Fixed the HTTP ext_authz client to respect ``status_on_error`` configuration when the authorization server returns a 5xx error or when HTTP call failures occur. Previously, these error scenarios always returned 403 Forbidden regardless of the configured error status. * **ext_proc**: Fixed a bug that prevented two ext_proc filters from being configured in the same filter chain. This change can be reverted by setting the runtime guard ``envoy.reloadable_features.ext_proc_inject_data_with_state_update`` to ``false``. * **ext_proc**: Fixed message-valued CEL attribute serialization (for example ``xds.virtual_host_metadata``) to use protobuf text format instead of debug string output. This restores ext_proc compatibility with protobuf 30+ where debug-string output is intentionally not parseable (for example ``goo.gle/debugonly`` prefixes). This change can be reverted by setting runtime guard ``envoy.reloadable_features.cel_message_serialize_text_format`` to ``false``. * **formatter**: Added support for the ``UPSTREAM_LOCAL_CLOSE_REASON`` log formatter. * **formatter**: Fixed the log formatter in HTTP router upstream logs by correctly setting the downstream connection's ``ConnectionInfoProvider`` in the ``StreamInfo``. * **header_mutation**: Fixed an issue where query parameter values added via ``query_parameter_mutations`` were not URL-encoded, allowing query parameter injection attacks. Values from formatters like ``%REQ(header)%`` are now properly URL-encoded when added to the query string. This behavior is controlled by the runtime guard ``envoy.reloadable_features.header_mutation_url_encode_query_params``. * **health_check**: Fixed a race condition where active health checks could start before required upstream TLS SDS secrets were fetched, causing intermittent health check failures `#43116 `_. This fix can be disabled by setting runtime guard ``envoy.reloadable_features.health_check_after_cluster_warming`` to ``false``. * **hot_restart**: Fixed hot restart for listeners with a network namespace in the address. Previously, socket hand-off didn't work cleanly because the namespace was not included in the ``PassListenSocket`` request, causing the parent to always fall back to binding a new socket. * **http**: Fixed a bug where the internal redirect logic may hang up a request when the request buffer is overflowed. * **http**: Fixed a potential file descriptor leak where HTTP/1.1 connections with zombie streams (waiting for codec completion) would not be properly closed when in draining state. This could occur when a response was sent before the request was fully received, causing connections to remain open indefinitely. This change can be reverted by setting the runtime guard ``envoy.reloadable_features.http1_close_connection_on_zombie_stream_complete`` to ``false``. * **http**: Fixed an issue where filter chain execution could continue on HTTP streams that had been reset but not yet destroyed. This could cause use-after-free conditions when filter callbacks were invoked on filters that had already received ``onDestroy()``. The fix ensures that ``decodeHeaders()``, ``decodeData()``, ``decodeTrailers()``, and ``decodeMetadata()`` are blocked after a downstream reset. * **http**: Fixed crash if a downstream watermark is hit by network filter writes before the HTTP codec is created. * **http**: Fixed upstream client to not close connection when idle timeout fires before the connection is established. This change can be reverted by setting the runtime guard ``envoy.reloadable_features.codec_client_enable_idle_timer_only_when_connected`` to ``false``. * **http_11_proxy**: Fixed bug where providing an empty inner socket config would cause Envoy to crash. * **io_socket**: Fixed an issue where a userspace IO socket could fail to drain the write buffer of a connection when the peer had closed for reads, causing the connection to remain open indefinitely. * **json**: Fixed an off-by-one write in ``JsonEscaper::escapeString()`` that could corrupt the string null terminator when the input string ends with a control character. * **load_report**: Fixed a race condition during load-report shutdown with the ADS stream by introducing proper cleanup of the gRPC stream. * **mcp_router**: Fixed MCP router to support session-less backends that do not return ``mcp-session-id`` headers. Previously, this caused a spurious 500 error. * **network**: Fixed a crash in ``Utility::getAddressWithPort`` when called with a scoped IPv6 address (e.g., ``fe80::1%eth0``). * **oauth2**: Fixed OAuth2 refresh requests so host rewriting no longer overrides the original ``Host`` header value. * **odcds**: Fixed a bug where using OD-CDS in tcp_proxy over ADS would not work in some cases. This change could be reverted temporarily by setting the runtime guard ``envoy.reloadable_features.tcp_proxy_odcds_over_ads_fix`` to ``false``. * **odcds**: Fixed a crash (SIGABRT) when destroying OdCDS handles on worker threads. The handle no longer holds a direct reference to the subscription, preventing thread-safety issues during destruction. The subscription now persists in ClusterManagerImpl and is looked up by a config source key. * **overload_manager**: Fixed a resource leak in global connection limit tracking that caused permanent connection rejections when using load shedding (e.g., ``envoy.load_shed_points.tcp_listener_accept``). When connections were rejected due to load shedding after passing the global connection limit check, the allocated connection limit resource was not released, causing the connection counter to become incorrect and leading to ``failed_updates`` in the resource monitor. This resulted in permanent connection rejections even after load subsided. The fix ensures that connection limit resources are properly released when connections are rejected due to load shedding. Also added defensive resource cleanup for edge cases where address processing fails (e.g., ``localAddress()`` or ``peerAddress()`` errors). * **ratelimit**: Fixed a bug in the gRPC rate limit client where the client could get into a bad state if the callbacks were not properly released after a request completion, leading to potential use-after-free issues. The fix ensures that callbacks and request references are cleared after completion, and adds assertions to enforce correct usage patterns. * **rbac**: Fixed RBAC header matcher to validate each header value individually instead of concatenating multiple header values into a single string. This prevents potential bypasses when requests contain multiple values for the same header. The new behavior is enabled by the runtime guard ``envoy.reloadable_features.rbac_match_headers_individually``. * **release**: Published contrib binaries now include the ``-contrib`` suffix in their version string. * **router**: Fixed a crash in scoped RDS when on-demand update is triggered for a scope that uses inline ``route_configuration`` instead of ``route_configuration_name``. The null RDS provider dereference is now guarded and the on-demand callback returns false for inline-config scopes. * **scoped_rds**: Fixed a bug where SRDS subscriptions would never start when a listener with scoped routes was added after server initialization completed. The ``SrdsFactory`` interface was incorrectly using the server-level init manager instead of the listener-level init manager, causing the SRDS init target to be silently discarded. * **spiffe**: Reduced the number of file watches needed by :ref:`trust_bundles ` when the validator is used in multiple places. Added support for :ref:`watched_directory ` to support Kubernetes environments that rely on atomic symbolic file updates. Added content hashing during file watching to handle excessive watch notifications. * **tls**: Fixed on-demand TLS selector to enforce session resumption settings. * **upstream**: Fixed an out-of-bounds issue in ThreadAwareLoadBalancerBase that could occur during mid-batch EDS host updates due to eagerly calling refresh() before the deferred priority state resize. * **watch-dog**: Fixed a bug where the worker thread watchdogs were configured using the main thread's configuration. This change can be reverted by setting the runtime guard ``envoy.restart_features.worker_threads_watchdog_fix`` to ``false``. * **xds**: Fixed a bug where in delta-xDS when xDS-Failover is configured (gated by the experimental ``envoy.restart_features.xds_failover_support`` runtime guard), in some cases the :ref:`initial_resource_versions ` field was not updated correctly when attempting to reconnect to the xDS server. Removed config or runtime ------------------------- *Normally occurs at the end of the* :ref:`deprecation period ` * **tcp_proxy**: Removed runtime guard ``envoy.reloadable_features.tcp_proxy_set_idle_timer_immediately_on_new_connection`` and legacy code path. New features ------------ * **a2a**: Added parsing support for the A2A (Agent2Agent) protocol, enabling parsing of A2A JSON-RPC messages. * **access_log**: Added stats customization support for the :ref:`access logger `. * **access_log**: Added support for gauges in the :ref:`stats access logger `. * **admin**: Added ``filter`` query parameter support to the ``/clusters`` endpoint. The parameter accepts a RE2 regular expression to filter clusters by name. Compatible with the ``format`` parameter for both text and JSON output (e.g., ``/clusters?filter=service&format=json``). * **cel**: Added functionality to reevaluate CEL expressions that attempt to read response path data on the request path once the data is available. Allows CEL matching based on both request and response headers. This may cause a behavior change for matchers that previously would silently fail to match due to attempting to match response headers in the request path. This behavior can be reverted by setting the runtime guard ``envoy.reloadable_features.enable_cel_response_path_matching`` to ``false``. * **compressor**: Added :ref:`weaken_etag_on_compress ` to the :ref:`compressor filter `. When enabled in ``response_direction_config``, strong ``ETag`` response headers are weakened (``W/`` prefix) instead of removed when compression is applied, allowing caches and conditional requests to work while indicating the body was modified by compression. When both ``weaken_etag_on_compress`` and ``disable_on_etag_header`` are true, the new field takes precedence. * **config**: Added support for :ref:`set_node_on_first_message_only ` to Delta-xDS. Guarded by runtime flag ``envoy.reloadable_features.xds_legacy_delta_skip_subsequent_node``. * **connection**: Add support for closing connections when they stay above the buffer high watermark for a configured time. This can be enabled by setting the :ref:`per_connection_buffer_high_watermark_timeout ` field on the listener and :ref:`per_connection_buffer_high_watermark_timeout ` field on the cluster. By default, the timeout is disabled. * **content_parsers**: Added :ref:`envoy.content_parsers.json ` content parser for extracting values from JSON content using JSON path selectors. Can be used by filters that need to parse structured JSON data and extract specific fields into metadata. * **contrib**: Added a new :ref:`Kafka stats sink ` contrib extension (``envoy.stat_sinks.kafka``) that produces metrics directly to an Apache Kafka topic using librdkafka. Supports both JSON and Protobuf serialization formats; the Protobuf format uses the same ``StreamMetricsMessage`` wire format as the gRPC :ref:`metrics_service ` sink, allowing consumers to reuse existing deserializers. Configurable batching, delta counters, tag-as-label emission, and full librdkafka producer tuning (including TLS and SASL authentication) are supported via :ref:`KafkaStatsSinkConfig `. * **dns_resolver**: Added :ref:`HickoryDnsResolverConfig `, a new DNS resolver using the `Hickory DNS `_ library. * **dynamic modules**: Added connection state and flow control ABI callbacks for the dynamic module network filter, including ``read_disable``, ``read_enabled``, ``get_connection_state``, ``enable_half_close``, ``is_half_close_enabled``, ``get_buffer_limit``, ``set_buffer_limits``, and ``above_high_watermark``. * **dynamic modules**: Added drain and shutdown lifecycle hooks for bootstrap dynamic modules. * **dynamic modules**: Added socket property getter and SSL/TLS information ABI callbacks for the dynamic module listener filter, including ``get_requested_server_name``, ``get_detected_transport_protocol``, ``get_requested_application_protocols``, ``get_ja3_hash``, ``get_ja4_hash``, ``is_ssl``, ``get_ssl_uri_sans``, ``get_ssl_dns_sans``, and ``get_ssl_subject``. * **dynamic modules**: Added support for dynamic modules authors to register any combination of HTTP, network, listener, UDP listener, and bootstrap filters in the Rust SDK. * **dynamic modules**: Introduced the extended ABI forward compatibility mechanism for dynamic modules where modules built with an SDK version can be loaded by Envoy binaries of the next Envoy version. For example, a module built with the v1.38 SDK can now be loaded by an Envoy binary of v1.39. * **dynamic_modules**: Added :ref:`TLS certificate validator ` support for dynamic modules, enabling custom TLS certificate validation to be implemented in dynamic modules. * **dynamic_modules**: Added :ref:`cluster ` support for dynamic modules, enabling custom service discovery and host management to be implemented in dynamic modules. * **dynamic_modules**: Added :ref:`load balancing policies ` support for dynamic modules, enabling custom load balancing algorithms to be implemented in dynamic modules. * **dynamic_modules**: Added :ref:`tracer ` support for dynamic modules, enabling custom distributed tracing backends to be implemented in dynamic modules. * **dynamic_modules**: Added HTTP callout support for dynamic module listener filters, enabling listener filters to initiate asynchronous HTTP requests to upstream clusters and receive responses via the ``send_http_callout`` ABI callback and ``on_listener_filter_http_callout_done`` event hook. * **dynamic_modules**: Added ``get_host_health_by_address`` ABI callback for dynamic module load balancers, providing O(1) host health lookup by address string using the cross-priority host map. * **dynamic_modules**: Added ``nack_on_cache_miss`` option for remote dynamic module sources. When enabled, uncached remote modules cause configuration rejection (NACK) with a background fetch, instead of blocking listener warming. This enables remote modules in ECDS and per-route configurations where an init manager is not available. * **dynamic_modules**: Added ``on_host_membership_update`` event hook and ``get_member_update_host_address`` callback for dynamic module load balancers, enabling modules to receive notifications when hosts are added or removed from the cluster and inspect the affected host addresses. * **dynamic_modules**: Added ``write_to_socket`` and ``close_socket`` ABI callbacks for the dynamic module listener filter, enabling protocol negotiation use cases such as Postgres SSL and MySQL handshake at the listener filter level. * **dynamic_modules**: Added a process-wide function registry to the dynamic modules ABI. Modules can register functions by name via ``envoy_dynamic_module_callback_register_function`` and other modules can resolve them via ``envoy_dynamic_module_callback_get_function``, enabling zero-copy cross-module interactions analogous to ``dlsym``. * **dynamic_modules**: Added a process-wide shared data registry to the dynamic modules ABI. * **dynamic_modules**: Added admin handler API to the bootstrap extension dynamic modules ABI, enabling modules to register custom admin HTTP endpoints. * **dynamic_modules**: Added caching for remotely fetched dynamic modules. Since ``newDynamicModuleFromBytes`` writes modules to a deterministic path based on SHA256, subsequent config updates referencing the same SHA256 load from the existing file, avoiding redundant HTTP fetches. * **dynamic_modules**: Added configurable :ref:`metrics_namespace ` field to ``DynamicModuleConfig``. This allows users to customize the prefix used for all metrics created by dynamic modules. Metrics now appear with the standard ``envoy_`` prefix followed by the namespace in prometheus output (e.g. ``envoy_myapp_requests_total``). The legacy behavior (stripping the namespace prefix from prometheus output) can be restored by setting the runtime guard ``envoy.reloadable_features.dynamic_modules_strip_custom_stat_prefix`` to ``true``. * **dynamic_modules**: Added custom metrics (counters, gauges, histograms) support to load balancer dynamic modules. Modules can now define metrics during configuration and record them during host selection. * **dynamic_modules**: Added dynamic module input matcher extension that allows implementing custom matching logic in external languages (Rust, Go, C) via dynamic modules. * **dynamic_modules**: Added filter state read/write support for dynamic module cert validators, allowing modules to set and get string values in the connection's filter state during certificate chain verification. * **dynamic_modules**: Added init manager integration to the dynamic modules bootstrap extension ABI. An init target is automatically registered for every bootstrap extension, blocking traffic until the module signals readiness via ``signal_init_complete``. * **dynamic_modules**: Added listener lifecycle event callbacks to the bootstrap dynamic module extension. Modules can opt in via ``enable_listener_lifecycle`` to receive ``on_listener_add_or_update`` and ``on_listener_removal`` notifications when listeners change in the ``ListenerManager``. * **dynamic_modules**: Added metrics definition and update support for bootstrap dynamic modules. * **dynamic_modules**: Added server lifecycle callbacks (``on_server_initialized``, ``on_drain_started``, ``on_shutdown``) for dynamic module custom clusters, enabling modules to react to server readiness, drain, and shutdown events. * **dynamic_modules**: Added support for fetching dynamic module binaries from remote HTTP sources via ``module.remote`` in ``DynamicModuleConfig``. The module is downloaded asynchronously during listener initialization with SHA256 verification, written to a temporary file, and loaded via ``dlopen``. If the remote fetch fails, the filter is not installed and requests pass through (fail-open). * **dynamic_modules**: Added support for loading dynamic module binaries from local file paths via the new :ref:`module ` field in ``DynamicModuleConfig``. This allows specifying an absolute path to a ``.so`` file via ``module.local.filename`` as an alternative to the name-based search path. * **dynamic_modules**: Added timer API to the bootstrap extension dynamic modules ABI. * **dynamic_modules**: Added typed filter state support for dynamic module HTTP and network filters. This allows modules to set and get filter state objects using registered ``StreamInfo::FilterState::ObjectFactory`` instances, enabling interoperability with built-in Envoy filters that expect specific typed objects. * **dynamic_modules**: Added upstream HTTP TCP bridge extension for dynamic modules. This enables modules to transform HTTP requests into raw TCP data for upstream connections and convert TCP responses back into HTTP responses via explicit send callbacks. See :ref:`envoy.upstreams.http.dynamic_modules `. * **dynamic_modules**: Changed the ``details`` parameter in ``cluster_lb_async_host_selection_complete`` ABI callback from raw ``const char*`` and ``size_t`` to ``envoy_dynamic_module_type_module_buffer`` for consistency with the ABI style guide. * **dynamic_modules**: Network filter read and write buffers now persist after ``on_read``/``on_write`` callbacks, allowing modules to access buffered data from ``on_scheduled`` and other callbacks. Added ``envoy_dynamic_module_callback_network_filter_get_cluster_host_count`` to query cluster host counts by name, enabling scale-to-zero and custom load balancing decisions in network filters. * **dynamic_modules**: Rust SDK now provides an opt-in ``CatchUnwind`` wrapper for filter callbacks. When a wrapped callback panics, Envoy logs the panic and returns a fail-closed error (e.g. HTTP 500, stream reset, connection close) instead of aborting the process. * **ext_authz**: Added :ref:`path_override ` to the HTTP ext_authz filter. When set, the request path sent to the authorization service is replaced entirely by this value. Only one of ``path_prefix`` or ``path_override`` may be set; validation fails at config load if both are specified. * **ext_proc**: Added :ref:`allow_content_length_header ` to allow the ext_proc filter to preserve the original ``Content-Length`` header or let ext_proc server modify it as needed. * **filters**: Added filters to update the filter state in :ref:`a listener filter `. * **formatter**: Added ``%UPSTREAM_DETECTED_CLOSE_TYPE%`` and ``%DOWNSTREAM_DETECTED_CLOSE_TYPE%`` to expose the detected close type of downstream and upstream connections. The possible values are ``Normal``, ``LocalReset``, and ``RemoteReset``. * **formatter**: Added ``QUERY_PARAMS`` support for substitution formatter to log all query params. They can either be logged in their original form or decoded. * **formatter**: Added ``SPAN_ID`` :ref:`access log formatter ` to log the span ID of the active (downstream) span for a request, complementing the existing ``TRACE_ID`` formatter. * **formatter**: Added extensions for :ref:`%FILE_CONTENT(/path/to/file)% ` and :ref:`%SECRET(name)% `. * **formatter**: Added new access log formatters for tracking upstream hosts and connection IDs attempted during request processing: ``%UPSTREAM_HOSTS_ATTEMPTED%``, ``%UPSTREAM_HOSTS_ATTEMPTED_WITHOUT_PORT%``, ``%UPSTREAM_HOST_NAMES_ATTEMPTED%``, ``%UPSTREAM_HOST_NAMES_ATTEMPTED_WITHOUT_PORT%``, and ``%UPSTREAM_CONNECTION_IDS_ATTEMPTED%``. These are useful for debugging retry behavior and understanding which hosts were tried before a successful connection or final failure. * **formatter**: Added the new access log formatter ``DOWNSTREAM_LOCAL_CLOSE_REASON``. * **formatter**: Extended ``*_WITHOUT_PORT`` address formatters to accept an optional ``MASK_PREFIX_LEN`` parameter that masks IP addresses and returns them in CIDR notation (e.g., ``%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT(16)%`` returns ``10.1.0.0/16`` for client IP ``10.1.10.23``). * **geoip**: Added ``asn_org`` field to :ref:`geo_field_keys ` to populate a header with the autonomous system organization name from the MaxMind ASN database. * **golang**: Added ``DownstreamSslConnection()`` method to the Golang HTTP filter's ``StreamInfo`` interface, providing access to SSL/TLS connection information for the downstream connection. This includes peer certificate details (subject, issuer, serial number, SANs, validity), TLS version, cipher suite, and PEM-encoded certificates. This achieves feature parity with the Lua filter's ``downstreamSslConnection()`` functionality. * **http**: Added :ref:`envoy.filters.http.sse_to_metadata ` filter for extracting values from Server-Sent Events (SSE) streams and writing them to dynamic metadata. Useful for capturing token usage metrics from LLM API responses. Supports pluggable content parsers for different SSE data formats. * **http**: Added :ref:`file_server http filter ` to allow responding with file contents from the filesystem. * **http**: Added an optional :ref:`JSON format ` for the :ref:`x-forwarded-client-cert ` (XFCC) header. The format can be configured via :ref:`format `. * **http**: Fixed an issue where filter chain execution could continue on HTTP streams that had been reset but not yet destroyed. This could cause use-after-free conditions when filter callbacks were invoked on filters that had already received ``onDestroy()``. The fix ensures that ``decodeHeaders()``, ``decodeData()``, ``decodeTrailers()``, and ``decodeMetadata()`` are blocked after a downstream reset. * **http2**: Added :ref:`max_header_field_size_kb ` to configure the maximum wire-encoded size in KiB of an individual HPACK-encoded header field that the HTTP/2 codec will accept. This allows increasing the default nghttp2 per-header limit of 64 KiB on the wire when larger single headers need to be supported. * **http_11_proxy**: Added ability to configure a default proxy address that is used when the proxy address is not configured via metadata. * **http_filter**: Added support for clear route cache in the :ref:`set_filter_state http filter `. When ``clear_route_cache`` is set, the filter will clear the route cache for the current request after applying filter state updates. This is necessary if the route configuration may depend on the filter state values set. * **http_service**: Added the ability for :ref:`request_headers_to_add ` to use a formatter extension that can retrieve secrets, for including authentication tokens. This support is added for all uses of this message, including the open telemetry, ``ext_proc``, and ``zipkin`` tracers. * **listener_manager**: Added ``ListenerUpdateCallbacks`` interface to ``ListenerManager``, similar to the existing ``ClusterUpdateCallbacks`` on ``ClusterManager``. * **lua**: Added :ref:`set() ` to the Lua filter state API, allowing Lua scripts to create and store filter state objects dynamically using registered object factories. * **matching**: Added :ref:`local reply matcher input ` to distinguish Envoy generated local replies from upstream responses. This matcher input returns ``true`` for local replies and ``false`` for upstream responses, enabling ``custom_response`` filter policies to selectively apply only to locally generated error responses. * **matching**: Added an optional ``field`` parameter to :ref:`FilterStateInput `. When set, ``FilterStateInput`` calls ``getField()`` on the filter state object instead of ``serializeAsString()``, enabling direct matching on individual fields within composite filter state objects such as proxy protocol TLVs stored via ``tlv_location: FILTER_STATE``. * **mcp**: Added HTTP DELETE session termination support to the MCP filter. DELETE requests with an ``MCP-Session-Id`` header are now recognized as valid MCP traffic in ``REJECT_NO_MCP`` mode. * **mcp**: Added options ``propagate_trace_context`` and ``propagate_baggage`` for extracting ``traceparent``, ``tracestate``, and baggage from MCP parameters, respectively. * **mcp_json_rest_bridge**: Added support for MCP ``tools/call`` request transcoding. Support for ``tools/list`` and ``tools/call`` response transcoding is planned. This filter is currently a work-in-progress and not recommended for production use. * **mcp_json_rest_bridge**: Added support for MCP ``tools/call`` response transcoding. Support for ``tools/list`` is planned. This filter is currently a work-in-progress and not recommended for production use. * **mcp_json_rest_bridge**: Added support for MCP session negotiation, including ``initialize`` and ``notifications/initialized`` methods. This filter is currently a work-in-progress and not recommended for production use. * **mcp_json_rest_bridge**: Added the MCP JSON REST Bridge HTTP filter configuration to transcode MCP JSON-RPC requests into standard JSON-REST HTTP requests. * **mcp_router**: Added :ref:`statistics ` to the MCP router filter for observability into request routing, fanout operations, and error conditions. * **mcp_router**: Added SSE (Server-Sent Events) streaming support for MCP backend responses. The router now handles SSE responses from backends for ``tools/call`` with direct pass-through streaming, and supports SSE aggregation for fanout operations (``tools/list``, ``initialize``) with incremental event parsing. * **mcp_router**: Added SSE response support for MCP ``prompts/list`` fanout aggregation. * **mcp_router**: Added SSE response support for MCP ``resources/list`` fanout aggregation. * **mcp_router**: Added support for MCP ``resources/templates/list`` method with fanout aggregation. * **mcp_router**: Added support for MCP client-to-server notification methods ``notifications/cancelled`` and ``notifications/roots/list_changed``. * **mcp_router**: Added support for MCP completion method ``completion/complete`` with routing based on ``ref/prompt`` or ``ref/resource``. * **mcp_router**: Added support for MCP logging method ``logging/setLevel``. * **mcp_router**: Added support for MCP prompt methods ``prompts/list`` and ``prompts/get``. * **mcp_router**: Added support for MCP resource methods ``resources/list``, ``resources/read``, ``resources/subscribe``, and ``resources/unsubscribe``. * **memory**: Added ``soft_memory_limit_bytes``, ``max_per_cpu_cache_size_bytes``, and ``max_unfreed_memory_bytes`` fields to :ref:`MemoryAllocatorManager ` for fine-grained control of tcmalloc memory management. * **network**: Added access logging support for network filters, similar to HTTP filters, by allowing network filters to register as access logger instances. * **network_filter**: Added support for ``on_downstream_data`` (see :ref:`envoy_v3_api_field_extensions.filters.network.set_filter_state.v3.Config.on_downstream_data`) to the :ref:`set_filter_state network filter `, allowing connection filter state to be populated after first receiving data from the downstream connection. * **oauth2**: Added :ref:`allow_failed_matcher ` to allow requests to proceed to upstream as unauthenticated when OAuth validation fails (missing, invalid, or expired credentials) and the request matches the configured matchers. This enables graceful degradation patterns where services can handle both authenticated and unauthenticated requests. When triggered, all OAuth cookies are stripped and context headers ``x-envoy-oauth-status: failed`` and ``x-envoy-oauth-failure-reason`` are added. The matcher evaluation follows priority order: ``pass_through_matcher`` > ``allow_failed_matcher`` > ``deny_redirect_matcher`` > default OAuth behavior. * **oauth2**: Added ``TLS_CLIENT_AUTH`` for the OAuth2 HTTP filter to support RFC 8705 mutual TLS client authentication. In this mode ``token_secret`` is optional and ignored, and the token endpoint cluster must be configured with mTLS. * **outlier_detection**: Added :ref:`detect_degraded_hosts ` to enable passive degraded host detection. When enabled, outlier detection marks hosts as degraded when they return the ``x-envoy-degraded`` header. Degraded hosts are deprioritized in load balancing but remain in rotation (not ejected). The degraded state is cleared using the same backoff algorithm as ejection. Defaults to ``false``. * **overload_manager**: Added :ref:`ShrinkHeapConfig ` typed configuration for the ``envoy.overload_actions.shrink_heap`` overload action. This allows operators to configure the timer interval (``timer_interval``, minimum 1s, default 10s) and the memory release threshold (``max_unfreed_memory_bytes``, default 100MB) passed to ``tcmalloc::MallocExtension::ReleaseMemoryToSystem()``. * **ratelimit**: Added ``RemoteAddressMatch`` action to the rate limit filter. This action will generate a descriptor based on the remote address of the downstream connection by matching it against specified CIDR ranges with support for inversion and formatter substitution. * **ratelimit**: Added per-descriptor ``x-ratelimit-*`` headers support. See the :ref:`x_ratelimit_option ` field documentation for more details. * **ratelimit**: Added support for shadow mode in the local rate limit filter. * **redis**: Added support for ``BITFIELD_RO`` in ``redis_proxy``. * **resource_monitors**: Added cgroup v2 support to the CPU utilization resource monitor. The monitor now automatically detects and selects between cgroup v1 and v2 at runtime by checking available cgroup files on the system. This enables the resource monitor to work correctly in both cgroup v1 and v2 environments without configuration changes. * **reverse_tunnel**: Added optional tenant isolation support to the reverse tunnel network filter. When ``enable_tenant_isolation`` is set, Envoy scopes cached reverse tunnel sockets with composite ``@`` and ``@`` identifiers and rejects handshake headers that already contain the ``@`` delimiter to prevent ambiguous lookups. * **sse_parser**: Extended the SSE parser utility to support all standard SSE fields: ``id``, ``event`` (as ``event_type``), and ``retry``, in addition to the existing ``data`` field. The ``retry`` field is parsed as a ``uint32_t`` and only accepts values consisting of ASCII digits per the SSE specification. * **stat_sinks**: Added support for exporting OpenTelemetry metrics via HTTP. The new ``http_service`` field in :ref:`SinkConfig ` enables direct OTLP metrics export to backends that only accept HTTP (Dynatrace, Datadog, Elastic), without requiring an intermediate collector sidecar. * **stats**: Added support for cluster-level stats matcher, allowing more granular control over which stats are enabled and reported at the cluster level. This the stats matcher could be configured via the xDS API dynamically on a per-cluster basis. See :ref:`envoy.stats_matcher ` for more details. * **stats**: Added support to limit the number of metrics stored in each scope within the stats library. * **stats**: The admin prometheus stats endpoint now supports the protobuf exposition format, and will automatically use it if the request contains the correct Accept header, or if query parameter ``prom_protobuf=1`` is set. In a prometheus scrape configuration, add ``PrometheusProto`` to ``scrape_protocols`` to use the protobuf format. Additionally, when using the protobuf exposition format, the admin prometheus stats endpoint now supports `native histograms `_ when using the prometheus protobuf exposition format, using query ``/stats/prometheus?histogram_buckets=prometheusnative``. * **tcp_proxy**: Added :ref:`proxy_protocol_tlv_merge_policy ` to control how TLVs in ``proxy_protocol_tlvs`` are merged with existing PROXY protocol state. Supports ``ADD_IF_ABSENT`` (default), ``OVERWRITE_BY_TYPE_IF_EXISTS_OR_ADD``, and ``APPEND_IF_EXISTS_OR_ADD``. * **tcp_proxy**: Added an option to emit a log entry when the connection is accepted. * **tcp_proxy**: Propagate upstream TCP RST to downstream when detected close type is RemoteReset. This behavioral change can be temporarily reverted by setting runtime guard ``envoy.reloadable_features.propagate_upstream_rst_through_tunneled_tcp_proxy`` to false. * **tls**: Added a per-connection filter state object to select a workload trust domain in the SPIFFE validator in the multi-tenant deployments. * **tls**: Added support for building Envoy with OpenSSL as an alternative to the default BoringSSL. This is achieved through a BoringSSL compatibility layer (``bssl-compat``) that translates BoringSSL API calls to OpenSSL, allowing Envoy's TLS code to remain unchanged. To build with OpenSSL, use ``--config=openssl``. HTTP/3 (QUIC) is disabled for OpenSSL builds. Note that OpenSSL builds are not currently covered by the `Envoy security policy `_. See :repo:`bazel/SSL.md ` for details. * **tls**: Added support for fetching certificates on-demand via SDS in the upstream TLS transport socket using the extension :ref:`on-demand certificate selector `. * **tls**: Enhanced TLS certificate validation failure messages for CRL-related errors in access logs. The ``%DOWNSTREAM_TRANSPORT_FAILURE_REASON%`` and ``%UPSTREAM_TRANSPORT_FAILURE_REASON%`` access log formatters now include the certificate's CRL Distribution Point (CRLDP) information when CRL validation fails. For errors such as ``CRL for certificate was not provided``, ``CRL has expired``, ``CRL is not yet valid``, or ``certificate revoked``, the error message now includes the certificate's CRL distribution points (e.g., ``X509_verify_cert: certificate verification error at depth 0: certificate revocation check against provided CRLs failed: unable to get certificate CRL, certificate CRL distribution points: [http://crl.example.com/ca.crl, http://backup-crl.example.com/ca.crl]``). This provides better visibility into CRL validation failures and helps operators identify connectivity or CRL server issues without requiring debug-level logging. * **tls**: Exposed the SHA-256 fingerprint and serial number of the verified issuer (CA) certificate from the validated downstream mTLS peer certificate chain. Accessible via the ``%DOWNSTREAM_PEER_ISSUER_FINGERPRINT_256%`` and ``%DOWNSTREAM_PEER_ISSUER_SERIAL%`` :ref:`access log formatters `, and via the ``sha256PeerCertificateIssuerDigest()`` and ``serialNumberPeerCertificateIssuer()`` methods on :ref:`downstreamSslConnection() ` in the Lua filter. * **tls**: Extended TLS certificate compression (RFC 8879): added brotli to QUIC (which already supported zlib), and added brotli and zlib to TCP TLS. Controlled by runtime flag ``envoy.reloadable_features.tls_certificate_compression_brotli`` (defaults to ``true``). When disabled, QUIC retains zlib-only compression, while TCP TLS has no compression. * **tracers**: Added log events to spans created by the OpenTelemetry tracer. * **upstream**: Coalesced load balancer rebuilds during EDS batch host updates. When multiple priorities change in a single batch, each LB level (LoadBalancerBase, ZoneAwareLoadBalancerBase, EdfLoadBalancerBase, ThreadAwareLoadBalancerBase) now defers expensive per-priority recalculations to a single pass after the batch completes, reducing CPU spikes on large clusters. This behavior can be reverted by setting the runtime guard ``envoy.reloadable_features.coalesce_lb_rebuilds_on_batch_update`` to ``false``.