current.yaml

date: Pending

behavior_changes:
# *Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required*
- area: build
  change: |
    Moved the subset, ring_hash, and maglev LB code into extensions. If you use these load balancers and override
    extensions_build_config.bzl you will need to include them explicitly.
- area: build
  change: |
    Moved xDS code extensions. If you use the xDS and override extensions_build_config.bzl you will
    need to include the new config_subscriptions explicitly.
- area: http
  change: |
    When ``append_x_forwarded_host`` is enabled for a given route action it is now only appended iff it is different from the last
    value in the list. This resolves issues where a retry caused the same value to be appended multiple times. This
    behavioral change can be temporarily reverted by setting runtime guard ``envoy_reloadable_features_append_xfh_idempotent`` to false.

minor_behavior_changes:
# *Changes that may cause incompatibilities for some users, but should not for most*
- area: connection pool
  change: |
    Increase granularity mapping connection pool failures to specific stream failure reasons to make it more transparent why
    the stream is reset when a connection pool's connection fails.
- area: custom response
  change: |
    The filter now traverses matchers from most specific to least specific per filter config till a match is found for the response.
- area: http1
  change: |
    Allowing mixed case schemes in absolute urls (e.g. HtTp://www.google.com). Mixed case schemes will be normalized to
    the lower cased equivalents before being forwarded upstream. This behavior can be reverted by setting runtime flag
    ``envoy.reloadable_features.allow_absolute_url_with_mixed_scheme`` to false.
- area: http1
  change: |
    The HTTP1 server-side codec no longer considers encoding 1xx headers as
    starting the response. This allows the codec to raise protocol errors,
    sending detailed local replies instead of just closing the connection. This
    behavior can be reverted by setting runtime flag
    ``envoy.reloadable_features.http1_allow_codec_error_response_after_1xx_headers``
    to false.
- area: dns
  change: |
    Changing the DNS cache to use host:port as the cache key rather than host. This allows a
    downstream DFP filter to serve both secure and insecure clusters. This behavioral change
    can be reverted by setting runtime flag ``envoy.reloadable_features.dfp_mixed_scheme`` to false.
- area: uhv
  change: |
    Preserve case of %-encoded triplets in the default header validator. This behavior can be reverted by setting runtime flag
    ``envoy.reloadable_features.uhv_preserve_url_encoded_case`` to false, in which case %-encoded triplets are normalized
    to uppercase characters. This setting is only applicable when the Unversal Header Validator is enabled and has no effect otherwise.
- area: uhv
  change: |
    Allow malformed URL encoded triplets in the default header validator. This behavior can be reverted by setting runtime flag
    ``envoy.reloadable_features.uhv_allow_malformed_url_encoding`` to false, in which case requests with malformed URL encoded triplets
    in path are rejected. This setting is only applicable when the Unversal Header Validator is enabled and has no effect otherwise.
- area: ext_proc
  change: |
    When :ref:`clear_route_cache <envoy_v3_api_field_service.ext_proc.v3.CommonResponse.clear_route_cache>` is set, ext_proc will check
    for header mutations beforce clearing the route cache. Failures due to this check will be counted under the
    clear_route_cache_ignored stat.
- area: aws
  change: |
    Added support for fetching credentials from the AWS credentials file, which only happens if credentials cannot be fetched
    from environment variables. This behavioral change can be reverted by setting runtime guard
    ``envoy.reloadable_features.enable_aws_credentials_file`` to ``false``.
- area: http cookies
  change: |
    Changed internal format of http cookie to protobuf and added expiry timestamp. Processing expired cookie
    results in selection of a new upstream host and sending a new cookie to the client. Previous format of
    the cookie is still accepted, but is planned to be obsoleted in the future.
    This behavior change can be reverted by setting
    ``envoy.reloadable_features.stateful_session_encode_ttl_in_cookie`` to ``false``.
- area: overload manager
  change: |
    Changed behavior of the overload manager to error on unknown overload
    manager actions. Prior it would silently fail.  This change can be reverted
    temporarily by setting the runtime guard
    ``envoy.reloadable_features.overload_manager_error_unknown_action`` to
    false.
- area: router
  change: |
    Added check for existing metadata before setting metadata due to 'auto_sni', 'auto_san_validation', or
    'override_auto_sni_header' to prevent triggering ENVOY_BUG when an earlier filter has set the metadata.
- area: resource_monitors
  change: |
    Changed behavior of the fixed heap monitor to count unused mapped pages as
    free memory. This change can be reverted temporarily by setting the runtime guard
    ``envoy.reloadable_features.count_unused_mapped_pages_as_free`` to false.
- area: ext_proc
  change: |
    Filter metadata containing ext proc stats has been moved from ext-proc-logging-info to a namespace corresponding
    to the name of the ext_proc filter.
- area: stats
  change: |
    Added new type of gauge with type hidden. These stats are hidden from admin/stats-sinks but can shown with a
    query-parameter of ``/stats?hidden=include`` or ``/stats?hidden=showonly``.
- area: upstream
  change: |
    Changed behavior of the unpausing connect with 2xx status codes. This change can be reverted temporarily by
    setting the runtime guard ``envoy.reloadable_features.upstream_allow_connect_with_2xx`` to false.

bug_fixes:
# *Changes expected to improve the state of the world and are unlikely to have negative effects*
- area: oauth2
  change: |
    The Max-Age attribute of Set-Cookie HTTP response header was being assigned a value representing Seconds Since
    the Epoch, causing cookies to expire in ~53 years. This was fixed an now it is being assinged a value representing
    the number of seconds until the cookie expires.
    This behavioral change can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.oauth_use_standard_max_age_value`` to false.
- area: tls
  change: |
    Fix build FIPS compliance when using both FIPS mode and Wasm extensions (``--define boringssl=fips`` and ``--define wasm=v8``).
- area: ext_authz
  change: |
    Fix a bug where the ext_authz filter will ignore the request body when the
    :ref:`pack_as_bytes <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.BufferSettings.pack_as_bytes>` is set to true and
    HTTP authorization service is configured.
- area: router
  change: |
    Fixed the bug that updating :ref:`scope_key_builder
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.ScopedRoutes.scope_key_builder>`
    of SRDS config doesn't work and multiple HCM share the same ``scope_key_builder``.
- area: http
  change: |
    The :ref:`is_optional
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpFilter.is_optional>`
    field of HTTP filter can only be used for configuration loading of
    :ref:`HTTP filter <envoy_v3_api_msg_extensions.filters.network.http_connection_manager.v3.HttpFilter>`
    and will be ignored for loading of route or virtual host level filter config. This behavioral change
    can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.ignore_optional_option_from_hcm_for_route_config`` to false.
    You can also use
    :ref:`route/virtual host optional flag <envoy_v3_api_field_config.route.v3.FilterConfig.is_optional>`
    as a replacement of the feature.
- area: logging
  change: |
    Do not display GRPC_STATUS_NUMBER for non gRPC requests.
    This behavioral change can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.validate_grpc_header_before_log_grpc_status`` to false.
- area: boringssl
  change: |
    Fixed the crash that occurs when contrib is compiled with ``boringssl=fips`` defined.
- area: oauth2
  change: |
    The httpOnly attribute for Set-Cookie for tokens in HTTP response header was missing,
    causing tokens to be accessible from the JavaScript making the apps vulnerable.
    This was fixed now by marking the cookie as httpOnly.
    This behavioral change can be temporarily reverted by setting runtime guard
    ``envoy.reloadable_features.oauth_make_token_cookie_httponly`` to false.
- area: dependency
  change: |
    update Wasmtime and related deps -> 9.0.3 to resolve
    `CVE-2023-30624 <https://nvd.nist.gov/vuln/detail/CVE-2023-30624>`_.
- area: dependency
  change: |
    update C-ares -> 1.91.1 to resolve:

    - `CVE-2023-31130 <https://nvd.nist.gov/vuln/detail/CVE-2023-31130>`_.
    - `CVE-2023-31147 <https://nvd.nist.gov/vuln/detail/CVE-2023-31147>`_.
    - `CVE-2023-31124 <https://nvd.nist.gov/vuln/detail/CVE-2023-31124>`_.
    - `CVE-2023-32067 <https://nvd.nist.gov/vuln/detail/CVE-2023-32067>`_.

removed_config_or_runtime:
# *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
- area: http
  change: |
    removed runtime key ``envoy.reloadable_features.closer_shadow_behavior`` and legacy code paths.
- area: http
  change: |
    removed runtime key ``envoy.reloadable_features.allow_upstream_filters`` and legacy code paths.
- area: quic
  change: |
    removed runtime key ``envoy.reloadable_features.quic_defer_send_in_response_to_packet`` and legacy code paths.
- area: upstream
  change: |
    removed runtime key ``envoy.reloadable_features.fix_hash_key`` and legacy code paths.
- area: logging
  change: |
    removed runtime key ``envoy.reloadable_features.correct_remote_address`` and legacy code paths.
- area: http
  change: |
    removed runtime key ``envoy.reloadable_features.http_response_half_close`` and legacy code paths.
- area: udp
  change: |
    removed runtime key ``envoy.reloadable_features.udp_proxy_connect`` and legacy code paths.
- area: header_formatters
  change: |
    removed runtime key ``envoy.reloadable_features.unified_header_formatter`` and legacy code paths.
- area: tls
  change: |
    remove runtime key ``envoy.reloadable_features.tls_async_cert_validation`` and legacy code paths.
- area: config
  change: |
    removed runtime key ``envoy.reloadable_features.delta_xds_subscription_state_tracking_fix`` and legacy code paths.
- area: http
  change: |
    removed runtime key ``envoy.reloadable_features.http_strip_fragment_from_path_unsafe_if_disabled`` and legacy code paths.

new_features:
- area: access_log
  change: |
    added %ACCESS_LOG_TYPE% substitution string, to help distinguishing between access log records and when they are being
    recorded. Please refer to the access log configuration documentation for more information.
- area: access_log
  change: |
    added :ref:`CEL <envoy_v3_api_msg_extensions.formatter.cel.v3.Cel>` access log formatter to print CEL expression.
- area: access_log
  change: |
    (QUIC only) Added support for %BYTES_RETRANSMITTED% and %PACKETS_RETRANSMITTED%.
- area: dynamic_forward_proxy
  change: |
    added :ref:`sub_clusters_config
    <envoy_v3_api_field_extensions.clusters.dynamic_forward_proxy.v3.ClusterConfig.sub_clusters_config>` to enable
    independent sub cluster for each host:port, with STRICT_DNS cluster type.
- area: http
  change: |
    added Runtime feature ``envoy.reloadable_features.max_request_headers_size_kb`` to override the default value of
    :ref:`max request headers size
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.max_request_headers_kb>`.
- area: listeners
  change: |
    added :ref:`max_connections_to_accept_per_socket_event
    <envoy_v3_api_field_config.listener.v3.Listener.max_connections_to_accept_per_socket_event>`
    that sets the maximum number of new connections to be accepted per socket
    event on a listener. If there are more connections to be accepted beyond
    the maximum, the remaining connections would be processed in later
    dispatcher loop iterations.
- area: load shed point
  change: |
    added load shed point ``envoy.load_shed_points.http_connection_manager_decode_headers`` that rejects new http streams
    by sending a local reply.
- area: load shed point
  change: |
    added load shed point ``envoy.load_shed_points.http1_server_abort_dispatch`` that rejects HTTP1 server processing of requests.
- area: load shed point
  change: |
    added load shed point ``envoy.load_shed_points.http2_server_go_away_on_dispatch`` that sends
    ``GOAWAY`` for HTTP2 server processing of requests.  When a ``GOAWAY`` frame is submitted by
    this the counter ``http2.goaway_sent`` will be incremented.
- area: matchers
  change: |
    Added :ref:`RuntimeFraction <envoy_v3_api_msg_extensions.matching.input_matchers.runtime_fraction.v3.RuntimeFraction>` input
    matcher. It allows matching hash of the input on a runtime key.
- area: stat_sinks
  change: |
    Added ``envoy.stat_sinks.open_telemetry`` stats_sink, that supports flushing metrics by the OTLP protocol,
    for supported Open Telemetry collectors.
- area: redis_proxy
  change: |
    added new configuration field :ref:`key_formatter
    <envoy_v3_api_field_extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.key_formatter>` to format redis key.
    The field supports using %KEY% as a formatter command for substituting the redis key as part of the substitution formatter expression.
- area: ratelimit
  change: |
    added new configuration field :ref:`domain
    <envoy_v3_api_field_extensions.filters.http.ratelimit.v3.RateLimitPerRoute.domain>` to allow for setting rate limit domains on a
    per-route basis.
- area: tls_inspector
  change: |
    added histogram ``bytes_processed`` which records the number of bytes of
    the tls_inspector processed while analyzing for tls usage. In cases where
    the connection uses tls this records the tls client hello size. In cases
    where the connection doesn't use tls this records the amount of bytes the
    tls_inspector processed until it realized the connection was not using tls.
- area: tls_inspector
  change: |
    added new configuration field :ref:`initial_read_buffer_size
    <envoy_v3_api_field_extensions.filters.listener.tls_inspector.v3.TlsInspector.initial_read_buffer_size>`
    to allow users to tune the buffer size requested by the filter. If
    configured, and the filter needs additional bytes, the filter will double
    the number of bytes requested up to the default 64KiB maximum.
- area: access_log
  change: |
    added access log filter :ref:`log_type_filter <envoy_v3_api_field_config.accesslog.v3.AccessLogFilter.log_type_filter>`
    to filter access log records based on the type of the record.
- area: ext_proc
  change: |
    added new configuration field
    :ref:`disable_clear_route_cache <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.disable_clear_route_cache>`
    to force the ext_proc filter from clearing the route cache. Failures to clear from setting this field will be counted under the
    clear_route_cache_disabled stat.
- area: ext_proc
  change: |
    added new configuration field
    :ref:`allow_mode_override <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.allow_mode_override>`
    If set to true, the filter config
    :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>`
    can be overridden by the
    :ref:`mode_override <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.mode_override>`
    in the response message from the external processing server.
    If not set, the ``mode_override`` API in the response message will be ignored.
- area: ext_proc
  change: |
    :ref:`forward_rules <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.forward_rules>`
    to only allow headers matchinging the forward rules to be forwarded to the external processing server.
- area: redis_proxy
  change: |
    added new field :ref:`connection_rate_limit
    <envoy_v3_api_field_extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.connection_rate_limit>`
    to limit reconnection rate to redis server to avoid reconnection storm.
- area: match_delegate
  change: |
    added :ref:`per route configuration
    <envoy_v3_api_msg_extensions.common.matching.v3.ExtensionWithMatcherPerRoute>` to the
    :ref:`ExtensionWithMatcher
    <envoy_v3_api_msg_extensions.common.matching.v3.ExtensionWithMatcher>` filter.
    Which allows the associated matcher to be defined on a per route basis.
- area: match_delegate
  change: |
    If no matcher is set the :ref:`ExtensionWithMatcher
    <envoy_v3_api_msg_extensions.common.matching.v3.ExtensionWithMatcher>` filter is now set to skip rather than erroring out.
- area: access_log
  change: |
    added additional HCM access log option :ref:`flush_log_on_tunnel_successfully_established
    <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.HcmAccessLogOptions.flush_log_on_tunnel_successfully_established>`.
    Enabling this option will write a log to all access loggers when HTTP tunnels (e.g. Websocket and CONNECT)
    are successfully established.
- area: admin
  change: |
    Adds a new admin stats html bucket-mode ``detailed`` to generate all recorded buckets and summary percentiles.
- area: http
  change: |
    Add support to the route/virtual host level
    :ref:`is_optional <envoy_v3_api_field_config.route.v3.FilterConfig.is_optional>` field.
    A route/virtual host level per filter config can be marked as optional, which means that if
    the filter fails to load, the configuration will no be rejected.
- area: upstream
  change: |
    Added :ref:`cluster provided extension
    <envoy_v3_api_msg_extensions.load_balancing_policies.cluster_provided.v3.ClusterProvided>`
    to suppport the :ref:`load balancer policy <envoy_v3_api_field_config.cluster.v3.Cluster.load_balancing_policy>`.
- area: fault
  change: |
    added new field ``envoy.extensions.filters.http.fault.v3.HTTPFault.filter_metadata`` to aid in logging.
    Metadata will be stored in StreamInfo dynamic metadata under a namespace corresponding to the name of the fault filter.
- area: application_logs
  change: |
    Added bootstrap option
    :ref:`application_log_format <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.ApplicationLogConfig.LogFormat.json_format>`
    to enable setting application log format as JSON structure.
- area: application_logs
  change: |
    Added bootstrap option
    :ref:`application_log_format <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.ApplicationLogConfig.LogFormat.text_format>`
    to enable setting application log text format from config.
- area: ext_proc
  change: |
    added new field ``filter_metadata <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExtProc.filter_metadata`` to aid in logging.
    Metadata will be stored in StreamInfo filter metadata under a namespace corresponding to the name of the ext proc filter.
- area: matching
  change: |
    added CEL(Common Expression Language) matcher support :ref:`CEL data input <extension_envoy.matching.inputs.cel_data_input>`
    and :ref:`CEL input matcher <extension_envoy.matching.matchers.cel_matcher>`.
- area: tls
  change: |
    Added support for hot-reloading CRL file when the file changes on disk.
    This works with dynamic secrets when
    :ref:`CertificateValidationContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CertificateValidationContext>`
    is delivered via SDS.
- area: http
  change: |
    added support for configuring additional :ref:`cookie attributes <envoy_v3_api_msg_config.route.v3.RouteAction.HashPolicy.cookie>`.
- area: http
  change: |
    Added support for the route/virtual host level
    :ref:`disabled <envoy_v3_api_field_config.route.v3.FilterConfig.disabled>` field.
    A route/virtual host level per filter config can be marked as disabled, which means that
    the filter will be disabled in a specific route/virtual host.
- area: health_check
  change: |
    added host related information :ref:`metadata <envoy_v3_api_field_data.core.v3.HealthCheckEvent.metadata>` and
    :ref:`locality <envoy_v3_api_field_data.core.v3.HealthCheckEvent.locality>` to
    the :ref:`health check event <envoy_v3_api_msg_data.core.v3.HealthCheckEvent>` definition.
- area: zookeeper
  change: |
    Added the "addWatch" opcode support to the ZooKeeper proxy filter.
- area: config
  change: |
    added a statistic :ref:`warming_state <config_cluster_stats>` to indicate the current warming state of a cluster.
- area: access_log
  change: |
    added bytes snapshotting for upstream and downstream logging that will be reset after every periodic log. Downstream
    periodic loggers should read BytesMeter::bytesAtLastDownstreamPeriodicLog(), and upstream periodic loggers should read
    BytesMeter::bytesAtLastUpstreamPeriodicLog().
- area: lds
  change: |
    pause SRDS when LDS is updated.

deprecated:
- area: access_log
  change: |
    deprecated (1.25.0) :ref:`intermediate_log_entry <envoy_v3_api_field_data.accesslog.v3.AccessLogCommon.intermediate_log_entry>`
    in favour of :ref:`access_log_type <envoy_v3_api_field_data.accesslog.v3.AccessLogCommon.access_log_type>`.
- area: health_check
  change: |
    deprecated the :ref:`HealthCheck event_log_path <envoy_v3_api_field_config.core.v3.HealthCheck.event_log_path>` in favor of
    :ref:`HealthCheck event_logger extension <envoy_v3_api_field_config.core.v3.HealthCheck.event_logger>`.