1.31.0 (July 19, 2024)

Incompatible behavior changes

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

  • composite_filter: Adding support for sample_percent. It specifies the probability of the action execution. If not specified, it is 100%.

  • ext_proc: Adding support for route_cache_action. It specifies the route action to be taken when an external processor response is received in response to request headers.

  • golang: Move Continue, SendLocalReply and RecoverPanic from FilterCallbackHandler to DecoderFilterCallbacks and EncoderFilterCallbacks, to support full-duplex processing.

  • http2: Changes the default value of envoy.reloadable_features.http2_use_oghttp2 to true. This changes the codec used for HTTP/2 requests and responses. This behavior can be reverted by setting the feature to false.

  • http2: Passes HTTP/2 DATA frames through a different codec API. This behavior can be temporarily disabled by setting the runtime feature envoy.reloadable_features.http2_use_visitor_for_data to false.

  • http3: Added a happy eyeballs feature to HTTP/3 upstream, where it assuming happy eyeballs sorting results in alternating address families will attempt the first v4 and v6 address before giving up on HTTP/3. This change can be reverted by setting envoy.reloadable_features.http3_happy_eyeballs to false.

  • local_ratelimit: Updated the token bucket implementation to use non-timer based token bucket. The tokens will be refilled when the token bucket is accessed and no dependency on the timer. This behavior can be temporarily reverted by setting the runtime guard envoy.reloadable_features.no_timer_based_rate_limit_token_bucket to false.

  • proxy_protocol: Populate typed metadata by default in proxy protocol listener. Typed metadata can be consumed as TlvsMetadata type. This change can be temporarily disabled by setting the runtime flag envoy.reloadable_features.use_typed_metadata_in_proxy_protocol_listener to false.

  • runtime: Rejecting invalid YAML. This has been an ENVOY_BUG linked to https://github.com/envoyproxy/envoy/issues/27434 for over a year with no hard-blockers so should be Ok. This behavior can be temporarily disabled by setting the runtime feature envoy.reloadable_features.reject_invalid_yaml to false but the runtime guard must be parsed before any invalid YAML.

  • thread_local: Changes the behavior of the SlotImpl class destructor. With this change the destructor can be called on any thread. This behavior can be reverted by setting the runtime flag envoy.reloadable_features.allow_slot_destroy_on_worker_threads to false.

  • tracing/datadog: Disabled remote configuration by default. To enable this feature, use the remote_config field.

