current.yaml

date: Pending

behavior_changes:
# *Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required*
- area: http
  change: |
    Remove the hop by hop TE header from downstream request headers if it's not set to ``trailers``, else keep it. This change can be
    temporarily reverted by setting ``envoy.reloadable_features.sanitize_te`` to false.
- area: stats
  change: |
    The runtime flag ``envoy.reloadable_features.enable_include_histograms`` is now enabled by default.
    This causes the ``includeHistogram()`` method on ``Stats::SinkPredicates`` to filter histograms to
    be flushed to stat sinks.
- area: http2
  change: |
    Changes the default value of ``envoy.reloadable_features.http2_use_oghttp2`` to ``false``. This changes the codec used for HTTP/2
    requests and responses. A number of users have reported issues with oghttp2 including issue 32611 and issue 32401 This behavior
    can be reverted by setting the feature to ``true``.

minor_behavior_changes:
# *Changes that may cause incompatibilities for some users, but should not for most*
- area: sockets
  change: |
    Failure to create an upstream socket should now result in clean connection failure rather than failing a release assert. This behavior
    can be temporarily reverted by setting runtime feature ``envoy.restart_features_.allow_client_socket_creation_failure`` to false.
- area: adaptive concurrency filter stats
  change: |
    Multiply the gradient value stat by 1000 to make it more granular (values will range between 500 and 2000).
- area: quic
  change: |
    :ref:`Server preferred address <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.server_preferred_address_config>` is
    now sent to non-quiche quic clients when configured. This behavior can be disabled with runtime flag
    ``envoy.reloadable_features.quic_send_server_preferred_address_to_all_clients``.
