As of release 1.3.0, Envoy will follow a Breaking Change Policy.
The following features have been DEPRECATED and will be removed in the specified release cycle. A logged warning is expected for each deprecated item that is in deprecation window. Deprecated items below are listed in chronological order.
The previous behavior for upstream connection pool circuit breaking described here has been deprecated in favor of the new behavior described :ref:`here <arch_overview_circuit_break>`.
Access Logger, Listener Filter, HTTP Filter, Network Filter, Stats Sink, and Tracer names have been deprecated in favor of the extension name from the envoy build system. Disable the runtime feature "envoy.deprecated_features.allow_deprecated_extension_names" to disallow the deprecated names. Use of these extension names generates a log message and increments the "deprecated_feature_use" metric in stats.
Canonical Names
Deprecated Names
envoy.access_loggers.file
envoy.file_access_log
envoy.access_loggers.http_grpc
envoy.http_grpc_access_log
envoy.access_loggers.tcp_grpc
envoy.tcp_grpc_access_log
envoy.filters.http.buffer
envoy.buffer
envoy.filters.http.cors
envoy.cors
envoy.filters.http.csrf
envoy.csrf
envoy.filters.http.dynamo
envoy.http_dynamo_filter
envoy.filters.http.ext_authz
envoy.ext_authz
envoy.filters.http.fault
envoy.fault
envoy.filters.http.grpc_http1_bridge
envoy.grpc_http1_bridge
envoy.filters.http.grpc_json_transcoder
envoy.grpc_json_transcoder
envoy.filters.http.grpc_web
envoy.grpc_web
envoy.filters.http.gzip
envoy.gzip
envoy.filters.http.health_check
envoy.health_check
envoy.filters.http.ip_tagging
envoy.ip_tagging
envoy.filters.http.lua
envoy.lua
envoy.filters.http.ratelimit
envoy.rate_limit
envoy.filters.http.router
envoy.router
envoy.filters.http.squash
envoy.squash
envoy.filters.listener.http_inspector
envoy.listener.http_inspector
envoy.filters.listener.original_dst
envoy.listener.original_dst
envoy.filters.listener.original_src
envoy.listener.original_src
envoy.filters.listener.proxy_protocol
envoy.listener.proxy_protocol
envoy.filters.listener.tls_inspector
envoy.listener.tls_inspector
envoy.filters.network.client_ssl_auth
envoy.client_ssl_auth
envoy.filters.network.echo
envoy.echo
envoy.filters.network.ext_authz
envoy.ext_authz
envoy.filters.network.http_connection_manager
envoy.http_connection_manager
envoy.filters.network.mongo_proxy
envoy.mongo_proxy
envoy.filters.network.ratelimit
envoy.ratelimit
envoy.filters.network.redis_proxy
envoy.redis_proxy
envoy.filters.network.tcp_proxy
envoy.tcp_proxy
envoy.stat_sinks.dog_statsd
envoy.dog_statsd
envoy.stat_sinks.metrics_service
envoy.metrics_service
envoy.stat_sinks.statsd
envoy.statsd
envoy.tracers.dynamic_ot
envoy.dynamic.ot
envoy.tracers.lightstep
envoy.lightstep
envoy.tracers.zipkin
envoy.zipkin
Note
Some renamed filters produce metadata using their filter name as the metadata namespace:
- Mongo Proxy Filter
- Zookeeper Filter
The metadata generated by these filters may be consumed by the following extensions, whose configurations may need to be adjusted to use the new names.
- Access Loggers
- HTTP and Network Ext Authz filters
- HTTP and Network RBAC filters
- Tracers
The previous behavior of auto ignoring case in headers matching: :ref:`allowed_headers <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationRequest.allowed_headers>`, :ref:`allowed_upstream_headers <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_upstream_headers>`, and :ref:`allowed_client_headers <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_client_headers>` of HTTP-based ext_authz has been deprecated in favor of explicitly setting the :ref:`ignore_case <envoy_api_field_type.matcher.StringMatcher.ignore_case>` field.
The header_fields, custom_header_fields, and additional_headers fields for the route checker tool have been deprecated in favor of request_header_fields, response_header_fields, additional_request_headers, and additional_response_headers.
The content_length, content_type, disable_on_etag_header and remove_accept_encoding_header fields in :ref:`HTTP Gzip filter config <envoy_api_msg_config.filter.http.gzip.v2.Gzip>` have been deprecated in favor of compressor.
The statistics counter header_gzip in :ref:`HTTP Gzip filter <config_http_filters_gzip>` has been deprecated in favor of header_compressor_used.
- The request_headers_for_tags field in :ref:`HTTP connection manager <envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing>` has been deprecated in favor of the :ref:`custom_tags <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.tracing.custom_tags>` field.
- The verify_subject_alt_name field in :ref:`Certificate Validation Context <envoy_api_field_auth.CertificateValidationContext.verify_subject_alt_name>` has been deprecated in favor of the :ref:`match_subject_alt_names <envoy_api_field_auth.CertificateValidationContext.match_subject_alt_names>` field.
- The request_mirror_policy field in :ref:`RouteMatch <envoy_api_msg_route.RouteAction>` has been deprecated in favor of the request_mirror_policies field.
- The service_name field in :ref:`HTTP health checker <envoy_api_msg_core.HealthCheck.HttpHealthCheck>` has been deprecated in favor of the service_name_matcher field.
- The v2 xDS API is deprecated. It will be supported by Envoy until EOY 2020. See :ref:`api_supported_versions`.
- The ORIGINAL_DST_LB :ref:`load balancing policy <envoy_api_field_Cluster.lb_policy>` is deprecated, use CLUSTER_PROVIDED policy instead when configuring an :ref:`original destination cluster <envoy_api_field_Cluster.type>`.
- The regex field in :ref:`StringMatcher <envoy_api_msg_type.matcher.StringMatcher>` has been deprecated in favor of the safe_regex field.
- The regex field in :ref:`RouteMatch <envoy_api_msg_route.RouteMatch>` has been deprecated in favor of the safe_regex field.
- The allow_origin and allow_origin_regex fields in :ref:`CorsPolicy <envoy_api_msg_route.CorsPolicy>` have been deprecated in favor of the allow_origin_string_match field.
- The pattern and method fields in :ref:`VirtualCluster <envoy_api_msg_route.VirtualCluster>` have been deprecated in favor of the headers field.
- The regex_match field in :ref:`HeaderMatcher <envoy_api_msg_route.HeaderMatcher>` has been deprecated in favor of the safe_regex_match field.
- The value and regex fields in :ref:`QueryParameterMatcher <envoy_api_msg_route.QueryParameterMatcher>` has been deprecated in favor of the string_match and present_match fields.
- The :option:`--allow-unknown-fields` command-line option, use :option:`--allow-unknown-static-fields` instead.
- The use of HTTP_JSON_V1 :ref:`Zipkin collector endpoint version <envoy_api_field_config.trace.v2.ZipkinConfig.collector_endpoint_version>` or not explicitly specifying it is deprecated, use HTTP_JSON or HTTP_PROTO instead.
- The operation_name field in :ref:`HTTP connection manager <envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager>` has been deprecated in favor of the traffic_direction field in :ref:`Listener <envoy_api_msg_Listener>`. The latter takes priority if specified.
- The tls_context field in :ref:`Filter chain <envoy_api_field_listener.FilterChain.tls_context>` message and :ref:`Cluster <envoy_api_field_Cluster.tls_context>` message have been deprecated in favor of transport_socket with name envoy.transport_sockets.tls. The latter takes priority if specified.
- The use_http2 field in :ref:`HTTP health checker <envoy_api_msg_core.HealthCheck.HttpHealthCheck>` has been deprecated in favor of the codec_client_type field.
- The use of :ref:`gRPC bridge filter <config_http_filters_grpc_bridge>` for gRPC stats has been deprecated in favor of the dedicated :ref:`gRPC stats filter <config_http_filters_grpc_stats>`
- Ext_authz filter stats ok, error, denied, failure_mode_allowed in cluster.<route target cluster>.ext_authz. namespace is deprecated. Use http.<stat_prefix>.ext_authz. namespace to access same counters instead.
- Use of google.protobuf.Struct for extension opaque configs is deprecated. Use google.protobuf.Any instead or pack udpa.type.v1.TypedStruct in google.protobuf.Any.
- Use of :ref:`idle_timeout <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.idle_timeout>` is deprecated. Use :ref:`common_http_protocol_options <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.common_http_protocol_options>` instead.
- The --max-stats and --max-obj-name-len flags no longer has any effect.
- Use of :ref:`cluster <envoy_api_field_config.filter.network.redis_proxy.v2.RedisProxy.cluster>` in :ref:`redis_proxy.proto <envoy_api_file_envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto>` is deprecated. Set a :ref:`catch_all_route <envoy_api_field_config.filter.network.redis_proxy.v2.RedisProxy.PrefixRoutes.catch_all_route>` instead.
- Use of :ref:`catch_all_cluster <envoy_api_field_config.filter.network.redis_proxy.v2.RedisProxy.PrefixRoutes.catch_all_cluster>` in :ref:`redis_proxy.proto <envoy_api_file_envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto>` is deprecated. Set a :ref:`catch_all_route <envoy_api_field_config.filter.network.redis_proxy.v2.RedisProxy.PrefixRoutes.catch_all_route>` instead.
- Use of json based schema in router check tool tests. The tests should follow validation :repo:`schema<test/tools/router_check/validation.proto>`.
- Use of the v1 style route configuration for the :ref:`TCP proxy filter <config_network_filters_tcp_proxy>` is now fully replaced with listener :ref:`filter chain matching <envoy_api_msg_listener.FilterChainMatch>`. Use this instead.
- Use of :ref:`runtime <envoy_api_field_config.bootstrap.v2.Bootstrap.runtime>` in :ref:`Bootstrap <envoy_api_msg_config.bootstrap.v2.Bootstrap>`. Use :ref:`layered_runtime <envoy_api_field_config.bootstrap.v2.Bootstrap.layered_runtime>` instead.
- Specifying "deprecated_v1: true" in HTTP and network filter configuration to allow loading JSON configuration is now deprecated and will be removed in a following release. Update any custom filters to use protobuf configuration. A struct can be used for a mostly 1:1 conversion if needed. The envoy.deprecated_features.v1_filter_json_config runtime key can be used to temporarily enable this feature once the deprecation becomes fail by default.
- Use of use_alpha in :ref:`Ext-Authz Authorization Service <envoy_api_file_envoy/service/auth/v2/external_auth.proto>` is deprecated. It should be used for a short time, and only when transitioning from alpha to V2 release version.
- Use of enabled in CorsPolicy, found in :ref:`route.proto <envoy_api_file_envoy/api/v2/route/route.proto>`. Set the filter_enabled field instead.
- Use of the type field in the FaultDelay message (found in :ref:`fault.proto <envoy_api_file_envoy/config/filter/fault/v2/fault.proto>`) has been deprecated. It was never used and setting it has no effect. It will be removed in the following release.
- Order of execution of the network write filter chain has been reversed. Prior to this release cycle it was incorrect, see #4599. In the 1.9.0 release cycle we introduced bugfix_reverse_write_filter_order in lds.proto to temporarily support both old and new behaviors. Note this boolean field is deprecated.
- Order of execution of the HTTP encoder filter chain has been reversed. Prior to this release cycle it was incorrect, see #4599. In the 1.9.0 release cycle we introduced bugfix_reverse_encode_order in http_connection_manager.proto to temporarily support both old and new behaviors. Note this boolean field is deprecated.
- Use of the v1 REST_LEGACY ApiConfigSource is deprecated.
- Use of std::hash in the ring hash load balancer is deprecated.
- Use of rate_limit_service configuration in the bootstrap configuration is deprecated.
- Use of runtime_key in RequestMirrorPolicy, found in route.proto is deprecated. Set the runtime_fraction field instead.
- Use of buffer filter max_request_time is deprecated in favor of the request timeout found in HttpConnectionManager
- Use of the v1 API (including *.deprecated_v1 fields in the v2 API) is deprecated. See envoy-announce email.
- Use of the legacy ratelimit.proto is deprecated, in favor of the proto defined in date-plane-api Prior to 1.8.0, Envoy can use either proto to send client requests to a ratelimit server with the use of the use_data_plane_proto boolean flag in the ratelimit configuration. However, when using the deprecated client a warning is logged.
- Use of the --v2-config-only flag.
- Use of both use_websocket and websocket_config in route.proto is deprecated. Please use the new upgrade_configs in the HttpConnectionManager instead.
- Use of the integer percent field in FaultDelay and in FaultAbort is deprecated in favor of the new FractionalPercent based percentage field.
- Setting hosts via hosts field in Cluster is deprecated. Use load_assignment instead.
- Use of response_headers_to_* and request_headers_to_add are deprecated at the RouteAction level. Please use the configuration options at the Route level.
- Use of runtime in RouteMatch, found in route.proto. Set the runtime_fraction field instead.
- Use of the string user field in Authenticated in rbac.proto is deprecated in favor of the new StringMatcher based principal_name field.
- Admin mutations should be sent as POSTs rather than GETs. HTTP GETs will result in an error status code and will not have their intended effect. Prior to 1.7, GETs can be used for admin mutations, but a warning is logged.
- Rate limit service configuration via the cluster_name field is deprecated. Use grpc_service instead.
- gRPC service configuration via the cluster_names field in ApiConfigSource is deprecated. Use grpc_services instead. Prior to 1.7, a warning is logged.
- Redis health checker configuration via the redis_health_check field in HealthCheck is deprecated. Use custom_health_check with name envoy.health_checkers.redis instead. Prior to 1.7, redis_health_check can be used, but warning is logged.
- SAN is replaced by URI in the x-forwarded-client-cert header.
- The endpoint field in the http health check filter is deprecated in favor of the headers field where one can specify HeaderMatch objects to match on.
- The sni_domains field in the filter chain match was deprecated/renamed to server_names.
- DOWNSTREAM_ADDRESS log formatter is deprecated. Use DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT instead.
- CLIENT_IP header formatter is deprecated. Use DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT instead.
- 'use_original_dst' field in the v2 LDS API is deprecated. Use listener filters and filter chain matching instead.
- value and regex fields in the HeaderMatcher message is deprecated. Use the exact_match or regex_match oneof instead.
- The outlier detection ejections_total stats counter has been deprecated and not replaced. Monitor the individual ejections_detected_* counters for the detectors of interest, or ejections_enforced_total for the total number of ejections that actually occurred.
- The outlier detection ejections_consecutive_5xx stats counter has been deprecated in favour of ejections_detected_consecutive_5xx and ejections_enforced_consecutive_5xx.
- The outlier detection ejections_success_rate stats counter has been deprecated in favour of ejections_detected_success_rate and ejections_enforced_success_rate.
- Config option statsd_local_udp_port has been deprecated and has been replaced with statsd_udp_ip_address.
- HttpFilterConfigFactory filter API has been deprecated in favor of NamedHttpFilterConfigFactory.
- Config option http_codec_options has been deprecated and has been replaced with http2_settings.
- The following log macros have been deprecated: log_trace, log_debug, conn_log, conn_log_info, conn_log_debug, conn_log_trace, stream_log, stream_log_info, stream_log_debug, stream_log_trace. For replacements, please see logger.h.
- The connectionId() and ssl() callbacks of StreamFilterCallbacks have been deprecated and replaced with a more general connection() callback, which, when not returning a nullptr, can be used to get the connection id and SSL connection from the returned Connection object pointer.
- The protobuf stub gRPC support via Grpc::RpcChannelImpl is now replaced with Grpc::AsyncClientImpl. This no longer uses protoc generated stubs but instead utilizes C++ template generation of the RPC stubs. Grpc::AsyncClientImpl supports streaming, in addition to the previous unary, RPCs.
- The direction of network and HTTP filters in the configuration will be ignored from 1.4.0 and later removed from the configuration in the v2 APIs. Filter direction is now implied at the C++ type level. The type() methods on the NamedNetworkFilterConfigFactory and NamedHttpFilterConfigFactory interfaces have been removed to reflect this.