Minor behavior changes

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

  • access_log: The %CEL% formatter supports call functions.

  • access_log: The upstream connection address, rather than the upstream host address, will be used for the %UPSTREAM_REMOTE_ADDRESS%, %UPSTREAM_REMOTE_PORT% and %UPSTREAM_REMOTE_ADDRESS_WITHOUT_PORT% access log format specifiers. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.upstream_remote_address_use_connection to false.

  • config: In xDS configuration, the AUTO value now means V3. AUTO is the default value of the enum, so this field may be omitted from all configurations now.

  • config: Stricter validation of a google.protobuf.Duration field in a config, rejecting invalid values (where the number of years is over 292). This can be temporarily reverted by setting runtime guard envoy.reloadable_features.strict_duration_validation to false.

  • custom response filter: Prevent the redirect policy from sending 100 as the overridden response code as the custom response must be complete.

  • dfp: Changed dynamic forward proxy so local reply errors include DNS resolution details. This behavior can be temporarily disabled by setting the runtime feature envoy.reloadable_features.dns_details to false.

  • dns: Changes the behavior of the getaddrinfo DNS resolver so that it treats EAI_NODATA and EAI_NONAME as successful queries with empty results, instead of as DNS failures. This change brings the getaddrinfo behavior in-line with the c-ares resolver behavior. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.dns_nodata_noname_is_success to false.

  • ext_proc: Timeout errors in external processor now returns 504 Gateway Timeout to downstream clients. The previous behavior was returning 500 Internal Server Error.

  • filters: Set WWW-Authenticate header for 401 responses from the Basic Auth filter.

  • gcp_authn: Use the fixed URL format instead of one from the configuration. This behavior can be disabled by setting runtime flag envoy.reloadable_features.gcp_authn_use_fixed_url to false.

  • grpc: Changes in AsyncStreamImpl and GoogleAsyncStreamImpl now propagate tracing context headers in bidirectional streams when using Envoy gRPC client or Google C++ gRPC client. Previously, tracing context headers were not being set when calling external services such as ext_proc.

  • hashing: Change murmurHash2 hashing on big endian platforms to generate the same values as little endian platforms.

  • http: Changing HTTP/2 semi-colon prefixed headers to being sanitized by Envoy code rather than nghttp2. Should be a functional no-op but guarded by envoy.reloadable_features.sanitize_http2_headers_without_nghttp2.

  • http: Changing header validation checks in the substitution format utility and CEL code to do RFC-compliant header validation. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.consistent_header_validation to false.

  • http: Envoy will now proxy 104 headers from upstream, though as with 100 only the first 1xx response headers will be sent. 104 headers are designated by IETF’s draft-ietf-httpbis-resumable-upload RFC. This behavioral can be temporarily reverted by setting runtime guard envoy.reloadable_features.proxy_104 to false.

  • http: Fixed host header changes for shadow requests to properly handle ipv6 addresses.

  • http: Reject messages with chunked transfer encoding with chunk extension containing CR not followed by LF. This can be temporarily reverted by setting runtime guard envoy.reloadable_features.http1_balsa_disallow_lone_cr_in_chunk_extension to false.

  • http: Removed runtime guard envoy.reloadable_features.refresh_rtt_after_request and legacy code path.

  • jwt_authn: Changes the behavior of the forward config. Previously, the config only removes JWT if set in headers. With this addition, the config can also be used to remove JWT set in query parameters. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.jwt_authn_remove_jwt_from_query_params to false.

  • jwt_authn: jwt_authn now validates provider URIs. If the validation is too strict it can temporarily be disabled by setting the runtime guard envoy.reloadable_features.jwt_authn_validate_uri to false.

  • quic: A change in QUICHE has renamed all flags formerly of the form quic_reloadable_flag_... to quiche_reloadable_flag_.... Likewise, for quic_restart_flag_..., now quiche_restart_flag_.... Consequently, all Envoy flags of those forms with an envoy_quic_... prefix have been similarly renamed to envoy_quiche_....

  • quic: Cache source/destination address instances in a LRU cache for packet read to improve performance. This behavior can be reverted by setting the runtime guard envoy.reloadable_features.quic_upstream_socket_use_address_cache_for_read to false.

  • quic: When a quic connection socket is created, the socket’s detected transport protocol will be set to quic.

  • statistics: Hot restart statistics like hot_restart_epoch are only set when hot restart is enabled.

  • tracers: Set status code for OpenTelemetry tracers (previously unset).

  • udp: Change GRO read buffer to 64kB to avoid MSG_TRUNC. And change the way to limit the number of packets processed per event loop to work with GRO. This behavior can be reverted by setting runtime guard envoy.reloadable_features.udp_socket_apply_aggregated_read_limit to false.

  • xds: Updated xDS-TP path naming to better comply with RFC-3986. Encoded resource paths can now include an a colon :, instead of %3A. This behavior can be reverted by setting the runtime flag envoy.reloadable_features.xdstp_path_avoid_colon_encoding to false.

Bug fixes

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

  • admin: Fixed missing additional addresses for LbEndpoint in config dump.

  • admission control: Fixed the thread-local controller’s average RPS calculation to be calculated over the full lookback window. Previously, the controller would calculate the average RPS over the amount of time elapsed since the oldest valid request sample. This change brings the behavior in line with the documentation.

  • async http client: Added one option to disable the response body buffering for mirror request. Also introduced a 32MB cap for the response buffer, which can be changed by the runtime flag http.async_response_buffer_limit based on the product needs.

  • cares: Upgraded c-ares library to 1.20.1 and added fix to c-ares DNS implementation to additionally check for ARES_EREFUSED, ARES_ESERVFAIL and ARES_ENOTIMP status. Without this fix, DestroyChannelOnRefused and CustomResolverValidAfterChannelDestruction unit test will break.

  • datadog: Bumped the version of datadog to resolve a crashing bug in earlier versions of the library.

  • decompression: Fixed a bug where Envoy will go into an endless loop when using the brotli decompressor. If the input stream has redundant data, the decompressor will loop forever.

  • ext_authz: Added field validate_mutations, which, when set to true, adds header and query parameter mutation validation to the HTTP ext_authz filter. If an authz response contains invalid mutations, the filter responds to the downstream request with HTTP 500 Internal Server Error. If you use ext_authz with an untrusted side stream, it’s recommended you set this to true.

  • ext_authz: Handle append_action from external authorization service that was ignored.

  • ext_authz: Set the SNI value from the requested server name if it isn’t available on the connection/socket. This applies when include_tls_session is true. The requested server name is set on a connection when filters such as the TLS inspector are used.

  • ext_authz: Validate http service path_prefix, Valid HTTP service path_prefix configuration must start with /.

  • http: Fix BalsaParser resetting state too early, guarded by envoy.reloadable_features.http1_balsa_delay_reset which defaults to true.

  • http: Fix a crash when reloading the HTTP Connection Manager via ECDS.

  • http: Fixed a bug where additional cookie attributes are not sent properly to clients.

  • local_ratelimit: Fixed a bug where the local rate limit filter would crash when the enable_x_ratelimit_headers is set to DRAFT_VERSION_03 and a send local reply is triggered before the rate limit filter is executed.

  • lua: Fixed a bug where the user data will reference a dangling pointer to the Lua state and cause a crash.

  • oauth: The ID token cookie now expires at the same time the id token itself expires, instead of when the access token expires.

  • oauth2: Fixed a bug that would cause Envoy to crash when receiving an Oauth callback while the Oauth upstream is unhealthy (e.g. due to DNS issues).

  • outlier detection: Fixed successful_active_health_check_uneject_host. Before, a failed health check could uneject the host if the FAILED_ACTIVE_HC health flag had not been set.

  • quic: Applied 2 QUICHE patches for crash bugs in QuicSpdyStream OnDataAvailable() and OnInitialHeaderComplete().

  • quic: Fixed crash bug when QUIC downstream stream was read closed and then timed out.

  • tls: Fix a RELEASE_ASSERT when using auto_sni if the downstream request :authority was longer than 255 characters.

  • tracing: Added support to configure a static config resource detector for the OpenTelemetry tracer.

  • tracing: Fix an issue where span id is missing from OpenTelemetry access log entries.

  • udp: Fixed a bug that would cause Envoy to crash when updates to a pre-existing cluster were made (e.g. HostSet changes).

  • websocket: Only 101 is considered a successful response for websocket handshake for HTTP/1.1, and Envoy as a proxy will proxy the response header from upstream to downstream and then close the request if other status is received. This behavior can be reverted by envoy_reloadable_features_check_switch_protocol_websocket_handshake.