- area: dns
  change: |
    Allowing <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.dns_min_refresh_rate>` to go as low as 1s.
- area: upstream
  change: |
    Upstream now excludes hosts set to ``DRAINING`` state via EDS from load balancing and panic routing
    threshold calculation. This feature can be disabled by setting
    ``envoy.reloadable_features.exclude_host_in_eds_status_draining`` to false.
- area: golang
  change: |
    Change ``RegisterHttpFilterConfigFactoryAndParser`` to ``RegisterHttpFilterFactoryAndConfigParser``.
- area: QUIC
  change: |
    Port migration is default turned off. QUIC client connections will no longer attempt to migrate to a new port when connections
    is degrading. Can be manually turned on via
    :ref:`port_migration <envoy_v3_api_field_config.core.v3.QuicProtocolOptions.num_timeouts_to_trigger_port_migration>`.
- area: QUIC
  change: |
    Make each upstream connection to read as many as 32 packets in each event loop. This feature can be disabled by setting
    ``envoy.reloadable_features.quic_upstream_reads_fixed_number_packets`` to false.
- area: aws
  change: |
    AWS region string is now retrieved from environment and profile consistently within aws_request_signer and
    grpc_credentials/aws_iam extensions. Region field in aws_request_signer is now optional, explicitly configured
    xDS region will take preference. aws_request_signer documentation now reflects the region chain.
- area: http
  change: |
    Enable obsolete line folding in BalsaParser (for behavior parity with http-parser, the
    previously used HTTP/1 parser).
- area: proxy status
  change: |
    Add more conversion in the proxy status utility. It can be disabled by the runtime guard
    ``envoy.reloadable_features.proxy_status_mapping_more_core_response_flags``.
- area: http2
  change: |
    Simplifies integration with the codec by removing translation between nghttp2 callbacks and Http2VisitorInterface events.
    Guarded by ``envoy.reloadable_features.http2_skip_callback_visitor``.
- area: http3
  change: |
    Use GRO (Generic Receive Offload) for reading packets from a client QUIC UDP socket. See
    https://www.kernel.org/doc/html/next/networking/segmentation-offloads.html for a description of
    GRO. This behavior change can be reverted by setting
    ``envoy.reloadable_features.prefer_quic_client_udp_gro`` to ``false``.
- area: http3
  change: |
    Disables recvmmsg (multi-message) for reading packets from a client QUIC UDP socket, if GRO
    is not set or not supported. recvmsg will be used instead. This behavior change can be
    reverted by setting ``envoy.reloadable_features.disallow_quic_client_udp_mmsg`` to ``false``.

bug_fixes:
# *Changes expected to improve the state of the world and are unlikely to have negative effects*
- area: http3_upstream
  change: |
    Fixing a bug with HTTP/3 upstream using a non-threadsafe cache cross-thread. Bumping HTTP/3 support down
    to alpha as the severity of this bug indicates it is both not in use and not GA quality code.
- area: tracers
  change: |
    use unary RPC calls for OpenTelemetry trace exports, rather than client-side streaming connections.
- area: stateful_session
  change: |
    Support 0 TTL for proto-encoded cookies, which disables cookie expiration by Envoy.
- area: load balancing
  change: |
    Added randomization in locality load-balancing initialization. This helps desynchronizing Envoys across
    a fleet by randomizing the scheduler starting point. This can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.edf_lb_locality_scheduler_init_fix`` to false.
- area: load balancing
  change: |
    Added randomization in host load-balancing initialization. This helps desynchronizing Envoys across
    a fleet by randomizing the scheduler starting point. This can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.edf_lb_host_scheduler_init_fix`` to false.
- area: UDP and TCP tunneling
  change: |
    fixed a bug where second HTTP response headers received would cause Envoy to crash in cases where
    ``propagate_response_headers`` and retry configurations are enabled at the same time, and an upstream
    request is retried multiple times.
- area: xds
  change: |
    Reject xDS configurations where the rate-limit's :ref:`fill_rate <envoy_v3_api_field_config.core.v3.RateLimitSettings.fill_rate>`
    is set to Infinity or NaN.
- area: tracing
  change: |
    Prevent Envoy from crashing at start up when the OpenTelemetry environment resource detector cannot detect any attributes.
- area: proxy protocol
  change: |
    Fixed a crash when Envoy is configured for PROXY protocol on both a listener and cluster, and the listener receives
    a PROXY protocol header with address type LOCAL (typically used for health checks).
- area: url matching
  change: |
    Fixed excessive CPU utilization when using regex URL template matcher.
- area: http
  change: |
    Fixed crash when HTTP request idle and per try timeouts occurs within backoff interval.
- area: quic
  change: |
    Fixed crash bug with QUIC upstream + X.509v1 certificates.
- area: proxy_protocol
  change: |
    Fix crash due to uncaught exception when the operating system does not support an address type (such as IPv6) that is
    received in a proxy protocol header. Connections will instead be dropped/reset.
- area: proxy_protocol
  change: |
    Fixed a bug where TLVs with non utf8 characters were inserted as protobuf values into filter metadata circumventing
    ext_authz checks when ``failure_mode_allow`` is set to ``true``.
- area: tls
  change: |
    Fix crash due to uncaught exception when the operating system does not support an address type (such as IPv6) that is
    received in an mTLS client cert IP SAN. These SANs will be ignored. This applies only when using formatter
    ``%DOWNSTREAM_PEER_IP_SAN%``.
- area: tcp_proxy
  change: |
    When tunneling TCP over HTTP, closed the downstream connection (for writing only) when upstream trailers are read
    to support half close semantics during TCP tunneling.
    This behavioral change can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.tcp_tunneling_send_downstream_fin_on_upstream_trailers`` to false.
- area: eds-caching
  change: |
    Fixing an issue where EDS caching is used (protected by the ``envoy.restart_features.use_eds_cache_for_ads``
    runtime flag that is false by default), when multiple clusters use the same EDS resource, and that cached EDS
    resource is used.
- area: jwt_authn
  change: |
    Fixed JWT extractor, which concatenated headers with a comma, resultig in invalid tokens.
- area: jwt_authn
  change: |
    Added
    :ref:`max_lifetime <envoy_v3_api_field_extensions.filters.http.jwt_authn.v3.JwtProvider.max_lifetime>` and
    :ref:`require_expiration <envoy_v3_api_field_extensions.filters.http.jwt_authn.v3.JwtProvider.require_expiration>`
    to limit the maximum remaining lifetime of a token from a ``JwtProvider`` and implement restrictions for JWT-SVIDs.
- area: router
  change: |
    Fix a timing issue when upstream requests are empty when decoding data and send local reply when that happens. This is
    controlled by ``envoy_reloadable_features_send_local_reply_when_no_buffer_and_upstream_request``.
- area: deps
  change: |
    Updated QUICHE dependencies to incorporate fixes for https://github.com/envoyproxy/envoy/issues/32401.
- area: tracing
  change: |
    Dynatrace resource detector: Only log warning message when no enrichment attributes are found.
- area: oauth
  change: |
    When performing a token refresh and forwarding tokens upstream, replace existing token cookies rather than appending as
    another Cookie header.

removed_config_or_runtime:
# *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
- area: http
  change: |
    Removed ``envoy.reloadable_features.allow_absolute_url_with_mixed_scheme`` runtime flag and legacy code paths.
- area: active health check
  change: |
    Removed ``envoy.reloadable_features.keep_endpoint_active_hc_status_on_locality_update`` runtime flag and legacy code paths.
- area: http1
  change: |
    Removed ``envoy.reloadable_features.http1_allow_codec_error_response_after_1xx_headers`` runtime flag and legacy code paths.
- area: overload manager
  change: |
    removed ``envoy.reloadable_features.overload_manager_error_unknown_action`` and legacy code paths.
- area: http
  change: |
    Removed ``envoy_reloadable_features_append_xfh_idempotent`` runtime flag and legacy code paths.
- area: resource_monitors
  change: |
    removed ``envoy.reloadable_features.count_unused_mapped_pages_as_free`` runtime flag  and legacy code paths.
- area: aws
  change: |
    Removed ``envoy.reloadable_features.enable_aws_credentials_file`` runtime flag and legacy code paths.
- area: upstream
  change: |
    removed ``envoy_reloadable_features_initialize_upstream_filters`` and legacy code paths.

new_features:
- area: ext_proc
  change: |
    Added
    :ref:`grpc_initial_metadata <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExtProcOverrides.grpc_initial_metadata>`
    config API to allow extending inherited metadata from
    :ref:`ExternalProcessor.grpc_service <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.grpc_service>`
    and
    :ref:`ExtProcOverrides.grpc_service <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExtProcOverrides.grpc_service>`
    with the new or updated values.
- area: aws_request_signing
  change: |
    Update ``aws_request_signing`` filter to support use as an upstream HTTP filter. This allows successful calculation of
    signatures after the forwarding stage has completed, particularly if the path element is modified.
- area: aws_lambda
  change: |
    Update ``aws_lambda`` filter to support use as an upstream HTTP filter. This allows successful calculation of
    signatures after the forwarding stage has completed, particularly if the path element is modified.
- area: grpc reverse bridge
  change: |
    Change HTTP status to 200 to respect the gRPC protocol. This may cause problems for incorrect gRPC clients expecting the filter
    to preserve HTTP 1.1 responses.  This behavioral change can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.grpc_http1_reverse_bridge_change_http_status`` to false.
- area: quic
  change: |
    Added QUIC protocol option :ref:`send_disable_active_migration
    <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.send_disable_active_migration>` to make the server send clients a transport
    parameter to discourage client endpoints from active migration.
- area: quic
  change: |
    Added support for QUIC listeners to :ref:`choose certificates based on SNI <arch_overview_ssl_cert_select>` and load certificates
    from formats other than PEM, such as :ref:`pkcs12 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.pkcs12>`.
    This behavior can be disabled with runtime flag ``envoy.restart_features.quic_handle_certs_with_shared_tls_code``.
- area: ext_proc
  change: |
    implemented
    :ref:`request_attributes <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.request_attributes>`
    and
    :ref:`response_attributes <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.response_attributes>`
    config APIs to enable sending and receiving attributes to/from the external processing server.
- area: access log
  change: |
    added support for :ref:`%UPSTREAM_CONNECTION_ID% <config_access_log_format_upstream_connection_id>` for the upstream connection
    identifier.
- area: aws_lambda
  change: |
    Added :ref:`host_rewrite <envoy_v3_api_field_extensions.filters.http.aws_lambda.v3.Config.host_rewrite>` config to be used
    during signature.
- area: http3
  change: |
    Added experimental support for sending and receiving HTTP/3 METADATA frames.
- area: ext_proc
  change: |
    added
    :ref:`metadata_options <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.metadata_options>`
    config API to enable sending and receiving metadata from/to the external processing server. Both typed and untyped dynamic
    metadata may be sent to the server. If
    :ref:`receiving_namespaces <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.MetadataOptions.receiving_namespaces>`
    is defined, returned metadata may be written to the specified allowed namespaces.
- area: wasm
  change: |
    added ``verify_signature`` foreign function to verify cryptographic signatures.
- area: monitoring
  change: |
    Add ``Envoy::ExecutionContext``, which is notified by ``ScopeTrackerScopeState``'s constructor and destructor. This feature is
    disabled by default, it can be enabled by runtime feature flag ``envoy.restart_features.enable_execution_context``. For more details,
    please see https://github.com/envoyproxy/envoy/issues/32012.
- area: rbac
  change: |
    Added :ref:`uri_template<envoy_v3_api_field_config.rbac.v3.Permission.uri_template>` which uses existing
    :ref:`UriTemplateMatchConfig<envoy_v3_api_msg_extensions.path.match.uri_template.v3.UriTemplateMatchConfig>`
    to allow use of glob patterns for URI path matching in RBAC.
- area: upstream
  change: |
    Added :ref:`selection_method <envoy_v3_api_msg_extensions.load_balancing_policies.least_request.v3.LeastRequest>`
    option to the least request load balancer. If set to ``FULL_SCAN``,
    Envoy will select the host with the fewest active requests from the entire host set rather than
    :ref:`choice_count <envoy_v3_api_msg_extensions.load_balancing_policies.least_request.v3.LeastRequest>`
    random choices.
- area: access_loggers
  change: |
    Added :ref:`Fluentd access logger <envoy_v3_api_msg_extensions.access_loggers.fluentd.v3.FluentdAccessLogConfig>`
    to support flushing access logs in `Fluentd format <https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1>`_.
- area: redis
  change: |
    Added support for the ``ECHO`` command.
- area: tcp_proxy
  change: |
    added an option to dynamically set a per downstream connection idle timeout period object under the key
    ``envoy.tcp_proxy.per_connection_idle_timeout_ms``. If this filter state value exists, it will override the idle timeout
    specified in the filter configuration and the default idle timeout.
- area: load shed point
  change: |
    Added load shed point ``envoy.load_shed_points.hcm_ondata_creating_codec`` that closes connections before creating codec if
    Envoy is under pressure, typically memory.
- area: health_checks
  change: |
    added a :ref:`configuration option <envoy_v3_api_field_config.core.v3.HealthCheck.always_log_health_check_success>` that enables
    health check logs on each successful health check.
- area: string matcher
  change: |
    Added an :ref:`extension point for custom string matcher implementations <envoy_v3_api_field_type.matcher.v3.StringMatcher.custom>`.
    An implementation for :ref:`running a Lua script <envoy_v3_api_msg_extensions.string_matcher.lua.v3.Lua>` is included.
- area: overload
  change: |
    added a :ref:`configuration option
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.append_local_overload>` to add
    ``x-envoy-local-overloaded`` header when Overload Manager is triggered.
- area: tracing
  change: |
    Added support to configure a Dynatrace sampler for the OpenTelemetry tracer.
- area: tracing
  change: |
    Added User-Agent header to OTLP trace exporters according to the OpenTelemetry specification.
- area: http
  change: |
    Added DownstreamRemoteReset to CoreResponseFlag, and it is set when stream is remote reset.
- area: tracing
  change: |
    Added support for variant span attribute type for the OpenTelemetry tracer.
- area: oauth
  change: |
    :ref:`deny_redirect_matcher <envoy_v3_api_field_extensions.filters.http.oauth2.v3.OAuth2Config.deny_redirect_matcher>`
    to support disabling authorization redirects for specific requests, e.g. AJAX requests.
- area: jwt_authn
  change: |
    Added
    :ref:`subjects <envoy_v3_api_field_extensions.filters.http.jwt_authn.v3.JwtProvider.subjects>` to allow restrictions
    of subjects a ``JwtProvider`` can assert.
- area: aws_request_signing
  change: |
    Update ``aws_request_signing`` filter to support optionally sending the aws signature in query parameters rather than headers,
    by specifying the :ref:`query_string <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.query_string>`
    configuration section.

deprecated:
- area: listener
  change: |
    deprecated runtime key ``overload.global_downstream_max_connections`` in favor of :ref:`downstream connections monitor
    <envoy_v3_api_msg_extensions.resource_monitors.downstream_connections.v3.DownstreamConnectionsConfig>`.
- area: tracing
  change: |
    deprecated :ref:`split_spans_for_request <envoy_v3_api_field_config.trace.v3.ZipkinConfig.split_spans_for_request>`
    in favor of :ref:`spawn_upstream_span
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.spawn_upstream_span>`.