Removed config or runtime

Normally occurs at the end of the deprecation period

  • ext_authz: Removed envoy.reloadable_features.ext_authz_http_send_original_xff runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.enable_connect_udp_support runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.handle_uppercase_scheme runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.http_allow_partial_urls_in_referer runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.lowercase_scheme runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.proxy_status_upstream_request_timeout runtime flag and lagacy code paths.

  • http: Removed envoy.reloadable_features.stop_decode_metadata_on_local_reply runtime flag and legacy code paths.

  • http: Removed envoy.reloadable_features.use_cluster_cache_for_alt_protocols_filter runtime flag and lagacy code paths.

  • http: Removed envoy.restart_features.send_goaway_for_premature_rst_streams runtime flag and legacy code paths.

  • http2: Removed envoy.reloadable_features.http2_decode_metadata_with_quiche runtime flag and legacy code paths.

  • jwt: Removed envoy.reloadable_features.token_passed_entirely runtime flag and legacy code paths.

  • load_balancing: Removed envoy.reloadable_features.enable_zone_routing_different_zone_counts runtime flag and legacy code paths.

  • load_balancing: Removed envoy.reloadable_features.locality_routing_use_new_routing_logic runtime flag and legacy code paths.

  • oauth: Removed envoy.reloadable_features.hmac_base64_encoding_only runtime flag and legacy code paths.

  • oauth: Removed envoy.reloadable_features.oauth_make_token_cookie_httponly runtime flag and legacy code paths.

  • oauth: Removed envoy.reloadable_features.oauth_use_standard_max_age_value runtime flag and lagacy code paths.

  • oauth2: Removed envoy.reloadable_features.oauth_use_url_encoding runtime flag and legacy code paths.

  • outlier detection: Removed envoy.reloadable_features.check_mep_on_first_eject runtime flag and legacy code paths.

  • router: Removed envoy.reloadable_features.copy_response_code_to_downstream_stream_info runtime flag and legacy code paths.

  • tcp: Removed envoy.reloadable_features.detect_and_raise_rst_tcp_connection runtime flag and legacy code paths.

  • thrift: Removed envoy.reloadable_features.thrift_allow_negative_field_ids runtime flag and legacy code paths.

  • thrift: Removed envoy.reloadable_features.thrift_connection_draining runtime flag and legacy code paths.

  • tls: Removed envoy.reloadable_features.enable_intermediate_ca runtime flag and lagacy code paths.

  • tls: Removed envoy.reloadable_features.no_full_scan_certs_on_sni_mismatch runtime flag and lagacy code paths.

  • upstream: Removed envoy.reloadable_features.convert_legacy_lb_config runtime flag and legacy code paths.

New features

  • access_log: Added support for %UPSTREAM_HOST_NAME% for the upstream host identifier.

  • access_log: added new access_log command operators to retrieve upstream connection information change: %UPSTREAM_PEER_URI_SAN%, %UPSTREAM_PEER_IP_SAN%, %UPSTREAM_PEER_DNS_SAN%, %UPSTREAM_LOCAL_URI_SAN%, %UPSTREAM_LOCAL_DNS_SAN%, %UPSTREAM_LOCAL_IP_SAN%.

  • access_loggers: Added TRACE_ID access log formatter.

  • aws_lambda: The aws_lambda filter now supports the credentials parameter. This enables setting AWS credentials from the filter configuration.

  • cares: Added udp_max_queries option to limit the number of UDP queries.

  • dns_filter: Added support for wildcard resolution in inline_dns_table when DNS filter is working in server mode.

  • ext_authz: Added decoder_header_mutation_rules which allows you to configure what decoder header mutations are allowed from the ext_authz service as well as whether to fail the downstream request if disallowed mutations are requested.

  • ext_authz: Added enable_dynamic_metadata_ingestion, which allows ext_authz to be configured to ignore dynamic metadata in ext_authz responses.

  • ext_authz: Added disallowed_headers to specify headers that should never be sent to the external authentication service. Overrides allowed_headers if a header matches both.

  • ext_proc: Added support for observability mode which deprecates async_mode. If enabled, each part of the HTTP request or response specified by ProcessingMode is sent without waiting for the response from the ext_proc service. It is “Send and Go” mode that can be used by external processor to observe Envoy data and status.

  • formatter: Added formatters for METADATA(VIRTUAL_HOST).

  • grpc: Added support for flow control in Envoy gRPC side stream. This behavior can be disabled by setting the runtime flag envoy.reloadable_features.grpc_side_stream_flow_control to false.

  • healthcheck: Added support to healthcheck with ProxyProtocol in TCP Healthcheck by setting health_check_config.

  • hot_restart: Added new command-line flag --skip-hot-restart-parent-stats.

  • http: Added disable_shadow_host_suffix_append in request_mirror_policies for disabling appending of the -shadow suffix to the shadowed host/authority header.

  • http: Added field match_upstream, which, when set to true, will set the downstream request :scheme to match the upstream transport protocol.

  • jwt_authn: Added strip_failure_response to allow stripping the failure response details from the JWT authentication filter.

  • listener: Added bypass_overload_manager to bypass the overload manager for a listener. When set to true, the listener will not be subject to overload protection.

  • local_rate_limit: Added support for local cluster rate limit. If set, the token buckets of the local rate limit will be shared across all the Envoy instances in the local cluster.

  • matching: Added Filter State Input for matching HTTP input based on filter state objects.

  • oauth: Added disable_id_token_set_cookie to disable setting the ID Token cookie.

  • open_telemetry: Added formatters configuration to support extension formatter for the OpenTelemetry logger.

  • open_telemetry: Added stat_prefix configuration to support additional stat prefix for the OpenTelemetry logger.

  • outlier detection: Added always_eject_one_host to optionally override the max_ejection_percent.

  • proxy_protocol: Added field stat_prefix to the proxy protocol listener filter configuration, allowing for differentiating statistics when multiple proxy protocol listener filters are configured.

  • quic: Added DataSourceServerPreferredAddressConfig for cases when the control plane does not know the correct configuration for the server preferred address.

  • quic: Added new interface to QuicListenerFilter that is called on receiving the first packet.

  • quic: Added support for QUIC server preferred address when there is a DNAT between the client and Envoy. See new config.

  • quic: QUIC stream reset error code will be added to transport failure reason. This behavior can be reverted by setting the runtime flag envoy.reloadable_features.report_stream_reset_error_code to false.

  • rbac: The RBAC filter will now log the enforced rule to the dynamic metadata field enforced_effective_policy_id and the result to the dynamic metadata field enforced_engine_result. These are only populated if a non-shadow engine exists.

  • redis: Added support for xack, xadd, xautoclaim, xclaim, xdel, xlen, xpending, xrange, xrevrange, xtrim.

  • redis: Added support for inline commands.

  • redis: Added support for all Bloom 1.0.0 commands.

  • retry: Added reset-before-request retry policy.

  • routing: Added support in file datasource implementation to listen to file changes and dynamically update the response when watched_directory is configured in DataSource.

  • thrift: Added implementation of thrift to metadata HTTP filter.

  • tls: Added support to match against OtherName SAN-type under match_typed_subject_alt_names. An additional field oid is added to SubjectAltNameMatcher to support this change.

  • upstream: Added a new field to LocalityLbEndpoints, LocalityLbEndpoints.Metadata, that may be used for transport socket matching groups of endpoints.

  • wasm: Update WASM filter to support use as an upstream filter.

Deprecated