diff --git a/xds/src/test/java/io/grpc/xds/XdsClientImplDataTest.java b/xds/src/test/java/io/grpc/xds/XdsClientImplDataTest.java index 051d890aea..e66dfd7b62 100644 --- a/xds/src/test/java/io/grpc/xds/XdsClientImplDataTest.java +++ b/xds/src/test/java/io/grpc/xds/XdsClientImplDataTest.java @@ -802,6 +802,7 @@ public class XdsClientImplDataTest { } @Test + @SuppressWarnings("deprecation") public void parseRouteAction_withHashPolicies() { io.envoyproxy.envoy.config.route.v3.RouteAction proto = io.envoyproxy.envoy.config.route.v3.RouteAction.newBuilder() diff --git a/xds/third_party/envoy/import.sh b/xds/third_party/envoy/import.sh index 13813fb9f3..45ca0e0c06 100755 --- a/xds/third_party/envoy/import.sh +++ b/xds/third_party/envoy/import.sh @@ -18,7 +18,7 @@ set -e BRANCH=main # import VERSION from the google internal copybara_version.txt for Envoy -VERSION=2f99e0c9f83b6c91b42d215a148ed49ce0f174fd +VERSION=8affda4b71b05c9b272dbd031b7810418fb26211 GIT_REPO="https://github.com/envoyproxy/envoy.git" GIT_BASE_DIR=envoy SOURCE_PROTO_BASE_DIR=envoy/api @@ -26,6 +26,7 @@ TARGET_PROTO_BASE_DIR=src/main/proto # Sorted alphabetically. FILES=( envoy/admin/v3/config_dump.proto +envoy/admin/v3/config_dump_shared.proto envoy/annotations/deprecation.proto envoy/annotations/resource.proto envoy/api/v2/auth/cert.proto @@ -120,6 +121,7 @@ envoy/config/trace/v3/dynamic_ot.proto envoy/config/trace/v3/http_tracer.proto envoy/config/trace/v3/lightstep.proto envoy/config/trace/v3/opencensus.proto +envoy/config/trace/v3/opentelemetry.proto envoy/config/trace/v3/service.proto envoy/config/trace/v3/trace.proto envoy/config/trace/v3/zipkin.proto @@ -129,6 +131,8 @@ envoy/extensions/filters/http/fault/v3/fault.proto envoy/extensions/filters/http/rbac/v3/rbac.proto envoy/extensions/filters/http/router/v3/router.proto envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +envoy/extensions/load_balancing_policies/common/v3/common.proto envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto @@ -151,6 +155,7 @@ envoy/type/matcher/number.proto envoy/type/matcher/path.proto envoy/type/matcher/regex.proto envoy/type/matcher/string.proto +envoy/type/matcher/v3/filter_state.proto envoy/type/matcher/v3/metadata.proto envoy/type/matcher/v3/node.proto envoy/type/matcher/v3/number.proto diff --git a/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump.proto b/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump.proto index 336d5b13ee..8f5fa096e3 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.admin.v3; +import "envoy/admin/v3/config_dump_shared.proto"; import "envoy/config/bootstrap/v3/bootstrap.proto"; import "google/protobuf/any.proto"; @@ -18,31 +19,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: ConfigDump] -// Resource status from the view of a xDS client, which tells the synchronization -// status between the xDS client and the xDS server. -enum ClientResourceStatus { - // Resource status is not available/unknown. - UNKNOWN = 0; - - // Client requested this resource but hasn't received any update from management - // server. The client will not fail requests, but will queue them until update - // arrives or the client times out waiting for the resource. - REQUESTED = 1; - - // This resource has been requested by the client but has either not been - // delivered by the server or was previously delivered by the server and then - // subsequently removed from resources provided by the server. For more - // information, please refer to the :ref:`"Knowing When a Requested Resource - // Does Not Exist" ` section. - DOES_NOT_EXIST = 2; - - // Client received this resource and replied with ACK. - ACKED = 3; - - // Client received this resource and replied with NACK. - NACKED = 4; -} - // The :ref:`/config_dump ` admin endpoint uses this wrapper // message to maintain and serve arbitrary configuration information from any component in Envoy. message ConfigDump { @@ -54,15 +30,20 @@ message ConfigDump { // The following configurations are currently supported and will be dumped in the order given // below: // - // * *bootstrap*: :ref:`BootstrapConfigDump ` - // * *clusters*: :ref:`ClustersConfigDump ` - // * *endpoints*: :ref:`EndpointsConfigDump ` - // * *listeners*: :ref:`ListenersConfigDump ` - // * *scoped_routes*: :ref:`ScopedRoutesConfigDump ` - // * *routes*: :ref:`RoutesConfigDump ` - // * *secrets*: :ref:`SecretsConfigDump ` + // * ``bootstrap``: :ref:`BootstrapConfigDump ` + // * ``clusters``: :ref:`ClustersConfigDump ` + // * ``ecds_filter_http``: :ref:`EcdsConfigDump ` + // * ``ecds_filter_tcp_listener``: :ref:`EcdsConfigDump ` + // * ``endpoints``: :ref:`EndpointsConfigDump ` + // * ``listeners``: :ref:`ListenersConfigDump ` + // * ``scoped_routes``: :ref:`ScopedRoutesConfigDump ` + // * ``routes``: :ref:`RoutesConfigDump ` + // * ``secrets``: :ref:`SecretsConfigDump ` // - // EDS Configuration will only be dumped by using parameter `?include_eds` + // EDS Configuration will only be dumped by using parameter ``?include_eds`` + // + // Currently ECDS is supported in HTTP and listener filters. Note, ECDS configuration for + // either HTTP or listener filter will only be dumped if it is actually configured. // // You can filter output with the resource and mask query parameters. // See :ref:`/config_dump?resource={} `, @@ -72,25 +53,6 @@ message ConfigDump { repeated google.protobuf.Any configs = 1; } -message UpdateFailureState { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.UpdateFailureState"; - - // What the component configuration would have been if the update had succeeded. - // This field may not be populated by xDS clients due to storage overhead. - google.protobuf.Any failed_configuration = 1; - - // Time of the latest failed update attempt. - google.protobuf.Timestamp last_update_attempt = 2; - - // Details about the last failed update attempt. - string details = 3; - - // This is the version of the rejected resource. - // [#not-implemented-hide:] - string version_info = 4; -} - // This message describes the bootstrap configuration that Envoy was started with. This includes // any CLI overrides that were merged. Bootstrap configuration information can be used to recreate // the static portions of an Envoy configuration by reusing the output as the bootstrap @@ -105,273 +67,6 @@ message BootstrapConfigDump { google.protobuf.Timestamp last_updated = 2; } -// Envoy's listener manager fills this message with all currently known listeners. Listener -// configuration information can be used to recreate an Envoy configuration by populating all -// listeners as static listeners or by returning them in a LDS response. -message ListenersConfigDump { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ListenersConfigDump"; - - // Describes a statically loaded listener. - message StaticListener { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ListenersConfigDump.StaticListener"; - - // The listener config. - google.protobuf.Any listener = 1; - - // The timestamp when the Listener was last successfully updated. - google.protobuf.Timestamp last_updated = 2; - } - - message DynamicListenerState { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ListenersConfigDump.DynamicListenerState"; - - // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` field at the time - // that the listener was loaded. In the future, discrete per-listener versions may be supported - // by the API. - string version_info = 1; - - // The listener config. - google.protobuf.Any listener = 2; - - // The timestamp when the Listener was last successfully updated. - google.protobuf.Timestamp last_updated = 3; - } - - // Describes a dynamically loaded listener via the LDS API. - // [#next-free-field: 7] - message DynamicListener { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ListenersConfigDump.DynamicListener"; - - // The name or unique id of this listener, pulled from the DynamicListenerState config. - string name = 1; - - // The listener state for any active listener by this name. - // These are listeners that are available to service data plane traffic. - DynamicListenerState active_state = 2; - - // The listener state for any warming listener by this name. - // These are listeners that are currently undergoing warming in preparation to service data - // plane traffic. Note that if attempting to recreate an Envoy configuration from a - // configuration dump, the warming listeners should generally be discarded. - DynamicListenerState warming_state = 3; - - // The listener state for any draining listener by this name. - // These are listeners that are currently undergoing draining in preparation to stop servicing - // data plane traffic. Note that if attempting to recreate an Envoy configuration from a - // configuration dump, the draining listeners should generally be discarded. - DynamicListenerState draining_state = 4; - - // Set if the last update failed, cleared after the next successful update. - // The *error_state* field contains the rejected version of this particular - // resource along with the reason and timestamp. For successfully updated or - // acknowledged resource, this field should be empty. - UpdateFailureState error_state = 5; - - // The client status of this resource. - // [#not-implemented-hide:] - ClientResourceStatus client_status = 6; - } - - // This is the :ref:`version_info ` in the - // last processed LDS discovery response. If there are only static bootstrap listeners, this field - // will be "". - string version_info = 1; - - // The statically loaded listener configs. - repeated StaticListener static_listeners = 2; - - // State for any warming, active, or draining listeners. - repeated DynamicListener dynamic_listeners = 3; -} - -// Envoy's cluster manager fills this message with all currently known clusters. Cluster -// configuration information can be used to recreate an Envoy configuration by populating all -// clusters as static clusters or by returning them in a CDS response. -message ClustersConfigDump { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ClustersConfigDump"; - - // Describes a statically loaded cluster. - message StaticCluster { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ClustersConfigDump.StaticCluster"; - - // The cluster config. - google.protobuf.Any cluster = 1; - - // The timestamp when the Cluster was last updated. - google.protobuf.Timestamp last_updated = 2; - } - - // Describes a dynamically loaded cluster via the CDS API. - // [#next-free-field: 6] - message DynamicCluster { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ClustersConfigDump.DynamicCluster"; - - // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` field at the time - // that the cluster was loaded. In the future, discrete per-cluster versions may be supported by - // the API. - string version_info = 1; - - // The cluster config. - google.protobuf.Any cluster = 2; - - // The timestamp when the Cluster was last updated. - google.protobuf.Timestamp last_updated = 3; - - // Set if the last update failed, cleared after the next successful update. - // The *error_state* field contains the rejected version of this particular - // resource along with the reason and timestamp. For successfully updated or - // acknowledged resource, this field should be empty. - // [#not-implemented-hide:] - UpdateFailureState error_state = 4; - - // The client status of this resource. - // [#not-implemented-hide:] - ClientResourceStatus client_status = 5; - } - - // This is the :ref:`version_info ` in the - // last processed CDS discovery response. If there are only static bootstrap clusters, this field - // will be "". - string version_info = 1; - - // The statically loaded cluster configs. - repeated StaticCluster static_clusters = 2; - - // The dynamically loaded active clusters. These are clusters that are available to service - // data plane traffic. - repeated DynamicCluster dynamic_active_clusters = 3; - - // The dynamically loaded warming clusters. These are clusters that are currently undergoing - // warming in preparation to service data plane traffic. Note that if attempting to recreate an - // Envoy configuration from a configuration dump, the warming clusters should generally be - // discarded. - repeated DynamicCluster dynamic_warming_clusters = 4; -} - -// Envoy's RDS implementation fills this message with all currently loaded routes, as described by -// their RouteConfiguration objects. Static routes that are either defined in the bootstrap configuration -// or defined inline while configuring listeners are separated from those configured dynamically via RDS. -// Route configuration information can be used to recreate an Envoy configuration by populating all routes -// as static routes or by returning them in RDS responses. -message RoutesConfigDump { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.RoutesConfigDump"; - - message StaticRouteConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.RoutesConfigDump.StaticRouteConfig"; - - // The route config. - google.protobuf.Any route_config = 1; - - // The timestamp when the Route was last updated. - google.protobuf.Timestamp last_updated = 2; - } - - // [#next-free-field: 6] - message DynamicRouteConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.RoutesConfigDump.DynamicRouteConfig"; - - // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` field at the time that - // the route configuration was loaded. - string version_info = 1; - - // The route config. - google.protobuf.Any route_config = 2; - - // The timestamp when the Route was last updated. - google.protobuf.Timestamp last_updated = 3; - - // Set if the last update failed, cleared after the next successful update. - // The *error_state* field contains the rejected version of this particular - // resource along with the reason and timestamp. For successfully updated or - // acknowledged resource, this field should be empty. - // [#not-implemented-hide:] - UpdateFailureState error_state = 4; - - // The client status of this resource. - // [#not-implemented-hide:] - ClientResourceStatus client_status = 5; - } - - // The statically loaded route configs. - repeated StaticRouteConfig static_route_configs = 2; - - // The dynamically loaded route configs. - repeated DynamicRouteConfig dynamic_route_configs = 3; -} - -// Envoy's scoped RDS implementation fills this message with all currently loaded route -// configuration scopes (defined via ScopedRouteConfigurationsSet protos). This message lists both -// the scopes defined inline with the higher order object (i.e., the HttpConnectionManager) and the -// dynamically obtained scopes via the SRDS API. -message ScopedRoutesConfigDump { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ScopedRoutesConfigDump"; - - message InlineScopedRouteConfigs { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ScopedRoutesConfigDump.InlineScopedRouteConfigs"; - - // The name assigned to the scoped route configurations. - string name = 1; - - // The scoped route configurations. - repeated google.protobuf.Any scoped_route_configs = 2; - - // The timestamp when the scoped route config set was last updated. - google.protobuf.Timestamp last_updated = 3; - } - - // [#next-free-field: 7] - message DynamicScopedRouteConfigs { - option (udpa.annotations.versioning).previous_message_type = - "envoy.admin.v2alpha.ScopedRoutesConfigDump.DynamicScopedRouteConfigs"; - - // The name assigned to the scoped route configurations. - string name = 1; - - // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` field at the time that - // the scoped routes configuration was loaded. - string version_info = 2; - - // The scoped route configurations. - repeated google.protobuf.Any scoped_route_configs = 3; - - // The timestamp when the scoped route config set was last updated. - google.protobuf.Timestamp last_updated = 4; - - // Set if the last update failed, cleared after the next successful update. - // The *error_state* field contains the rejected version of this particular - // resource along with the reason and timestamp. For successfully updated or - // acknowledged resource, this field should be empty. - // [#not-implemented-hide:] - UpdateFailureState error_state = 5; - - // The client status of this resource. - // [#not-implemented-hide:] - ClientResourceStatus client_status = 6; - } - - // The statically loaded scoped route configs. - repeated InlineScopedRouteConfigs inline_scoped_route_configs = 1; - - // The dynamically loaded scoped route configs. - repeated DynamicScopedRouteConfigs dynamic_scoped_route_configs = 2; -} - // Envoys SDS implementation fills this message with all secrets fetched dynamically via SDS. message SecretsConfigDump { option (udpa.annotations.versioning).previous_message_type = @@ -437,47 +132,3 @@ message SecretsConfigDump { // warming in preparation to service clusters or listeners. repeated DynamicSecret dynamic_warming_secrets = 3; } - -// Envoy's admin fill this message with all currently known endpoints. Endpoint -// configuration information can be used to recreate an Envoy configuration by populating all -// endpoints as static endpoints or by returning them in an EDS response. -message EndpointsConfigDump { - message StaticEndpointConfig { - // The endpoint config. - google.protobuf.Any endpoint_config = 1; - - // [#not-implemented-hide:] The timestamp when the Endpoint was last updated. - google.protobuf.Timestamp last_updated = 2; - } - - // [#next-free-field: 6] - message DynamicEndpointConfig { - // [#not-implemented-hide:] This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` field at the time that - // the endpoint configuration was loaded. - string version_info = 1; - - // The endpoint config. - google.protobuf.Any endpoint_config = 2; - - // [#not-implemented-hide:] The timestamp when the Endpoint was last updated. - google.protobuf.Timestamp last_updated = 3; - - // Set if the last update failed, cleared after the next successful update. - // The *error_state* field contains the rejected version of this particular - // resource along with the reason and timestamp. For successfully updated or - // acknowledged resource, this field should be empty. - // [#not-implemented-hide:] - UpdateFailureState error_state = 4; - - // The client status of this resource. - // [#not-implemented-hide:] - ClientResourceStatus client_status = 5; - } - - // The statically loaded endpoint configs. - repeated StaticEndpointConfig static_endpoint_configs = 2; - - // The dynamically loaded endpoint configs. - repeated DynamicEndpointConfig dynamic_endpoint_configs = 3; -} diff --git a/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump_shared.proto b/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump_shared.proto new file mode 100644 index 0000000000..8de77e18e1 --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/admin/v3/config_dump_shared.proto @@ -0,0 +1,412 @@ +syntax = "proto3"; + +package envoy.admin.v3; + +import "google/protobuf/any.proto"; +import "google/protobuf/timestamp.proto"; + +import "udpa/annotations/status.proto"; +import "udpa/annotations/versioning.proto"; + +option java_package = "io.envoyproxy.envoy.admin.v3"; +option java_outer_classname = "ConfigDumpSharedProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/admin/v3;adminv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: ConfigDump] + +// Resource status from the view of a xDS client, which tells the synchronization +// status between the xDS client and the xDS server. +enum ClientResourceStatus { + // Resource status is not available/unknown. + UNKNOWN = 0; + + // Client requested this resource but hasn't received any update from management + // server. The client will not fail requests, but will queue them until update + // arrives or the client times out waiting for the resource. + REQUESTED = 1; + + // This resource has been requested by the client but has either not been + // delivered by the server or was previously delivered by the server and then + // subsequently removed from resources provided by the server. For more + // information, please refer to the :ref:`"Knowing When a Requested Resource + // Does Not Exist" ` section. + DOES_NOT_EXIST = 2; + + // Client received this resource and replied with ACK. + ACKED = 3; + + // Client received this resource and replied with NACK. + NACKED = 4; +} + +message UpdateFailureState { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.UpdateFailureState"; + + // What the component configuration would have been if the update had succeeded. + // This field may not be populated by xDS clients due to storage overhead. + google.protobuf.Any failed_configuration = 1; + + // Time of the latest failed update attempt. + google.protobuf.Timestamp last_update_attempt = 2; + + // Details about the last failed update attempt. + string details = 3; + + // This is the version of the rejected resource. + // [#not-implemented-hide:] + string version_info = 4; +} + +// Envoy's listener manager fills this message with all currently known listeners. Listener +// configuration information can be used to recreate an Envoy configuration by populating all +// listeners as static listeners or by returning them in a LDS response. +message ListenersConfigDump { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ListenersConfigDump"; + + // Describes a statically loaded listener. + message StaticListener { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ListenersConfigDump.StaticListener"; + + // The listener config. + google.protobuf.Any listener = 1; + + // The timestamp when the Listener was last successfully updated. + google.protobuf.Timestamp last_updated = 2; + } + + message DynamicListenerState { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ListenersConfigDump.DynamicListenerState"; + + // This is the per-resource version information. This version is currently taken from the + // :ref:`version_info ` field at the time + // that the listener was loaded. In the future, discrete per-listener versions may be supported + // by the API. + string version_info = 1; + + // The listener config. + google.protobuf.Any listener = 2; + + // The timestamp when the Listener was last successfully updated. + google.protobuf.Timestamp last_updated = 3; + } + + // Describes a dynamically loaded listener via the LDS API. + // [#next-free-field: 7] + message DynamicListener { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ListenersConfigDump.DynamicListener"; + + // The name or unique id of this listener, pulled from the DynamicListenerState config. + string name = 1; + + // The listener state for any active listener by this name. + // These are listeners that are available to service data plane traffic. + DynamicListenerState active_state = 2; + + // The listener state for any warming listener by this name. + // These are listeners that are currently undergoing warming in preparation to service data + // plane traffic. Note that if attempting to recreate an Envoy configuration from a + // configuration dump, the warming listeners should generally be discarded. + DynamicListenerState warming_state = 3; + + // The listener state for any draining listener by this name. + // These are listeners that are currently undergoing draining in preparation to stop servicing + // data plane traffic. Note that if attempting to recreate an Envoy configuration from a + // configuration dump, the draining listeners should generally be discarded. + DynamicListenerState draining_state = 4; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this particular + // resource along with the reason and timestamp. For successfully updated or + // acknowledged resource, this field should be empty. + UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; + } + + // This is the :ref:`version_info ` in the + // last processed LDS discovery response. If there are only static bootstrap listeners, this field + // will be "". + string version_info = 1; + + // The statically loaded listener configs. + repeated StaticListener static_listeners = 2; + + // State for any warming, active, or draining listeners. + repeated DynamicListener dynamic_listeners = 3; +} + +// Envoy's cluster manager fills this message with all currently known clusters. Cluster +// configuration information can be used to recreate an Envoy configuration by populating all +// clusters as static clusters or by returning them in a CDS response. +message ClustersConfigDump { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ClustersConfigDump"; + + // Describes a statically loaded cluster. + message StaticCluster { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ClustersConfigDump.StaticCluster"; + + // The cluster config. + google.protobuf.Any cluster = 1; + + // The timestamp when the Cluster was last updated. + google.protobuf.Timestamp last_updated = 2; + } + + // Describes a dynamically loaded cluster via the CDS API. + // [#next-free-field: 6] + message DynamicCluster { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ClustersConfigDump.DynamicCluster"; + + // This is the per-resource version information. This version is currently taken from the + // :ref:`version_info ` field at the time + // that the cluster was loaded. In the future, discrete per-cluster versions may be supported by + // the API. + string version_info = 1; + + // The cluster config. + google.protobuf.Any cluster = 2; + + // The timestamp when the Cluster was last updated. + google.protobuf.Timestamp last_updated = 3; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this particular + // resource along with the reason and timestamp. For successfully updated or + // acknowledged resource, this field should be empty. + // [#not-implemented-hide:] + UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; + } + + // This is the :ref:`version_info ` in the + // last processed CDS discovery response. If there are only static bootstrap clusters, this field + // will be "". + string version_info = 1; + + // The statically loaded cluster configs. + repeated StaticCluster static_clusters = 2; + + // The dynamically loaded active clusters. These are clusters that are available to service + // data plane traffic. + repeated DynamicCluster dynamic_active_clusters = 3; + + // The dynamically loaded warming clusters. These are clusters that are currently undergoing + // warming in preparation to service data plane traffic. Note that if attempting to recreate an + // Envoy configuration from a configuration dump, the warming clusters should generally be + // discarded. + repeated DynamicCluster dynamic_warming_clusters = 4; +} + +// Envoy's RDS implementation fills this message with all currently loaded routes, as described by +// their RouteConfiguration objects. Static routes that are either defined in the bootstrap configuration +// or defined inline while configuring listeners are separated from those configured dynamically via RDS. +// Route configuration information can be used to recreate an Envoy configuration by populating all routes +// as static routes or by returning them in RDS responses. +message RoutesConfigDump { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.RoutesConfigDump"; + + message StaticRouteConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.RoutesConfigDump.StaticRouteConfig"; + + // The route config. + google.protobuf.Any route_config = 1; + + // The timestamp when the Route was last updated. + google.protobuf.Timestamp last_updated = 2; + } + + // [#next-free-field: 6] + message DynamicRouteConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.RoutesConfigDump.DynamicRouteConfig"; + + // This is the per-resource version information. This version is currently taken from the + // :ref:`version_info ` field at the time that + // the route configuration was loaded. + string version_info = 1; + + // The route config. + google.protobuf.Any route_config = 2; + + // The timestamp when the Route was last updated. + google.protobuf.Timestamp last_updated = 3; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this particular + // resource along with the reason and timestamp. For successfully updated or + // acknowledged resource, this field should be empty. + // [#not-implemented-hide:] + UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; + } + + // The statically loaded route configs. + repeated StaticRouteConfig static_route_configs = 2; + + // The dynamically loaded route configs. + repeated DynamicRouteConfig dynamic_route_configs = 3; +} + +// Envoy's scoped RDS implementation fills this message with all currently loaded route +// configuration scopes (defined via ScopedRouteConfigurationsSet protos). This message lists both +// the scopes defined inline with the higher order object (i.e., the HttpConnectionManager) and the +// dynamically obtained scopes via the SRDS API. +message ScopedRoutesConfigDump { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ScopedRoutesConfigDump"; + + message InlineScopedRouteConfigs { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ScopedRoutesConfigDump.InlineScopedRouteConfigs"; + + // The name assigned to the scoped route configurations. + string name = 1; + + // The scoped route configurations. + repeated google.protobuf.Any scoped_route_configs = 2; + + // The timestamp when the scoped route config set was last updated. + google.protobuf.Timestamp last_updated = 3; + } + + // [#next-free-field: 7] + message DynamicScopedRouteConfigs { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.ScopedRoutesConfigDump.DynamicScopedRouteConfigs"; + + // The name assigned to the scoped route configurations. + string name = 1; + + // This is the per-resource version information. This version is currently taken from the + // :ref:`version_info ` field at the time that + // the scoped routes configuration was loaded. + string version_info = 2; + + // The scoped route configurations. + repeated google.protobuf.Any scoped_route_configs = 3; + + // The timestamp when the scoped route config set was last updated. + google.protobuf.Timestamp last_updated = 4; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this particular + // resource along with the reason and timestamp. For successfully updated or + // acknowledged resource, this field should be empty. + // [#not-implemented-hide:] + UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; + } + + // The statically loaded scoped route configs. + repeated InlineScopedRouteConfigs inline_scoped_route_configs = 1; + + // The dynamically loaded scoped route configs. + repeated DynamicScopedRouteConfigs dynamic_scoped_route_configs = 2; +} + +// Envoy's admin fill this message with all currently known endpoints. Endpoint +// configuration information can be used to recreate an Envoy configuration by populating all +// endpoints as static endpoints or by returning them in an EDS response. +message EndpointsConfigDump { + message StaticEndpointConfig { + // The endpoint config. + google.protobuf.Any endpoint_config = 1; + + // [#not-implemented-hide:] The timestamp when the Endpoint was last updated. + google.protobuf.Timestamp last_updated = 2; + } + + // [#next-free-field: 6] + message DynamicEndpointConfig { + // [#not-implemented-hide:] This is the per-resource version information. This version is currently taken from the + // :ref:`version_info ` field at the time that + // the endpoint configuration was loaded. + string version_info = 1; + + // The endpoint config. + google.protobuf.Any endpoint_config = 2; + + // [#not-implemented-hide:] The timestamp when the Endpoint was last updated. + google.protobuf.Timestamp last_updated = 3; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this particular + // resource along with the reason and timestamp. For successfully updated or + // acknowledged resource, this field should be empty. + // [#not-implemented-hide:] + UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; + } + + // The statically loaded endpoint configs. + repeated StaticEndpointConfig static_endpoint_configs = 2; + + // The dynamically loaded endpoint configs. + repeated DynamicEndpointConfig dynamic_endpoint_configs = 3; +} + +// Envoy's ECDS service fills this message with all currently extension +// configuration. Extension configuration information can be used to recreate +// an Envoy ECDS listener and HTTP filters as static filters or by returning +// them in ECDS response. +message EcdsConfigDump { + option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.EcdsConfigDump"; + + // [#next-free-field: 6] + message EcdsFilterConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v2alpha.EcdsConfigDump.EcdsFilterConfig"; + + // This is the per-resource version information. This version is currently + // taken from the :ref:`version_info + // ` + // field at the time that the ECDS filter was loaded. + string version_info = 1; + + // The ECDS filter config. + google.protobuf.Any ecds_filter = 2; + + // The timestamp when the ECDS filter was last updated. + google.protobuf.Timestamp last_updated = 3; + + // Set if the last update failed, cleared after the next successful update. + // The ``error_state`` field contains the rejected version of this + // particular resource along with the reason and timestamp. For successfully + // updated or acknowledged resource, this field should be empty. + // [#not-implemented-hide:] + UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; + } + + // The ECDS filter configs. + repeated EcdsFilterConfig ecds_filters = 1; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/api/v2/cluster/outlier_detection.proto b/xds/third_party/envoy/src/main/proto/envoy/api/v2/cluster/outlier_detection.proto index ec8c6ee731..4a86160c71 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/api/v2/cluster/outlier_detection.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/api/v2/cluster/outlier_detection.proto @@ -24,9 +24,9 @@ option (udpa.annotations.file_status).package_version_status = FROZEN; // more information on outlier detection. // [#next-free-field: 21] message OutlierDetection { - // The number of consecutive 5xx responses or local origin errors that are mapped - // to 5xx error codes before a consecutive 5xx ejection - // occurs. Defaults to 5. + // The number of consecutive server-side error responses (for HTTP traffic, + // 5xx responses; for TCP traffic, connection failures; for Redis, failure to + // respond PONG; etc.) before a consecutive 5xx ejection occurs. Defaults to 5. google.protobuf.UInt32Value consecutive_5xx = 1; // The time interval between ejection analysis sweeps. This can result in diff --git a/xds/third_party/envoy/src/main/proto/envoy/api/v2/core/grpc_service.proto b/xds/third_party/envoy/src/main/proto/envoy/api/v2/core/grpc_service.proto index faafb7f0f7..027a45e4c5 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/api/v2/core/grpc_service.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/api/v2/core/grpc_service.proto @@ -100,7 +100,7 @@ message GrpcService { message StsService { // URI of the token exchange service that handles token exchange requests. // [#comment:TODO(asraa): Add URI validation when implemented. Tracked by - // https://github.com/envoyproxy/protoc-gen-validate/issues/303] + // https://github.com/bufbuild/protoc-gen-validate/issues/303] string token_exchange_service_uri = 1; // Location of the target service or resource where the client diff --git a/xds/third_party/envoy/src/main/proto/envoy/api/v2/route/route_components.proto b/xds/third_party/envoy/src/main/proto/envoy/api/v2/route/route_components.proto index 062e73231d..5889a8309b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/api/v2/route/route_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/api/v2/route/route_components.proto @@ -301,7 +301,7 @@ message WeightedCluster { // An integer between 0 and :ref:`total_weight // `. When a request matches the route, // the choice of an upstream cluster is determined by its weight. The sum of weights across all - // entries in the clusters array must add up to the total_weight, which defaults to 100. + // entries in the clusters array must add up to the total_weight, if total_weight is greater than 0. google.protobuf.UInt32Value weight = 2; // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in @@ -859,8 +859,9 @@ message RouteAction { // Indicates that during forwarding, the host header will be swapped with // the hostname of the upstream host chosen by the cluster manager. This // option is applicable only when the destination cluster for a route is of - // type *strict_dns* or *logical_dns*. Setting this to true with other cluster - // types has no effect. + // type ``STRICT_DNS``, ``LOGICAL_DNS`` or ``STATIC``. For ``STATIC`` clusters, the + // hostname attribute of the endpoint must be configured. Setting this to true + // with other cluster types has no effect. google.protobuf.BoolValue auto_host_rewrite = 7; // Indicates that during forwarding, the host header will be swapped with the content of given diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/accesslog/v3/accesslog.proto b/xds/third_party/envoy/src/main/proto/envoy/config/accesslog/v3/accesslog.proto index b851949692..5f7f004478 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/accesslog/v3/accesslog.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/accesslog/v3/accesslog.proto @@ -151,7 +151,7 @@ message RuntimeFilter { "envoy.config.filter.accesslog.v2.RuntimeFilter"; // Runtime key to get an optional overridden numerator for use in the - // *percent_sampled* field. If found in runtime, this value will replace the + // ``percent_sampled`` field. If found in runtime, this value will replace the // default numerator. string runtime_key = 1 [(validate.rules).string = {min_len: 1}]; @@ -165,9 +165,9 @@ message RuntimeFilter { // is present, the filter will consistently sample across multiple hosts based // on the runtime key value and the value extracted from // :ref:`x-request-id`. If it is - // missing, or *use_independent_randomness* is set to true, the filter will + // missing, or ``use_independent_randomness`` is set to true, the filter will // randomly sample based on the runtime key value alone. - // *use_independent_randomness* can be used for logging kill switches within + // ``use_independent_randomness`` can be used for logging kill switches within // complex nested :ref:`AndFilter // ` and :ref:`OrFilter // ` blocks that are easier to diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto b/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto index bde4d5c396..6b230536cd 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto @@ -41,7 +41,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` for more detail. // Bootstrap :ref:`configuration overview `. -// [#next-free-field: 34] +// [#next-free-field: 38] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Bootstrap"; @@ -169,7 +169,7 @@ message Bootstrap { // Optional duration between flushes to configured stats sinks. For // performance reasons Envoy latches counters and only flushes counters and // gauges at a periodic interval. If not specified the default is 5000ms (5 - // seconds). Only one of `stats_flush_interval` or `stats_flush_on_admin` + // seconds). Only one of ``stats_flush_interval`` or ``stats_flush_on_admin`` // can be set. // Duration must be at least 1ms and at most 5 min. google.protobuf.Duration stats_flush_interval = 7 [ @@ -182,14 +182,14 @@ message Bootstrap { oneof stats_flush { // Flush stats to sinks only when queried for on the admin interface. If set, - // a flush timer is not created. Only one of `stats_flush_on_admin` or - // `stats_flush_interval` can be set. + // a flush timer is not created. Only one of ``stats_flush_on_admin`` or + // ``stats_flush_interval`` can be set. bool stats_flush_on_admin = 29 [(validate.rules).bool = {const: true}]; } // Optional watchdog configuration. // This is for a single watchdog configuration for the entire system. - // Deprecated in favor of *watchdogs* which has finer granularity. + // Deprecated in favor of ``watchdogs`` which has finer granularity. Watchdog watchdog = 8 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -249,7 +249,7 @@ message Bootstrap { // when :ref:`dns_resolvers ` and // :ref:`use_tcp_for_dns_lookups ` are // specified. - // This field is deprecated in favor of *dns_resolution_config* + // This field is deprecated in favor of ``dns_resolution_config`` // which aggregates all of the DNS resolver configuration in a single message. bool use_tcp_for_dns_lookups = 20 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -267,12 +267,12 @@ message Bootstrap { // or any other DNS resolver types and the related parameters. // For example, an object of // :ref:`CaresDnsResolverConfig ` - // can be packed into this *typed_dns_resolver_config*. This configuration replaces the + // can be packed into this ``typed_dns_resolver_config``. This configuration replaces the // :ref:`dns_resolution_config ` // configuration. - // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists, - // when *typed_dns_resolver_config* is in place, Envoy will use it and ignore *dns_resolution_config*. - // When *typed_dns_resolver_config* is missing, the default behavior is in place. + // During the transition period when both ``dns_resolution_config`` and ``typed_dns_resolver_config`` exists, + // when ``typed_dns_resolver_config`` is in place, Envoy will use it and ignore ``dns_resolution_config``. + // When ``typed_dns_resolver_config`` is missing, the default behavior is in place. // [#extension-category: envoy.network.dns_resolver] core.v3.TypedExtensionConfig typed_dns_resolver_config = 31; @@ -289,18 +289,18 @@ message Bootstrap { // xdstp:// URL authority resolution. The algorithm is as // follows: // 1. The authority field is taken from the xdstp:// URL, call - // this *resource_authority*. - // 2. *resource_authority* is compared against the authorities in any peer - // *ConfigSource*. The peer *ConfigSource* is the configuration source + // this ``resource_authority``. + // 2. ``resource_authority`` is compared against the authorities in any peer + // ``ConfigSource``. The peer ``ConfigSource`` is the configuration source // message which would have been used unconditionally for resolution // with opaque resource names. If there is a match with an authority, the - // peer *ConfigSource* message is used. - // 3. *resource_authority* is compared sequentially with the authorities in - // each configuration source in *config_sources*. The first *ConfigSource* + // peer ``ConfigSource`` message is used. + // 3. ``resource_authority`` is compared sequentially with the authorities in + // each configuration source in ``config_sources``. The first ``ConfigSource`` // to match wins. // 4. As a fallback, if no configuration source matches, then - // *default_config_source* is used. - // 5. If *default_config_source* is not specified, resolution fails. + // ``default_config_source`` is used. + // 5. If ``default_config_source`` is not specified, resolution fails. // [#not-implemented-hide:] repeated core.v3.ConfigSource config_sources = 22; @@ -330,6 +330,36 @@ message Bootstrap { // Optional path to a file with performance tracing data created by "Perfetto" SDK in binary // ProtoBuf format. The default value is "envoy.pftrace". string perf_tracing_file_path = 33; + + // Optional overriding of default regex engine. + // If the value is not specified, Google RE2 will be used by default. + // [#extension-category: envoy.regex_engines] + core.v3.TypedExtensionConfig default_regex_engine = 34; + + // Optional XdsResourcesDelegate configuration, which allows plugging custom logic into both + // fetch and load events during xDS processing. + // If a value is not specified, no XdsResourcesDelegate will be used. + // TODO(abeyad): Add public-facing documentation. + // [#not-implemented-hide:] + core.v3.TypedExtensionConfig xds_delegate_extension = 35; + + // Optional XdsConfigTracker configuration, which allows tracking xDS responses in external components, + // e.g., external tracer or monitor. It provides the process point when receive, ingest, or fail to + // process xDS resources and messages. If a value is not specified, no XdsConfigTracker will be used. + // + // .. note:: + // + // There are no in-repo extensions currently, and the :repo:`XdsConfigTracker ` + // interface should be implemented before using. + // See :repo:`xds_config_tracker_integration_test ` + // for an example usage of the interface. + core.v3.TypedExtensionConfig xds_config_tracker_extension = 36; + + // [#not-implemented-hide:] + // This controls the type of listener manager configured for Envoy. Currently + // Envoy only supports ListenerManager for this field and Envoy Mobile + // supports ApiListenerManager. + core.v3.TypedExtensionConfig listener_manager = 37; } // Administration interface :ref:`operations documentation @@ -345,7 +375,7 @@ message Admin { // The path to write the access log for the administration server. If no // access log is desired specify ‘/dev/null’. This is only required if // :ref:`address ` is set. - // Deprecated in favor of *access_log* which offers more options. + // Deprecated in favor of ``access_log`` which offers more options. string access_log_path = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -387,7 +417,7 @@ message ClusterManager { // Name of the local cluster (i.e., the cluster that owns the Envoy running // this configuration). In order to enable :ref:`zone aware routing // ` this option must be set. - // If *local_cluster_name* is defined then :ref:`clusters + // If ``local_cluster_name`` is defined then :ref:`clusters // ` must be defined in the :ref:`Bootstrap // static cluster resources // `. This is unrelated to @@ -403,7 +433,7 @@ message ClusterManager { core.v3.BindConfig upstream_bind_config = 3; // A management server endpoint to stream load stats to via - // *StreamLoadStats*. This must have :ref:`api_type + // ``StreamLoadStats``. This must have :ref:`api_type // ` :ref:`GRPC // `. core.v3.ApiConfigSource load_stats_config = 4; @@ -449,15 +479,15 @@ message Watchdog { } // Register actions that will fire on given WatchDog events. - // See *WatchDogAction* for priority of events. + // See ``WatchDogAction`` for priority of events. repeated WatchdogAction actions = 7; // The duration after which Envoy counts a nonresponsive thread in the - // *watchdog_miss* statistic. If not specified the default is 200ms. + // ``watchdog_miss`` statistic. If not specified the default is 200ms. google.protobuf.Duration miss_timeout = 1; // The duration after which Envoy counts a nonresponsive thread in the - // *watchdog_mega_miss* statistic. If not specified the default is + // ``watchdog_mega_miss`` statistic. If not specified the default is // 1000ms. google.protobuf.Duration megamiss_timeout = 2; @@ -466,20 +496,20 @@ message Watchdog { // kill behavior. If not specified the default is 0 (disabled). google.protobuf.Duration kill_timeout = 3; - // Defines the maximum jitter used to adjust the *kill_timeout* if *kill_timeout* is + // Defines the maximum jitter used to adjust the ``kill_timeout`` if ``kill_timeout`` is // enabled. Enabling this feature would help to reduce risk of synchronized // watchdog kill events across proxies due to external triggers. Set to 0 to // disable. If not specified the default is 0 (disabled). google.protobuf.Duration max_kill_timeout_jitter = 6 [(validate.rules).duration = {gte {}}]; - // If max(2, ceil(registered_threads * Fraction(*multikill_threshold*))) + // If ``max(2, ceil(registered_threads * Fraction(*multikill_threshold*)))`` // threads have been nonresponsive for at least this duration kill the entire // Envoy process. Set to 0 to disable this behavior. If not specified the // default is 0 (disabled). google.protobuf.Duration multikill_timeout = 4; - // Sets the threshold for *multikill_timeout* in terms of the percentage of - // nonresponsive threads required for the *multikill_timeout*. + // Sets the threshold for ``multikill_timeout`` in terms of the percentage of + // nonresponsive threads required for the ``multikill_timeout``. // If not specified the default is 0. type.v3.Percent multikill_threshold = 5; } @@ -490,7 +520,7 @@ message Watchdog { // have an out of band system to terminate the process. // // The interface for the extension is ``Envoy::Server::Configuration::FatalAction``. -// *FatalAction* extensions live in the ``envoy.extensions.fatal_actions`` API +// ``FatalAction`` extensions live in the ``envoy.extensions.fatal_actions`` API // namespace. message FatalAction { // Extension specific configuration for the action. It's expected to conform @@ -570,7 +600,7 @@ message RuntimeLayer { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.RuntimeLayer.RtdsLayer"; - // Resource to subscribe to at *rtds_config* for the RTDS layer. + // Resource to subscribe to at ``rtds_config`` for the RTDS layer. string name = 1; // RTDS configuration source. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto index 84bab4673b..0a266e17e6 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto @@ -37,7 +37,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Cluster configuration] -// Cluster list collections. Entries are *Cluster* resources or references. +// Cluster list collections. Entries are ``Cluster`` resources or references. // [#not-implemented-hide:] message ClusterCollection { xds.core.v3.CollectionEntry entries = 1; @@ -170,7 +170,7 @@ message Cluster { // Optional endpoint metadata match criteria. // The connection to the endpoint with metadata matching what is set in this field // will use the transport socket configuration specified here. - // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match + // The endpoint's metadata entry in ``envoy.transport_socket_match`` is used to match // against the values specified in this field. google.protobuf.Struct match = 2; @@ -209,7 +209,7 @@ message Cluster { // Optionally divide the endpoints in this cluster into subsets defined by // endpoint metadata and selected by route and weighted cluster metadata. - // [#next-free-field: 8] + // [#next-free-field: 9] message LbSubsetConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.LbSubsetConfig"; @@ -225,6 +225,52 @@ message Cluster { DEFAULT_SUBSET = 2; } + enum LbSubsetMetadataFallbackPolicy { + // No fallback. Route metadata will be used as-is. + METADATA_NO_FALLBACK = 0; + + // A special metadata key ``fallback_list`` will be used to provide variants of metadata to try. + // Value of ``fallback_list`` key has to be a list. Every list element has to be a struct - it will + // be merged with route metadata, overriding keys that appear in both places. + // ``fallback_list`` entries will be used in order until a host is found. + // + // ``fallback_list`` key itself is removed from metadata before subset load balancing is performed. + // + // Example: + // + // for metadata: + // + // .. code-block:: yaml + // + // version: 1.0 + // fallback_list: + // - version: 2.0 + // hardware: c64 + // - hardware: c32 + // - version: 3.0 + // + // at first, metadata: + // + // .. code-block:: json + // + // {"version": "2.0", "hardware": "c64"} + // + // will be used for load balancing. If no host is found, metadata: + // + // .. code-block:: json + // + // {"version": "1.0", "hardware": "c32"} + // + // is next to try. If it still results in no host, finally metadata: + // + // .. code-block:: json + // + // {"version": "3.0"} + // + // is used. + FALLBACK_LIST = 1; + } + // Specifications for subsets. message LbSubsetSelector { option (udpa.annotations.versioning).previous_message_type = @@ -260,12 +306,9 @@ message Cluster { // Selects a mode of operation in which each subset has only one host. This mode uses the same rules for // choosing a host, but updating hosts is faster, especially for large numbers of hosts. // - // If a match is found to a host, that host will be used regardless of priority levels, unless the host is unhealthy. + // If a match is found to a host, that host will be used regardless of priority levels. // - // Currently, this mode is only supported if `subset_selectors` has only one entry, and `keys` contains - // only one entry. - // - // When this mode is enabled, configurations that contain more than one host with the same metadata value for the single key in `keys` + // When this mode is enabled, configurations that contain more than one host with the same metadata value for the single key in ``keys`` // will use only one of the hosts with the given key; no requests will be routed to the others. The cluster gauge // :ref:`lb_subsets_single_host_per_subset_duplicate` indicates how many duplicates are // present in the current configuration. @@ -284,7 +327,7 @@ message Cluster { // For any other fallback policy the parameter is not used and should not be set. // Only values also present in // :ref:`keys` are allowed, but - // `fallback_keys_subset` cannot be equal to `keys`. + // ``fallback_keys_subset`` cannot be equal to ``keys``. repeated string fallback_keys_subset = 3; } @@ -297,14 +340,14 @@ message Cluster { // fallback_policy is // :ref:`DEFAULT_SUBSET`. // Each field in default_subset is - // compared to the matching LbEndpoint.Metadata under the *envoy.lb* + // compared to the matching LbEndpoint.Metadata under the ``envoy.lb`` // namespace. It is valid for no hosts to match, in which case the behavior // is the same as a fallback_policy of // :ref:`NO_FALLBACK`. google.protobuf.Struct default_subset = 2; // For each entry, LbEndpoint.Metadata's - // *envoy.lb* namespace is traversed and a subset is created for each unique + // ``envoy.lb`` namespace is traversed and a subset is created for each unique // combination of key and value. For example: // // .. code-block:: json @@ -349,6 +392,16 @@ message Cluster { // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value // and any of the elements in the list matches the criteria. bool list_as_any = 7; + + // Fallback mechanism that allows to try different route metadata until a host is found. + // If load balancing process, including all its mechanisms (like + // :ref:`fallback_policy`) + // fails to select a host, this policy decides if and how the process is repeated using another metadata. + // + // The value defaults to + // :ref:`METADATA_NO_FALLBACK`. + LbSubsetMetadataFallbackPolicy metadata_fallback_policy = 8 + [(validate.rules).enum = {defined_only: true}]; } // Configuration for :ref:`slow start mode `. @@ -365,8 +418,8 @@ message Cluster { // By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve. // // During slow start window, effective weight of an endpoint would be scaled with time factor and aggression: - // `new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))`, - // where `time_factor=(time_since_start_seconds / slow_start_time_seconds)`. + // ``new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))``, + // where ``time_factor=(time_since_start_seconds / slow_start_time_seconds)``. // // As time progresses, more and more traffic would be sent to endpoint, which is in slow start window. // Once host exits slow start, time_factor and aggression no longer affect its weight. @@ -397,18 +450,18 @@ message Cluster { // The following formula is used to calculate the dynamic weights when hosts have different load // balancing weights: // - // `weight = load_balancing_weight / (active_requests + 1)^active_request_bias` + // ``weight = load_balancing_weight / (active_requests + 1)^active_request_bias`` // // The larger the active request bias is, the more aggressively active requests will lower the // effective weight when all host weights are not equal. // - // `active_request_bias` must be greater than or equal to 0.0. + // ``active_request_bias`` must be greater than or equal to 0.0. // - // When `active_request_bias == 0.0` the Least Request Load Balancer doesn't consider the number + // When ``active_request_bias == 0.0`` the Least Request Load Balancer doesn't consider the number // of active requests at the time it picks a host and behaves like the Round Robin Load // Balancer. // - // When `active_request_bias > 0.0` the Least Request Load Balancer scales the load balancing + // When ``active_request_bias > 0.0`` the Least Request Load Balancer scales the load balancing // weight by the number of active requests at the time it does a pick. // // The value is cached for performance reasons and refreshed whenever one of the Load Balancer's @@ -462,8 +515,8 @@ message Cluster { // Specific configuration for the :ref:`Maglev` // load balancing policy. message MaglevLbConfig { - // The table size for Maglev hashing. The Maglev aims for ‘minimal disruption’ rather than an absolute guarantee. - // Minimal disruption means that when the set of upstreams changes, a connection will likely be sent to the same + // The table size for Maglev hashing. Maglev aims for "minimal disruption" rather than an absolute guarantee. + // Minimal disruption means that when the set of upstream hosts change, a connection will likely be sent to the same // upstream as it was before. Increasing the table size reduces the amount of disruption. // The table size must be prime number limited to 5000011. If it is not specified, the default is 65537. google.protobuf.UInt64Value table_size = 1 [(validate.rules).uint64 = {lte: 5000011}]; @@ -472,6 +525,7 @@ message Cluster { // Specific configuration for the // :ref:`Original Destination ` // load balancing policy. + // [#extension: envoy.clusters.original_dst] message OriginalDstLbConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.OriginalDstLbConfig"; @@ -493,6 +547,10 @@ message Cluster { // The http header to override destination address if :ref:`use_http_header `. // is set to true. If the value is empty, :ref:`x-envoy-original-dst-host ` will be used. string http_header_name = 2; + + // The port to override for the original dst address. This port + // will take precedence over filter state and header override ports + google.protobuf.UInt32Value upstream_port_override = 3 [(validate.rules).uint32 = {lte: 65535}]; } // Common configuration for all load balancer implementations. @@ -539,7 +597,7 @@ message Cluster { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.CommonLbConfig.ConsistentHashingLbConfig"; - // If set to `true`, the cluster will use hostname instead of the resolved + // If set to ``true``, the cluster will use hostname instead of the resolved // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address. bool use_hostname_for_hashing = 1; @@ -551,7 +609,7 @@ message Cluster { // Applies to both Ring Hash and Maglev load balancers. // // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified - // `hash_balance_factor`, requests to any upstream host are capped at `hash_balance_factor/100` times the average number of requests + // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the @@ -559,7 +617,7 @@ message Cluster { // // If weights are specified on the hosts, they are respected. // - // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts + // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts // being probed, so use a higher value if you require better performance. google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}]; } @@ -599,7 +657,7 @@ message Cluster { // This will have no effect unless active health checking is also configured. bool ignore_new_hosts_until_first_hc = 5; - // If set to `true`, the cluster manager will drain all existing + // If set to ``true``, the cluster manager will drain all existing // connections to upstream hosts whenever hosts are added or removed from the cluster. bool close_connections_on_host_set_change = 6; @@ -664,7 +722,7 @@ message Cluster { // Indicates how many many streams (rounded up) can be anticipated across a cluster for each // stream, useful for low QPS services. This is currently supported for a subset of // deterministic non-hash-based load-balancing algorithms (weighted round robin, random). - // Unlike *per_upstream_preconnect_ratio* this preconnects across the upstream instances in a + // Unlike ``per_upstream_preconnect_ratio`` this preconnects across the upstream instances in a // cluster, doing best effort predictions of what upstream would be picked next and // pre-establishing a connection. // @@ -692,7 +750,7 @@ message Cluster { reserved "hosts", "tls_context", "extension_protocol_options"; // Configuration to use different transport sockets for different endpoints. - // The entry of *envoy.transport_socket_match* in the + // The entry of ``envoy.transport_socket_match`` in the // :ref:`LbEndpoint.Metadata ` // is used to match against the transport sockets as they appear in the list. The first // :ref:`match ` is used. @@ -712,16 +770,16 @@ message Cluster { // transport_socket: // name: envoy.transport_sockets.raw_buffer // - // Connections to the endpoints whose metadata value under *envoy.transport_socket_match* + // Connections to the endpoints whose metadata value under ``envoy.transport_socket_match`` // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. // // If a :ref:`socket match ` with empty match // criteria is provided, that always match any endpoint. For example, the "defaultToPlaintext" // socket match in case above. // - // If an endpoint metadata's value under *envoy.transport_socket_match* does not match any - // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or - // *transport_socket* specified in this cluster. + // If an endpoint metadata's value under ``envoy.transport_socket_match`` does not match any + // ``TransportSocketMatch``, socket configuration fallbacks to use the ``tls_context`` or + // ``transport_socket`` specified in this cluster. // // This field allows gradual and flexible transport socket configuration changes. // @@ -732,8 +790,8 @@ message Cluster { // // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding - // *TransportSocketMatch* in this field. Other client Envoys receive CDS without - // *transport_socket_match* set, and still send plain text traffic to the same cluster. + // ``TransportSocketMatch`` in this field. Other client Envoys receive CDS without + // ``transport_socket_match`` set, and still send plain text traffic to the same cluster. // // This field can be used to specify custom transport socket configurations for health // checks by adding matching key/value pairs in a health check's @@ -787,7 +845,7 @@ message Cluster { // :ref:`STATIC`, // :ref:`STRICT_DNS` // or :ref:`LOGICAL_DNS` clusters. - // This field supersedes the *hosts* field in the v2 API. + // This field supersedes the ``hosts`` field in the v2 API. // // .. attention:: // @@ -856,7 +914,7 @@ message Cluster { // set so that Envoy will assume that the upstream supports HTTP/2 when // making new HTTP connection pool connections. Currently, Envoy only // supports prior knowledge for upstream connections. Even if TLS is used - // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2 + // with ALPN, ``http2_protocol_options`` must be specified. As an aside this allows HTTP/2 // connections to happen over plain text. // This has been deprecated in favor of http2_protocol_options fields in the // :ref:`http_protocol_options ` @@ -920,13 +978,13 @@ message Cluster { // :ref:`STRICT_DNS` // and :ref:`LOGICAL_DNS` // this setting is ignored. - // This field is deprecated in favor of *dns_resolution_config* + // This field is deprecated in favor of ``dns_resolution_config`` // which aggregates all of the DNS resolver configuration in a single message. repeated core.v3.Address dns_resolvers = 18 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Always use TCP queries instead of UDP queries for DNS lookups. - // This field is deprecated in favor of *dns_resolution_config* + // This field is deprecated in favor of ``dns_resolution_config`` // which aggregates all of the DNS resolver configuration in a single message. bool use_tcp_for_dns_lookups = 45 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -941,12 +999,12 @@ message Cluster { // or any other DNS resolver types and the related parameters. // For example, an object of // :ref:`CaresDnsResolverConfig ` - // can be packed into this *typed_dns_resolver_config*. This configuration replaces the + // can be packed into this ``typed_dns_resolver_config``. This configuration replaces the // :ref:`dns_resolution_config ` // configuration. - // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists, - // when *typed_dns_resolver_config* is in place, Envoy will use it and ignore *dns_resolution_config*. - // When *typed_dns_resolver_config* is missing, the default behavior is in place. + // During the transition period when both ``dns_resolution_config`` and ``typed_dns_resolver_config`` exists, + // when ``typed_dns_resolver_config`` is in place, Envoy will use it and ignore ``dns_resolution_config``. + // When ``typed_dns_resolver_config`` is missing, the default behavior is in place. // [#extension-category: envoy.network.dns_resolver] core.v3.TypedExtensionConfig typed_dns_resolver_config = 55; @@ -1014,8 +1072,8 @@ message Cluster { CommonLbConfig common_lb_config = 27; // Optional custom transport socket implementation to use for upstream connections. - // To setup TLS, set a transport socket with name `envoy.transport_sockets.tls` and - // :ref:`UpstreamTlsContexts ` in the `typed_config`. + // To setup TLS, set a transport socket with name ``envoy.transport_sockets.tls`` and + // :ref:`UpstreamTlsContexts ` in the ``typed_config``. // If no transport socket configuration is specified, new connections // will be set up with plaintext. core.v3.TransportSocket transport_socket = 24; @@ -1024,7 +1082,7 @@ message Cluster { // cluster. It can be used for stats, logging, and varying filter behavior. // Fields should use reverse DNS notation to denote which entity within Envoy // will need the information. For instance, if the metadata is intended for - // the Router filter, the filter name should be specified as *envoy.filters.http.router*. + // the Router filter, the filter name should be specified as ``envoy.filters.http.router``. core.v3.Metadata metadata = 25; // Determines how Envoy selects the protocol used to speak to upstream hosts. @@ -1092,7 +1150,7 @@ message Cluster { // // .. attention:: // - // This field has been deprecated in favor of `timeout_budgets`, part of + // This field has been deprecated in favor of ``timeout_budgets``, part of // :ref:`track_cluster_stats `. bool track_timeout_budgets = 47 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -1103,7 +1161,7 @@ message Cluster { // TCP upstreams. // // For HTTP traffic, Envoy will generally take downstream HTTP and send it upstream as upstream - // HTTP, using the http connection pool and the codec from `http2_protocol_options` + // HTTP, using the http connection pool and the codec from ``http2_protocol_options`` // // For routes where CONNECT termination is configured, Envoy will take downstream CONNECT // requests and forward the CONNECT payload upstream over raw TCP using the tcp connection pool. @@ -1123,7 +1181,7 @@ message Cluster { // Preconnect configuration for this cluster. PreconnectPolicy preconnect_policy = 50; - // If `connection_pool_per_downstream_connection` is true, the cluster will use a separate + // If ``connection_pool_per_downstream_connection`` is true, the cluster will use a separate // connection pool for every downstream connection bool connection_pool_per_downstream_connection = 51; } @@ -1158,6 +1216,7 @@ message LoadBalancingPolicy { reserved "config", "name", "typed_config"; + // [#extension-category: envoy.load_balancing_policies] core.v3.TypedExtensionConfig typed_extension_config = 4; } @@ -1167,15 +1226,6 @@ message LoadBalancingPolicy { repeated Policy policies = 1; } -// An extensible structure containing the address Envoy should bind to when -// establishing upstream connections. -message UpstreamBindConfig { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamBindConfig"; - - // The address Envoy should bind to when establishing upstream connections. - core.v3.Address source_address = 1; -} - message UpstreamConnectionOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamConnectionOptions"; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto index 8543886314..e922737750 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto @@ -24,9 +24,9 @@ message OutlierDetection { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.cluster.OutlierDetection"; - // The number of consecutive 5xx responses or local origin errors that are mapped - // to 5xx error codes before a consecutive 5xx ejection - // occurs. Defaults to 5. + // The number of consecutive server-side error responses (for HTTP traffic, + // 5xx responses; for TCP traffic, connection failures; for Redis, failure to + // respond PONG; etc.) before a consecutive 5xx ejection occurs. Defaults to 5. google.protobuf.UInt32Value consecutive_5xx = 1; // The time interval between ejection analysis sweeps. This can result in diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto index 3f1b6fe3dc..09b13969e8 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto @@ -6,6 +6,7 @@ import "envoy/config/core/v3/socket_option.proto"; import "google/protobuf/wrappers.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; @@ -32,15 +33,20 @@ message Pipe { } // The address represents an envoy internal listener. -// [#comment: TODO(lambdai): Make this address available for listener and endpoint. -// TODO(asraa): When address available, remove workaround from test/server/server_fuzz_test.cc:30.] +// [#comment: TODO(asraa): When address available, remove workaround from test/server/server_fuzz_test.cc:30.] message EnvoyInternalAddress { oneof address_name_specifier { option (validate.required) = true; - // [#not-implemented-hide:] The :ref:`listener name ` of the destination internal listener. + // Specifies the :ref:`name ` of the + // internal listener. string server_listener_name = 1; } + + // Specifies an endpoint identifier to distinguish between multiple endpoints for the same internal listener in a + // single upstream pool. Only used in the upstream addresses for tracking changes to individual endpoints. This, for + // example, may be set to the final destination IP for the target internal listener. + string endpoint_id = 2; } // [#next-free-field: 7] @@ -62,8 +68,8 @@ message SocketAddress { // within an upstream :ref:`BindConfig `, the address // controls the source address of outbound connections. For :ref:`clusters // `, the cluster type determines whether the - // address must be an IP (*STATIC* or *EDS* clusters) or a hostname resolved by DNS - // (*STRICT_DNS* or *LOGICAL_DNS* clusters). Address resolution can be customized + // address must be an IP (``STATIC`` or ``EDS`` clusters) or a hostname resolved by DNS + // (``STRICT_DNS`` or ``LOGICAL_DNS`` clusters). Address resolution can be customized // via :ref:`resolver_name `. string address = 2 [(validate.rules).string = {min_len: 1}]; @@ -82,7 +88,7 @@ message SocketAddress { // this is empty, a context dependent default applies. If the address is a concrete // IP address, no resolution will occur. If address is a hostname this // should be set for resolution other than DNS. Specifying a custom resolver with - // *STRICT_DNS* or *LOGICAL_DNS* will generate an error at runtime. + // ``STRICT_DNS`` or ``LOGICAL_DNS`` will generate an error at runtime. string resolver_name = 5; // When binding to an IPv6 address above, this enables `IPv4 compatibility @@ -110,17 +116,32 @@ message TcpKeepalive { google.protobuf.UInt32Value keepalive_interval = 3; } +message ExtraSourceAddress { + // The additional address to bind. + SocketAddress address = 1 [(validate.rules).message = {required: true}]; + + // Additional socket options that may not be present in Envoy source code or + // precompiled binaries. If specified, this will override the + // :ref:`socket_options ` + // in the BindConfig. If specified with no + // :ref:`socket_options ` + // or an empty list of :ref:`socket_options `, + // it means no socket option will apply. + SocketOptionsOverride socket_options = 2; +} + +// [#next-free-field: 6] message BindConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.BindConfig"; // The address to bind to when creating a socket. - SocketAddress source_address = 1 [(validate.rules).message = {required: true}]; + SocketAddress source_address = 1; - // Whether to set the *IP_FREEBIND* option when creating the socket. When this + // Whether to set the ``IP_FREEBIND`` option when creating the socket. When this // flag is set to true, allows the :ref:`source_address - // ` to be an IP address + // ` to be an IP address // that is not configured on the system running Envoy. When this flag is set - // to false, the option *IP_FREEBIND* is disabled on the socket. When this + // to false, the option ``IP_FREEBIND`` is disabled on the socket. When this // flag is not set (default), the socket is not modified, i.e. the option is // neither enabled nor disabled. google.protobuf.BoolValue freebind = 2; @@ -128,6 +149,21 @@ message BindConfig { // Additional socket options that may not be present in Envoy source code or // precompiled binaries. repeated SocketOption socket_options = 3; + + // Extra source addresses appended to the address specified in the `source_address` + // field. This enables to specify multiple source addresses. Currently, only one extra + // address can be supported, and the extra address should have a different IP version + // with the address in the `source_address` field. The address which has the same IP + // version with the target host's address IP version will be used as bind address. If more + // than one extra address specified, only the first address matched IP version will be + // returned. If there is no same IP version address found, the address in the `source_address` + // will be returned. + repeated ExtraSourceAddress extra_source_addresses = 5; + + // Deprecated by + // :ref:`extra_source_addresses ` + repeated SocketAddress additional_source_addresses = 4 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; } // Addresses specify either a logical or physical address and port, which are @@ -143,7 +179,8 @@ message Address { Pipe pipe = 2; - // [#not-implemented-hide:] + // Specifies a user-space address handled by :ref:`internal listeners + // `. EnvoyInternalAddress envoy_internal_address = 3; } } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/backoff.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/backoff.proto index 1899d1abf1..435b36190e 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/backoff.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/backoff.proto @@ -14,7 +14,7 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/core/v3;corev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Backoff Strategy] +// [#protodoc-title: Backoff strategy] // Configuration defining a jittered exponential back off strategy. message BackoffStrategy { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto index f8d94a49dd..383b3d9639 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto @@ -103,7 +103,7 @@ message BuildVersion { } // Version and identification for an Envoy extension. -// [#next-free-field: 6] +// [#next-free-field: 7] message Extension { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Extension"; @@ -121,7 +121,8 @@ message Extension { // [#not-implemented-hide:] Type descriptor of extension configuration proto. // [#comment:TODO(yanavlasov): Link to the doc with existing configuration protos.] // [#comment:TODO(yanavlasov): Add tests when PR #9391 lands.] - string type_descriptor = 3; + string type_descriptor = 3 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // The version is a property of the extension and maintained independently // of other extensions and the Envoy API. @@ -130,6 +131,9 @@ message Extension { // Indicates that the extension is present but was disabled via dynamic configuration. bool disabled = 5; + + // Type URLs of extension configuration protos. + repeated string type_urls = 6; } // Identifies a specific Envoy instance. The node identifier is presented to the @@ -197,7 +201,7 @@ message Node { // Client feature support list. These are well known features described // in the Envoy API repository for a given major version of an API. Client features - // use reverse DNS naming scheme, for example `com.acme.feature`. + // use reverse DNS naming scheme, for example ``com.acme.feature``. // See :ref:`the list of features ` that xDS client may // support. repeated string client_features = 10; @@ -205,7 +209,7 @@ message Node { // Known listening ports on the node as a generic hint to the management server // for filtering :ref:`listeners ` to be returned. For example, // if there is a listener bound to port 80, the list can optionally contain the - // SocketAddress `(0.0.0.0,80)`. The field is optional and just a hint. + // SocketAddress ``(0.0.0.0,80)``. The field is optional and just a hint. repeated Address listening_addresses = 11 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; } @@ -235,20 +239,20 @@ message Node { message Metadata { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Metadata"; - // Key is the reverse DNS filter name, e.g. com.acme.widget. The envoy.* + // Key is the reverse DNS filter name, e.g. com.acme.widget. The ``envoy.*`` // namespace is reserved for Envoy's built-in filters. - // If both *filter_metadata* and + // If both ``filter_metadata`` and // :ref:`typed_filter_metadata ` // fields are present in the metadata with same keys, - // only *typed_filter_metadata* field will be parsed. + // only ``typed_filter_metadata`` field will be parsed. map filter_metadata = 1; - // Key is the reverse DNS filter name, e.g. com.acme.widget. The envoy.* + // Key is the reverse DNS filter name, e.g. com.acme.widget. The ``envoy.*`` // namespace is reserved for Envoy's built-in filters. // The value is encoded as google.protobuf.Any. // If both :ref:`filter_metadata ` - // and *typed_filter_metadata* fields are present in the metadata with same keys, - // only *typed_filter_metadata* field will be parsed. + // and ``typed_filter_metadata`` fields are present in the metadata with same keys, + // only ``typed_filter_metadata`` field will be parsed. map typed_filter_metadata = 2; } @@ -319,7 +323,7 @@ message HeaderValue { // // The same :ref:`format specifier ` as used for // :ref:`HTTP access logging ` applies here, however - // unknown header values are replaced with the empty string instead of `-`. + // unknown header values are replaced with the empty string instead of ``-``. string value = 2 [ (validate.rules).string = {max_bytes: 16384 well_known_regex: HTTP_HEADER_VALUE strict: false} ]; @@ -352,11 +356,25 @@ message HeaderValueOption { // Should the value be appended? If true (default), the value is appended to // existing values. Otherwise it replaces any existing values. - google.protobuf.BoolValue append = 2; + // This field is deprecated and please use + // :ref:`append_action ` as replacement. + // + // .. note:: + // The :ref:`external authorization service ` and + // :ref:`external processor service ` have + // default value (``false``) for this field. + google.protobuf.BoolValue append = 2 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // [#not-implemented-hide:] Describes the action taken to append/overwrite the given value for an existing header - // or to only add this header if it's absent. Value defaults to :ref:`APPEND_IF_EXISTS_OR_ADD`. + // Describes the action taken to append/overwrite the given value for an existing header + // or to only add this header if it's absent. + // Value defaults to :ref:`APPEND_IF_EXISTS_OR_ADD + // `. HeaderAppendAction append_action = 3 [(validate.rules).enum = {defined_only: true}]; + + // Is the header value allowed to be empty? If false (default), custom headers with empty values are dropped, + // otherwise they are added. + bool keep_empty_value = 4; } // Wrapper for a set of headers. @@ -469,7 +487,7 @@ message TransportSocket { // :ref:`FractionalPercent ` proto represented as JSON/YAML // and may also be represented as an integer with the assumption that the value is an integral // percentage out of 100. For instance, a runtime key lookup returning the value "42" would parse -// as a `FractionalPercent` whose numerator is 42 and denominator is HUNDRED. +// as a ``FractionalPercent`` whose numerator is 42 and denominator is HUNDRED. message RuntimeFractionalPercent { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.RuntimeFractionalPercent"; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/config_source.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/config_source.proto index a49a05de8d..c12930135a 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/config_source.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/config_source.proto @@ -114,7 +114,7 @@ message ApiConfigSource { // A list of config validators that will be executed when a new update is // received from the ApiConfigSource. Note that each validator handles a // specific xDS service type, and only the validators corresponding to the - // type url (in `:ref: DiscoveryResponse` or `:ref: DeltaDiscoveryResponse`) + // type url (in ``:ref: DiscoveryResponse`` or ``:ref: DeltaDiscoveryResponse``) // will be invoked. // If the validator returns false or throws an exception, the config will be rejected by // the client, and a NACK will be sent. @@ -168,24 +168,24 @@ message PathConfigSource { // // .. note:: // - // If `watched_directory` is *not* configured, Envoy will watch the file path for *moves.* + // If ``watched_directory`` is *not* configured, Envoy will watch the file path for *moves*. // This is because in general only moves are atomic. The same method of swapping files as is // demonstrated in the :ref:`runtime documentation ` can be - // used here also. If `watched_directory` is configured, no watch will be placed directly on - // this path. Instead, the configured `watched_directory` will be used to trigger reloads of + // used here also. If ``watched_directory`` is configured, no watch will be placed directly on + // this path. Instead, the configured ``watched_directory`` will be used to trigger reloads of // this path. This is required in certain deployment scenarios. See below for more information. string path = 1 [(validate.rules).string = {min_len: 1}]; - // If configured, this directory will be watched for *moves.* When an entry in this directory is - // moved to, the `path` will be reloaded. This is required in certain deployment scenarios. + // If configured, this directory will be watched for *moves*. When an entry in this directory is + // moved to, the ``path`` will be reloaded. This is required in certain deployment scenarios. // // Specifically, if trying to load an xDS resource using a // `Kubernetes ConfigMap `_, the // following configuration might be used: // 1. Store xds.yaml inside a ConfigMap. - // 2. Mount the ConfigMap to `/config_map/xds` - // 3. Configure path `/config_map/xds/xds.yaml` - // 4. Configure watched directory `/config_map/xds` + // 2. Mount the ConfigMap to ``/config_map/xds`` + // 3. Configure path ``/config_map/xds/xds.yaml`` + // 4. Configure watched directory ``/config_map/xds`` // // The above configuration will ensure that Envoy watches the owning directory for moves which is // required due to how Kubernetes manages ConfigMap symbolic links during atomic updates. @@ -203,7 +203,7 @@ message ConfigSource { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.ConfigSource"; // Authorities that this config source may be used for. An authority specified in a xdstp:// URL - // is resolved to a *ConfigSource* prior to configuration fetch. This field provides the + // is resolved to a ``ConfigSource`` prior to configuration fetch. This field provides the // association between authority name and configuration source. // [#not-implemented-hide:] repeated xds.core.v3.Authority authorities = 7; @@ -211,7 +211,7 @@ message ConfigSource { oneof config_source_specifier { option (validate.required) = true; - // Deprecated in favor of `path_config_source`. Use that field instead. + // Deprecated in favor of ``path_config_source``. Use that field instead. string path = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Local filesystem path configuration source. @@ -269,7 +269,7 @@ message ExtensionConfigSource { // Optional default configuration to use as the initial configuration if // there is a failure to receive the initial extension configuration or if - // `apply_default_config_without_warming` flag is set. + // ``apply_default_config_without_warming`` flag is set. google.protobuf.Any default_config = 2; // Use the default config as the initial configuration without warming and diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/extension.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/extension.proto index 80afce693c..cacc7b00c2 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/extension.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/extension.proto @@ -23,9 +23,9 @@ message TypedExtensionConfig { string name = 1 [(validate.rules).string = {min_len: 1}]; // The typed config for the extension. The type URL will be used to identify - // the extension. In the case that the type URL is *xds.type.v3.TypedStruct* - // (or, for historical reasons, *udpa.type.v1.TypedStruct*), the inner type - // URL of *TypedStruct* will be utilized. See the + // the extension. In the case that the type URL is ``xds.type.v3.TypedStruct`` + // (or, for historical reasons, ``udpa.type.v1.TypedStruct``), the inner type + // URL of ``TypedStruct`` will be utilized. See the // :ref:`extension configuration overview // ` for further details. google.protobuf.Any typed_config = 2 [(validate.rules).any = {required: true}]; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/grpc_service.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/grpc_service.proto index 4fb6095580..6027b2b47d 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/grpc_service.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/grpc_service.proto @@ -38,7 +38,7 @@ message GrpcService { // `. string cluster_name = 1 [(validate.rules).string = {min_len: 1}]; - // The `:authority` header in the grpc request. If this field is not set, the authority header value will be `cluster_name`. + // The ``:authority`` header in the grpc request. If this field is not set, the authority header value will be ``cluster_name``. // Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster. string authority = 2 [(validate.rules).string = @@ -142,7 +142,7 @@ message GrpcService { // URI of the token exchange service that handles token exchange requests. // [#comment:TODO(asraa): Add URI validation when implemented. Tracked by - // https://github.com/envoyproxy/protoc-gen-validate/issues/303] + // https://github.com/bufbuild/protoc-gen-validate/issues/303] string token_exchange_service_uri = 1; // Location of the target service or resource where the client diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/health_check.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/health_check.proto index 83cce7ccdb..f4c9d857b4 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/health_check.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/health_check.proto @@ -30,7 +30,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Endpoint health status. enum HealthStatus { - // The health status is not known. This is interpreted by Envoy as *HEALTHY*. + // The health status is not known. This is interpreted by Envoy as ``HEALTHY``. UNKNOWN = 0; // Healthy. @@ -43,11 +43,11 @@ enum HealthStatus { // ``_ // or // ``_. - // This is interpreted by Envoy as *UNHEALTHY*. + // This is interpreted by Envoy as ``UNHEALTHY``. DRAINING = 3; // Health check timed out. This is part of HDS and is interpreted by Envoy as - // *UNHEALTHY*. + // ``UNHEALTHY``. TIMEOUT = 4; // Degraded. @@ -75,12 +75,12 @@ message HealthCheck { // Hex encoded payload. E.g., "000000FF". string text = 1 [(validate.rules).string = {min_len: 1}]; - // [#not-implemented-hide:] Binary payload. + // Binary payload. bytes binary = 2; } } - // [#next-free-field: 13] + // [#next-free-field: 15] message HttpHealthCheck { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HealthCheck.HttpHealthCheck"; @@ -96,15 +96,27 @@ message HealthCheck { string host = 1 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; // Specifies the HTTP path that will be requested during health checking. For example - // */healthcheck*. + // ``/healthcheck``. string path = 2 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_VALUE strict: false}]; // [#not-implemented-hide:] HTTP specific payload. Payload send = 3; - // [#not-implemented-hide:] HTTP specific response. - Payload receive = 4; + // Specifies a list of HTTP expected responses to match in the first ``response_buffer_size`` bytes of the response body. + // If it is set, both the expected response check and status code determine the health check. + // When checking the response, “fuzzy” matching is performed such that each payload block must be found, + // and in the order specified, but not necessarily contiguous. + // + // .. note:: + // + // It is recommended to set ``response_buffer_size`` based on the total Payload size for efficiency. + // The default buffer size is 1024 bytes when it is not set. + repeated Payload receive = 4; + + // Specifies the size of response buffer in bytes that is used to Payload match. + // The default value is 1024. Setting to 0 implies that the Payload will be matched against the entire response. + google.protobuf.UInt64Value response_buffer_size = 14 [(validate.rules).uint64 = {gte: 0}]; // Specifies a list of HTTP headers that should be added to each request that is sent to the // health checked cluster. For more information, including details on header value syntax, see @@ -145,6 +157,12 @@ message HealthCheck { // `. See the :ref:`architecture overview // ` for more information. type.matcher.v3.StringMatcher service_name_matcher = 11; + + // HTTP Method that will be used for health checking, default is "GET". + // GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, PATCH methods are supported, but making request body is not supported. + // CONNECT method is disallowed because it is not appropriate for health check request. + // If a non-200 response is expected by the method, it needs to be set in :ref:`expected_statuses `. + RequestMethod method = 13 [(validate.rules).enum = {defined_only: true not_in: 6}]; } message TcpHealthCheck { @@ -155,7 +173,7 @@ message HealthCheck { Payload send = 1; // When checking the response, “fuzzy” matching is performed such that each - // binary block must be found, and in the order specified, but not + // payload block must be found, and in the order specified, but not // necessarily contiguous. repeated Payload receive = 2; } @@ -260,15 +278,15 @@ message HealthCheck { google.protobuf.Duration interval_jitter = 3; // An optional jitter amount as a percentage of interval_ms. If specified, - // during every interval Envoy will add interval_ms * - // interval_jitter_percent / 100 to the wait time. + // during every interval Envoy will add ``interval_ms`` * + // ``interval_jitter_percent`` / 100 to the wait time. // // If interval_jitter_ms and interval_jitter_percent are both set, both of // them will be used to increase the wait time. uint32 interval_jitter_percent = 18; // The number of unhealthy health checks required before a host is marked - // unhealthy. Note that for *http* health checking if a host responds with a code not in + // unhealthy. Note that for ``http`` health checking if a host responds with a code not in // :ref:`expected_statuses ` // or :ref:`retriable_statuses `, // this threshold is ignored and the host is considered immediately unhealthy. @@ -316,7 +334,7 @@ message HealthCheck { // (including new hosts) when the cluster has received no traffic. // // This is useful for when we want to send frequent health checks with - // `no_traffic_interval` but then revert to lower frequency `no_traffic_healthy_interval` once + // ``no_traffic_interval`` but then revert to lower frequency ``no_traffic_healthy_interval`` once // a host in the cluster is marked as healthy. // // Once a cluster has been used for traffic routing, Envoy will shift back to using the @@ -386,7 +404,7 @@ message HealthCheck { // name: envoy.transport_sockets.tls // config: { ... } # tls socket configuration // - // If this field is set, then for health checks it will supersede an entry of *envoy.transport_socket* in the + // If this field is set, then for health checks it will supersede an entry of ``envoy.transport_socket`` in the // :ref:`LbEndpoint.Metadata `. // This allows using different transport socket capabilities for health checking versus proxying to the // endpoint. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_uri.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_uri.proto index ec0f71f905..93b63093e3 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_uri.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_uri.proto @@ -14,7 +14,7 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/core/v3;corev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: HTTP Service URI ] +// [#protodoc-title: HTTP service URI ] // Envoy external URI descriptor message HttpUri { @@ -30,7 +30,7 @@ message HttpUri { // string uri = 1 [(validate.rules).string = {min_len: 1}]; - // Specify how `uri` is to be fetched. Today, this requires an explicit + // Specify how ``uri`` is to be fetched. Today, this requires an explicit // cluster, but in the future we may support dynamic cluster creation or // inline DNS resolution. See `issue // `_. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto index f18a2053d9..0def86bcb2 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto @@ -75,9 +75,9 @@ message QuicProtocolOptions { google.protobuf.UInt32Value initial_stream_window_size = 2 [(validate.rules).uint32 = {lte: 16777216 gte: 1}]; - // Similar to *initial_stream_window_size*, but for connection-level + // Similar to ``initial_stream_window_size``, but for connection-level // flow-control. Valid values rage from 1 to 25165824 (24MB, maximum supported by QUICHE) and defaults to 65536 (2^16). - // window. Currently, this has the same minimum/default as *initial_stream_window_size*. + // window. Currently, this has the same minimum/default as ``initial_stream_window_size``. // // NOTE: 16384 (2^14) is the minimum window size supported in Google QUIC. We only support increasing the default // window size now, so it's also the minimum. @@ -109,7 +109,7 @@ message UpstreamHttpProtocolOptions { // Automatic validate upstream presented certificate for new upstream connections based on the // downstream HTTP host/authority header or any other arbitrary header when :ref:`override_auto_sni_header ` // is set, as seen by the :ref:`router filter `. - // This field is intended to be set with `auto_sni` field. + // This field is intended to be set with ``auto_sni`` field. bool auto_san_validation = 2; // An optional alternative to the host/authority header to be used for setting the SNI value. @@ -117,7 +117,7 @@ message UpstreamHttpProtocolOptions { // :ref:`router filter `. // If unset, host/authority header will be used for populating the SNI. If the specified header // is not found or the value is empty, host/authority header will be used instead. - // This field is intended to be set with `auto_sni` and/or `auto_san_validation` fields. + // This field is intended to be set with ``auto_sni`` and/or ``auto_san_validation`` fields. // If none of these fields are set then setting this would be a no-op. string override_auto_sni_header = 3 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; @@ -127,6 +127,7 @@ message UpstreamHttpProtocolOptions { // make an HTTP connection to an origin server. See https://tools.ietf.org/html/rfc7838 for // HTTP Alternative Services and https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04 // for the "HTTPS" DNS resource record. +// [#next-free-field: 6] message AlternateProtocolsCacheOptions { // Allows pre-populating the cache with HTTP/3 alternate protocols entries with a 7 day lifetime. // This will cause Envoy to attempt HTTP/3 to those upstreams, even if the upstreams have not @@ -171,6 +172,17 @@ message AlternateProtocolsCacheOptions { // Allows pre-populating the cache with entries, as described above. repeated AlternateProtocolsCacheEntry prepopulated_entries = 4; + + // Optional list of hostnames suffixes for which Alt-Svc entries can be shared. For example, if + // this list contained the value ``.c.example.com``, then an Alt-Svc entry for ``foo.c.example.com`` + // could be shared with ``bar.c.example.com`` but would not be shared with ``baz.example.com``. On + // the other hand, if the list contained the value ``.example.com`` then all three hosts could share + // Alt-Svc entries. Each entry must start with ``.``. If a hostname matches multiple suffixes, the + // first listed suffix will be used. + // + // Since lookup in this list is O(n), it is recommended that the number of suffixes be limited. + // [#not-implemented-hide:] + repeated string canonical_suffixes = 5; } // [#next-free-field: 7] @@ -247,7 +259,7 @@ message HttpProtocolOptions { google.protobuf.UInt32Value max_requests_per_connection = 6; } -// [#next-free-field: 8] +// [#next-free-field: 9] message Http1ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Http1ProtocolOptions"; @@ -282,18 +294,18 @@ message Http1ProtocolOptions { // Handle HTTP requests with absolute URLs in the requests. These requests // are generally sent by clients to forward/explicit proxies. This allows clients to configure // envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the - // *http_proxy* environment variable. + // ``http_proxy`` environment variable. google.protobuf.BoolValue allow_absolute_url = 1; // Handle incoming HTTP/1.0 and HTTP 0.9 requests. // This is off by default, and not fully standards compliant. There is support for pre-HTTP/1.1 // style connect logic, dechunking, and handling lack of client host iff - // *default_host_for_http_10* is configured. + // ``default_host_for_http_10`` is configured. bool accept_http_10 = 2; - // A default host for HTTP/1.0 requests. This is highly suggested if *accept_http_10* is true as + // A default host for HTTP/1.0 requests. This is highly suggested if ``accept_http_10`` is true as // Envoy does not otherwise support HTTP/1.0 without a Host header. - // This is a no-op if *accept_http_10* is not true. + // This is a no-op if ``accept_http_10`` is not true. string default_host_for_http_10 = 3; // Describes how the keys for response headers should be formatted. By default, all header keys @@ -311,7 +323,7 @@ message Http1ProtocolOptions { // - The content length header is not present. bool enable_trailers = 5; - // Allows Envoy to process requests/responses with both `Content-Length` and `Transfer-Encoding` + // Allows Envoy to process requests/responses with both ``Content-Length`` and ``Transfer-Encoding`` // headers set. By default such messages are rejected, but if option is enabled - Envoy will // remove Content-Length header and process message. // See `RFC7230, sec. 3.3.3 `_ for details. @@ -319,6 +331,9 @@ message Http1ProtocolOptions { // .. attention:: // Enabling this option might lead to request smuggling vulnerability, especially if traffic // is proxied via multiple layers of proxies. + // [#comment:TODO: This field is ignored when the + // :ref:`header validation configuration ` + // is present.] bool allow_chunked_length = 6; // Allows invalid HTTP messaging. When this option is false, then Envoy will terminate @@ -328,6 +343,13 @@ message Http1ProtocolOptions { // If set, this overrides any HCM :ref:`stream_error_on_invalid_http_messaging // `. google.protobuf.BoolValue override_stream_error_on_invalid_http_message = 7; + + // Allows sending fully qualified URLs when proxying the first line of the + // response. By default, Envoy will only send the path components in the first line. + // If this is true, Envoy will create a fully qualified URI composing scheme + // (inferred if not present), host (from the host/:authority header) and path + // (from first line or :path header). + bool send_fully_qualified_url = 8; } message KeepaliveSettings { @@ -415,8 +437,8 @@ message Http2ProtocolOptions { google.protobuf.UInt32Value initial_stream_window_size = 3 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; - // Similar to *initial_stream_window_size*, but for connection-level flow-control - // window. Currently, this has the same minimum/maximum/default as *initial_stream_window_size*. + // Similar to ``initial_stream_window_size``, but for connection-level flow-control + // window. Currently, this has the same minimum/maximum/default as ``initial_stream_window_size``. google.protobuf.UInt32Value initial_connection_window_size = 4 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; @@ -456,11 +478,11 @@ message Http2ProtocolOptions { // of PRIORITY frames received over the lifetime of connection exceeds the value calculated // using this formula:: // - // max_inbound_priority_frames_per_stream * (1 + opened_streams) + // ``max_inbound_priority_frames_per_stream`` * (1 + ``opened_streams``) // - // the connection is terminated. For downstream connections the `opened_streams` is incremented when + // the connection is terminated. For downstream connections the ``opened_streams`` is incremented when // Envoy receives complete response headers from the upstream server. For upstream connection the - // `opened_streams` is incremented when Envoy send the HEADERS frame for a new stream. The + // ``opened_streams`` is incremented when Envoy send the HEADERS frame for a new stream. The // ``http2.inbound_priority_frames_flood`` stat tracks // the number of connections terminated due to flood mitigation. The default limit is 100. google.protobuf.UInt32Value max_inbound_priority_frames_per_stream = 10; @@ -469,12 +491,12 @@ message Http2ProtocolOptions { // of WINDOW_UPDATE frames received over the lifetime of connection exceeds the value calculated // using this formula:: // - // 5 + 2 * (opened_streams + - // max_inbound_window_update_frames_per_data_frame_sent * outbound_data_frames) + // 5 + 2 * (``opened_streams`` + + // ``max_inbound_window_update_frames_per_data_frame_sent`` * ``outbound_data_frames``) // - // the connection is terminated. For downstream connections the `opened_streams` is incremented when + // the connection is terminated. For downstream connections the ``opened_streams`` is incremented when // Envoy receives complete response headers from the upstream server. For upstream connections the - // `opened_streams` is incremented when Envoy sends the HEADERS frame for a new stream. The + // ``opened_streams`` is incremented when Envoy sends the HEADERS frame for a new stream. The // ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to // flood mitigation. The default max_inbound_window_update_frames_per_data_frame_sent value is 10. // Setting this to 1 should be enough to support HTTP/2 implementations with basic flow control, diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/proxy_protocol.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/proxy_protocol.proto index 9cfdbe5f66..c276ce4d58 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/proxy_protocol.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/proxy_protocol.proto @@ -10,7 +10,7 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/core/v3;corev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Proxy Protocol] +// [#protodoc-title: Proxy protocol] message ProxyProtocolConfig { enum Version { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto index e7605fb688..44f1ce3890 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto @@ -12,7 +12,7 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/core/v3;corev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Socket Option ] +// [#protodoc-title: Socket option] // Generic socket option message. This would be used to set socket options that // might not exist in upstream kernels or precompiled Envoy binaries. @@ -75,3 +75,7 @@ message SocketOption { // STATE_PREBIND is currently the only valid value. SocketState state = 6 [(validate.rules).enum = {defined_only: true}]; } + +message SocketOptionsOverride { + repeated SocketOption socket_options = 1; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto index 7259725e05..11c834accd 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto @@ -97,9 +97,9 @@ message SubstitutionFormatString { // * for ``json_format`` the keys with null values are omitted in the output structure. bool omit_empty_values = 3; - // Specify a *content_type* field. - // If this field is not set then ``text/plain`` is used for *text_format* and - // ``application/json`` is used for *json_format*. + // Specify a ``content_type`` field. + // If this field is not set then ``text/plain`` is used for ``text_format`` and + // ``application/json`` is used for ``json_format``. // // .. validated-code-block:: yaml // :type-name: envoy.config.core.v3.SubstitutionFormatString diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto index 49f38211e8..247f2a5019 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto @@ -44,6 +44,17 @@ message Endpoint { // to a non-empty value allows overriding the cluster level configuration for a specific // endpoint. string hostname = 2; + + // Optional alternative health check host address. + // + // .. attention:: + // + // The form of the health check host address is expected to be a direct IP address. + core.v3.Address address = 3; + + // Optional flag to control if perform active health check for this endpoint. + // Active health check is enabled by default if there is a health checker. + bool disable_active_health_check = 4; } // The upstream host address. @@ -91,8 +102,8 @@ message LbEndpoint { // The endpoint metadata specifies values that may be used by the load // balancer to select endpoints in a cluster for a given request. The filter - // name should be specified as *envoy.lb*. An example boolean key-value pair - // is *canary*, providing the optional canary status of the upstream host. + // name should be specified as ``envoy.lb``. An example boolean key-value pair + // is ``canary``, providing the optional canary status of the upstream host. // This may be matched against in a route's // :ref:`RouteAction ` metadata_match field // to subset the endpoints considered in cluster load balancing. @@ -104,9 +115,9 @@ message LbEndpoint { // of the weights of all endpoints in the endpoint's locality to produce a // percentage of traffic for the endpoint. This percentage is then further // weighted by the endpoint's locality's load balancing weight from - // LocalityLbEndpoints. If unspecified, each host is presumed to have equal - // weight in a locality. The sum of the weights of all endpoints in the - // endpoint's locality must not exceed uint32_t maximal value (4294967295). + // LocalityLbEndpoints. If unspecified, will be treated as 1. The sum + // of the weights of all endpoints in the endpoint's locality must not + // exceed uint32_t maximal value (4294967295). google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}]; } @@ -140,13 +151,13 @@ message LocalityLbEndpoints { // The group of endpoints belonging to the locality specified. // [#comment:TODO(adisuissa): Once LEDS is implemented this field needs to be - // deprecated and replaced by *load_balancer_endpoints*.] + // deprecated and replaced by ``load_balancer_endpoints``.] repeated LbEndpoint lb_endpoints = 2; // [#not-implemented-hide:] oneof lb_config { // The group of endpoints belonging to the locality. - // [#comment:TODO(adisuissa): Once LEDS is implemented the *lb_endpoints* field + // [#comment:TODO(adisuissa): Once LEDS is implemented the ``lb_endpoints`` field // needs to be deprecated.] LbEndpointList load_balancer_endpoints = 7; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/load_report.proto b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/load_report.proto index 85ecae7f2d..832fe83dbb 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/load_report.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/load_report.proto @@ -161,8 +161,8 @@ message ClusterStats { repeated DroppedRequests dropped_requests = 5; // Period over which the actual load report occurred. This will be guaranteed to include every - // request reported. Due to system load and delays between the *LoadStatsRequest* sent from Envoy - // and the *LoadStatsResponse* message sent from the management server, this may be longer than - // the requested load reporting interval in the *LoadStatsResponse*. + // request reported. Due to system load and delays between the ``LoadStatsRequest`` sent from Envoy + // and the ``LoadStatsResponse`` message sent from the management server, this may be longer than + // the requested load reporting interval in the ``LoadStatsResponse``. google.protobuf.Duration load_report_interval = 4; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto index d8982b0a97..2016d2bb8e 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto @@ -5,6 +5,7 @@ package envoy.config.listener.v3; import "envoy/config/accesslog/v3/accesslog.proto"; import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/base.proto"; +import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/socket_option.proto"; import "envoy/config/listener/v3/api_listener.proto"; import "envoy/config/listener/v3/listener_components.proto"; @@ -32,13 +33,27 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Listener configuration] // Listener :ref:`configuration overview ` -// Listener list collections. Entries are *Listener* resources or references. +// The additional address the listener is listening on. +message AdditionalAddress { + core.v3.Address address = 1; + + // Additional socket options that may not be present in Envoy source code or + // precompiled binaries. If specified, this will override the + // :ref:`socket_options ` + // in the listener. If specified with no + // :ref:`socket_options ` + // or an empty list of :ref:`socket_options `, + // it means no socket option will apply. + core.v3.SocketOptionsOverride socket_options = 2; +} + +// Listener list collections. Entries are ``Listener`` resources or references. // [#not-implemented-hide:] message ListenerCollection { repeated xds.core.v3.CollectionEntry entries = 1; } -// [#next-free-field: 33] +// [#next-free-field: 34] message Listener { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener"; @@ -88,11 +103,15 @@ message Listener { // If specified, the listener will use the exact connection balancer. ExactBalance exact_balance = 1; + + // The listener will use the connection balancer according to ``type_url``. If ``type_url`` is invalid, + // Envoy will not attempt to balance active connections between worker threads. + // [#extension-category: envoy.network.connection_balance] + core.v3.TypedExtensionConfig extend_balance = 2; } } // Configuration for envoy internal listener. All the future internal listener features should be added here. - // [#not-implemented-hide:] message InternalListenerConfig { } @@ -106,12 +125,17 @@ message Listener { // The address that the listener should listen on. In general, the address must be unique, though // that is governed by the bind rules of the OS. E.g., multiple listeners can listen on port 0 on // Linux as the actual port will be allocated by the OS. - // Required unless *api_listener* or *listener_specifier* is populated. + // Required unless ``api_listener`` or ``listener_specifier`` is populated. core.v3.Address address = 2; + // The additional addresses the listener should listen on. The addresses must be unique across all + // listeners. Multiple addresses with port 0 can be supplied. When using multiple addresses in a single listener, + // all addresses use the same protocol, and multiple internal addresses are not supported. + repeated AdditionalAddress additional_addresses = 33; + // Optional prefix to use on listener stats. If empty, the stats will be rooted at - // `listener.
.`. If non-empty, stats will be rooted at - // `listener..`. + // ``listener.
.``. If non-empty, stats will be rooted at + // ``listener..``. string stat_prefix = 28; // A list of filter chains to consider for this listener. The @@ -142,7 +166,7 @@ message Listener { xds.type.matcher.v3.Matcher filter_chain_matcher = 32 [(xds.annotations.v3.field_status).work_in_progress = true]; - // If a connection is redirected using *iptables*, the port on which the proxy + // If a connection is redirected using ``iptables``, the port on which the proxy // receives it might be different from the original destination address. When this flag is set to // true, the listener hands off redirected connections to the listener associated with the // original destination address. If there is no listener associated with the original destination @@ -180,7 +204,7 @@ message Listener { // The timeout to wait for all listener filters to complete operation. If the timeout is reached, // the accepted socket is closed without a connection being created unless - // `continue_on_listener_filters_timeout` is set to true. Specify 0 to disable the + // ``continue_on_listener_filters_timeout`` is set to true. Specify 0 to disable the // timeout. If not specified, a default timeout of 15s is used. google.protobuf.Duration listener_filters_timeout = 15; @@ -195,30 +219,33 @@ message Listener { // Whether the listener should be set as a transparent socket. // When this flag is set to true, connections can be redirected to the listener using an - // *iptables* *TPROXY* target, in which case the original source and destination addresses and + // ``iptables`` ``TPROXY`` target, in which case the original source and destination addresses and // ports are preserved on accepted connections. This flag should be used in combination with // :ref:`an original_dst ` :ref:`listener filter // ` to mark the connections' local addresses as // "restored." This can be used to hand off each redirected connection to another listener // associated with the connection's destination address. Direct connections to the socket without - // using *TPROXY* cannot be distinguished from connections redirected using *TPROXY* and are + // using ``TPROXY`` cannot be distinguished from connections redirected using ``TPROXY`` and are // therefore treated as if they were redirected. // When this flag is set to false, the listener's socket is explicitly reset as non-transparent. - // Setting this flag requires Envoy to run with the *CAP_NET_ADMIN* capability. + // Setting this flag requires Envoy to run with the ``CAP_NET_ADMIN`` capability. // When this flag is not set (default), the socket is not modified, i.e. the transparent option // is neither set nor reset. google.protobuf.BoolValue transparent = 10; - // Whether the listener should set the *IP_FREEBIND* socket option. When this + // Whether the listener should set the ``IP_FREEBIND`` socket option. When this // flag is set to true, listeners can be bound to an IP address that is not // configured on the system running Envoy. When this flag is set to false, the - // option *IP_FREEBIND* is disabled on the socket. When this flag is not set + // option ``IP_FREEBIND`` is disabled on the socket. When this flag is not set // (default), the socket is not modified, i.e. the option is neither enabled // nor disabled. google.protobuf.BoolValue freebind = 11; // Additional socket options that may not be present in Envoy source code or - // precompiled binaries. + // precompiled binaries. The socket options can be updated for a listener when + // :ref:`enable_reuse_port ` + // is `true`. Otherwise, if socket options change during a listener update the update will be rejected + // to make it clear that the options were not updated. repeated core.v3.SocketOption socket_options = 13; // Whether the listener should accept TCP Fast Open (TFO) connections. @@ -277,14 +304,16 @@ message Listener { // enable the balance config in Y1 and Y2 to balance the connections among the workers. ConnectionBalanceConfig connection_balance_config = 20; - // Deprecated. Use `enable_reuse_port` instead. + // Deprecated. Use ``enable_reuse_port`` instead. bool reuse_port = 21 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // When this flag is set to true, listeners set the *SO_REUSEPORT* socket option and + // When this flag is set to true, listeners set the ``SO_REUSEPORT`` socket option and // create one socket for each worker thread. This makes inbound connections // distribute among worker threads roughly evenly in cases where there are a high number // of connections. When this flag is set to false, all worker threads share one socket. This field - // defaults to true. + // defaults to true. The change of field will be rejected during an listener update when the + // runtime flag ``envoy.reloadable_features.enable_update_listener_socket_options`` is enabled. + // Otherwise, the update of this field will be ignored quietly. // // .. attention:: // @@ -317,24 +346,21 @@ message Listener { google.protobuf.BoolValue bind_to_port = 26; // The exclusive listener type and the corresponding config. - // TODO(lambdai): https://github.com/envoyproxy/envoy/issues/15372 - // Will create and add TcpListenerConfig. Will add UdpListenerConfig and ApiListener. - // [#not-implemented-hide:] oneof listener_specifier { // Used to represent an internal listener which does not listen on OSI L4 address but can be used by the // :ref:`envoy cluster ` to create a user space connection to. - // The internal listener acts as a tcp listener. It supports listener filters and network filter chains. - // The internal listener require :ref:`address ` has - // field `envoy_internal_address`. + // The internal listener acts as a TCP listener. It supports listener filters and network filter chains. + // Upstream clusters refer to the internal listeners by their :ref:`name + // `. :ref:`Address + // ` must not be set on the internal listeners. // - // There are some limitations are derived from the implementation. The known limitations include + // There are some limitations that are derived from the implementation. The known limitations include: // // * :ref:`ConnectionBalanceConfig ` is not - // allowed because both cluster connection and listener connection must be owned by the same dispatcher. + // allowed because both the cluster connection and the listener connection must be owned by the same dispatcher. // * :ref:`tcp_backlog_size ` // * :ref:`freebind ` // * :ref:`transparent ` - // [#not-implemented-hide:] InternalListenerConfig internal_listener = 27; } @@ -346,3 +372,21 @@ message Listener { // :ref:`global_downstream_max_connections `. bool ignore_global_conn_limit = 31; } + +// A placeholder proto so that users can explicitly configure the standard +// Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ListenerManager { +} + +// A placeholder proto so that users can explicitly configure the standard +// Validation Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ValidationListenerManager { +} + +// A placeholder proto so that users can explicitly configure the API +// Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ApiListenerManager { +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener_components.proto b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener_components.proto index aed27c3714..150a6851d5 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener_components.proto @@ -11,8 +11,6 @@ import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; -import "xds/annotations/v3/status.proto"; - import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; @@ -157,6 +155,7 @@ message FilterChainMatch { // will be first matched against ``www.example.com``, then ``*.example.com``, then ``*.com``. // // Note that partial wildcards are not supported, and values like ``*w.example.com`` are invalid. + // The value ``*`` is also not supported, and ``server_names`` should be omitted instead. // // .. attention:: // @@ -229,6 +228,12 @@ message FilterChain { // connections established with the listener. Order matters as the filters are // processed sequentially as connection events happen. Note: If the filter // list is empty, the connection will close by default. + // + // For QUIC listeners, network filters other than HTTP Connection Manager (HCM) + // can be created, but due to differences in the connection implementation compared + // to TCP, the onData() method will never be called. Therefore, network filters + // for QUIC listeners should only expect to do work at the start of a new connection + // (i.e. in onNewConnection()). HCM must be the last (or only) filter in the chain. repeated Filter filters = 3; // Whether the listener should expect a PROXY protocol V1 header on new @@ -248,8 +253,8 @@ message FilterChain { core.v3.Metadata metadata = 5; // Optional custom transport socket implementation to use for downstream connections. - // To setup TLS, set a transport socket with name `envoy.transport_sockets.tls` and - // :ref:`DownstreamTlsContext ` in the `typed_config`. + // To setup TLS, set a transport socket with name ``envoy.transport_sockets.tls`` and + // :ref:`DownstreamTlsContext ` in the ``typed_config``. // If no transport socket configuration is specified, new connections // will be set up with plaintext. // [#extension-category: envoy.transport_sockets.downstream] @@ -264,7 +269,7 @@ message FilterChain { // Note: :ref:`filter_chain_matcher // ` // requires that filter chains are uniquely named within a listener. - string name = 7 [(xds.annotations.v3.field_status).work_in_progress = true]; + string name = 7; // [#not-implemented-hide:] The configuration to specify whether the filter chain will be built on-demand. // If this field is not empty, the filter chain will be built on-demand. @@ -357,7 +362,6 @@ message ListenerFilter { // Configuration source specifier for an extension configuration discovery // service. In case of a failure and without the default configuration, the // listener closes the connections. - // [#not-implemented-hide:] core.v3.ExtensionConfigSource config_discovery = 5; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/quic_config.proto b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/quic_config.proto index 89dc34a06b..42b5a6e516 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/quic_config.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/quic_config.proto @@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: QUIC listener config] // Configuration specific to the UDP QUIC listener. -// [#next-free-field: 8] +// [#next-free-field: 9] message QuicProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.listener.QuicProtocolOptions"; @@ -54,13 +54,18 @@ message QuicProtocolOptions { google.protobuf.UInt32Value packets_to_read_to_connection_count_ratio = 5 [(validate.rules).uint32 = {gte: 1}]; - // Configure which implementation of `quic::QuicCryptoClientStreamBase` to be used for this listener. + // Configure which implementation of ``quic::QuicCryptoClientStreamBase`` to be used for this listener. // If not specified the :ref:`QUICHE default one configured by ` will be used. // [#extension-category: envoy.quic.server.crypto_stream] core.v3.TypedExtensionConfig crypto_stream_config = 6; - // Configure which implementation of `quic::ProofSource` to be used for this listener. + // Configure which implementation of ``quic::ProofSource`` to be used for this listener. // If not specified the :ref:`default one configured by ` will be used. // [#extension-category: envoy.quic.proof_source] core.v3.TypedExtensionConfig proof_source_config = 7; + + // Config which implementation of ``quic::ConnectionIdGeneratorInterface`` to be used for this listener. + // If not specified the :ref:`default one configured by ` will be used. + // [#extension-category: envoy.quic.connection_id_generator] + core.v3.TypedExtensionConfig connection_id_generator_config = 8; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/udp_listener_config.proto b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/udp_listener_config.proto index f3f03d23ed..4e619b1f76 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/udp_listener_config.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/udp_listener_config.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.config.listener.v3; +import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/udp_socket_config.proto"; import "envoy/config/listener/v3/quic_config.proto"; @@ -17,7 +18,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: UDP listener config] // Listener :ref:`configuration overview ` -// [#next-free-field: 8] +// [#next-free-field: 9] message UdpListenerConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.listener.UdpListenerConfig"; @@ -35,6 +36,14 @@ message UdpListenerConfig { // Configuration for QUIC protocol. If empty, QUIC will not be enabled on this listener. Set // to the default object to enable QUIC without modifying any additional options. QuicProtocolOptions quic_options = 7; + + // Configuration for the UDP packet writer. If empty, HTTP/3 will use GSO if available + // (:ref:`UdpDefaultWriterFactory `) + // or the default kernel sendmsg if not, + // (:ref:`UdpDefaultWriterFactory `) + // and raw UDP will use kernel sendmsg. + // [#extension-category: envoy.udp_packet_writer] + core.v3.TypedExtensionConfig udp_packet_packet_writer_config = 8; } message ActiveRawUdpListenerConfig { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto b/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto index 17ae761ea3..fb73e91f8f 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto @@ -48,10 +48,11 @@ message StatsConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.metrics.v2.StatsConfig"; - // Each stat name is iteratively processed through these tag specifiers. - // When a tag is matched, the first capture group is removed from the name so - // later :ref:`TagSpecifiers ` cannot match that - // same portion of the match. + // Each stat name is independently processed through these tag specifiers. When a tag is + // matched, the first capture group is not immediately removed from the name, so later + // :ref:`TagSpecifiers ` can also match that + // same portion of the match. After all tag matching is complete, a tag-extracted version of + // the name is produced and is used in stats sinks that represent tags, such as Prometheus. repeated TagSpecifier stats_tags = 1; // Use all default tag regexes specified in Envoy. These can be combined with @@ -120,7 +121,7 @@ message StatsMatcher { // limited by either an exclusion or an inclusion list of :ref:`StringMatcher // ` protos: // - // * If `reject_all` is set to `true`, no stats will be instantiated. If `reject_all` is set to + // * If ``reject_all`` is set to `true`, no stats will be instantiated. If ``reject_all`` is set to // `false`, all stats will be instantiated. // // * If an exclusion list is supplied, any stat name matching *any* of the StringMatchers in the @@ -186,7 +187,7 @@ message StatsMatcher { oneof stats_matcher { option (validate.required) = true; - // If `reject_all` is true, then all stats are disabled. If `reject_all` is false, then all + // If ``reject_all`` is true, then all stats are disabled. If ``reject_all`` is false, then all // stats are enabled. bool reject_all = 1; @@ -219,7 +220,11 @@ message TagSpecifier { // // .. note:: // - // It is invalid to specify the same tag name twice in a config. + // A stat name may be spelled in such a way that it matches two different + // tag extractors for the same tag name. In that case, all but one of the + // tag values will be dropped. It is not specified which tag value will be + // retained. The extraction will only occur for one of the extractors, and + // only the matched extraction will be removed from the tag name. string tag_name = 1; oneof tag_value { @@ -265,18 +270,18 @@ message TagSpecifier { // } // ] // - // The two regexes of the specifiers will be processed in the definition order. + // The two regexes of the specifiers will be processed from the elaborated + // stat name. // - // The first regex will remove ``ios.``, leaving the tag extracted name - // ``http.connection_manager_1.user_agent.downstream_cx_total``. The tag - // ``envoy.http_user_agent`` will be added with tag value ``ios``. + // The first regex will save ``ios.`` as the tag value for ``envoy.http_user_agent``. It will + // leave it in the name for potential matching with additional tag specifiers. After all tag + // specifiers are processed the tags will be removed from the name. // - // The second regex will remove ``connection_manager_1.`` from the tag - // extracted name produced by the first regex - // ``http.connection_manager_1.user_agent.downstream_cx_total``, leaving - // ``http.user_agent.downstream_cx_total`` as the tag extracted name. The tag - // ``envoy.http_conn_manager_prefix`` will be added with the tag value - // ``connection_manager_1``. + // The second regex will populate tag ``envoy.http_conn_manager_prefix`` with value + // ``connection_manager_1.``, based on the original stat name. + // + // As a final step, the matched tags are removed, leaving + // ``http.user_agent.downstream_cx_total`` as the tag extracted name. string regex = 2 [(validate.rules).string = {max_bytes: 1024}]; // Specifies a fixed tag value for the ``tag_name``. @@ -287,7 +292,7 @@ message TagSpecifier { // Specifies a matcher for stats and the buckets that matching stats should use. message HistogramBucketSettings { // The stats that this rule applies to. The match is applied to the original stat name - // before tag-extraction, for example `cluster.exampleclustername.upstream_cx_length_ms`. + // before tag-extraction, for example ``cluster.exampleclustername.upstream_cx_length_ms``. type.matcher.v3.StringMatcher match = 1 [(validate.rules).message = {required: true}]; // Each value is the upper bound of a bucket. Each bucket must be greater than 0 and unique. @@ -299,7 +304,7 @@ message HistogramBucketSettings { }]; } -// Stats configuration proto schema for built-in *envoy.stat_sinks.statsd* sink. This sink does not support +// Stats configuration proto schema for built-in ``envoy.stat_sinks.statsd`` sink. This sink does not support // tagged metrics. // [#extension: envoy.stat_sinks.statsd] message StatsdSink { @@ -348,7 +353,7 @@ message StatsdSink { string prefix = 3; } -// Stats configuration proto schema for built-in *envoy.stat_sinks.dog_statsd* sink. +// Stats configuration proto schema for built-in ``envoy.stat_sinks.dog_statsd`` sink. // The sink emits stats with `DogStatsD `_ // compatible tags. Tags are configurable via :ref:`StatsConfig // `. @@ -380,7 +385,7 @@ message DogStatsdSink { google.protobuf.UInt64Value max_bytes_per_datagram = 4 [(validate.rules).uint64 = {gt: 0}]; } -// Stats configuration proto schema for built-in *envoy.stat_sinks.hystrix* sink. +// Stats configuration proto schema for built-in ``envoy.stat_sinks.hystrix`` sink. // The sink emits stats in `text/event-stream // `_ // formatted stream for use by `Hystrix dashboard @@ -401,7 +406,7 @@ message HystrixSink { // in the process). The sink then outputs the aggregate statistics across the // current rolling window to the event stream(s). // - // rolling_window(ms) = stats_flush_interval(ms) * num_of_buckets + // ``rolling_window(ms)`` = ``stats_flush_interval(ms)`` * ``num_of_buckets`` // // More detailed explanation can be found in `Hystrix wiki // `_. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto b/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto index 3868df2348..10cc34331b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto @@ -56,7 +56,7 @@ message ThresholdTrigger { message ScaledTrigger { // If the resource pressure is greater than this value, the trigger will be in the // :ref:`scaling ` state with value - // `(pressure - scaling_threshold) / (saturation_threshold - scaling_threshold)`. + // ``(pressure - scaling_threshold) / (saturation_threshold - scaling_threshold)``. double scaling_threshold = 1 [(validate.rules).double = {lte: 1.0 gte: 0.0}]; // If the resource pressure is greater than this value, the trigger will enter saturation. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/rbac/v3/rbac.proto b/xds/third_party/envoy/src/main/proto/envoy/config/rbac/v3/rbac.proto index 8abde899d7..e8d9e9cf8b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/rbac/v3/rbac.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/rbac/v3/rbac.proto @@ -5,6 +5,7 @@ package envoy.config.rbac.v3; import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/route/v3/route_components.proto"; +import "envoy/type/matcher/v3/filter_state.proto"; import "envoy/type/matcher/v3/metadata.proto"; import "envoy/type/matcher/v3/path.proto"; import "envoy/type/matcher/v3/string.proto"; @@ -28,21 +29,21 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Role Based Access Control (RBAC)] // Role Based Access Control (RBAC) provides service-level and method-level access control for a -// service. Requests are allowed or denied based on the `action` and whether a matching policy is +// service. Requests are allowed or denied based on the ``action`` and whether a matching policy is // found. For instance, if the action is ALLOW and a matching policy is found the request should be // allowed. // // RBAC can also be used to make access logging decisions by communicating with access loggers // through dynamic metadata. When the action is LOG and at least one policy matches, the -// `access_log_hint` value in the shared key namespace 'envoy.common' is set to `true` indicating +// ``access_log_hint`` value in the shared key namespace 'envoy.common' is set to ``true`` indicating // the request should be logged. // // Here is an example of RBAC configuration. It has two policies: // -// * Service account "cluster.local/ns/default/sa/admin" has full access to the service, and so +// * Service account ``cluster.local/ns/default/sa/admin`` has full access to the service, and so // does "cluster.local/ns/default/sa/superuser". // -// * Any user can read ("GET") the service at paths with prefix "/products", so long as the +// * Any user can read (``GET``) the service at paths with prefix ``/products``, so long as the // destination port is either 80 or 443. // // .. code-block:: yaml @@ -89,7 +90,7 @@ message RBAC { // access control. DENY = 1; - // The policies set the `access_log_hint` dynamic metadata key based on if requests match. + // The policies set the ``access_log_hint`` dynamic metadata key based on if requests match. // All requests are allowed. LOG = 2; } @@ -99,13 +100,13 @@ message RBAC { // // Actions: // - // * ALLOW: Allows the request if and only if there is a policy that matches + // * ``ALLOW``: Allows the request if and only if there is a policy that matches // the request. - // * DENY: Allows the request if and only if there are no policies that + // * ``DENY``: Allows the request if and only if there are no policies that // match the request. - // * LOG: Allows all requests. If at least one policy matches, the dynamic - // metadata key `access_log_hint` is set to the value `true` under the shared - // key namespace 'envoy.common'. If no policies match, it is set to `false`. + // * ``LOG``: Allows all requests. If at least one policy matches, the dynamic + // metadata key ``access_log_hint`` is set to the value ``true`` under the shared + // key namespace ``envoy.common``. If no policies match, it is set to ``false``. // Other actions do not modify this key. // Action action = 1 [(validate.rules).enum = {defined_only: true}]; @@ -124,12 +125,12 @@ message Policy { // Required. The set of permissions that define a role. Each permission is // matched with OR semantics. To match all actions for this policy, a single - // Permission with the `any` field set to true should be used. + // Permission with the ``any`` field set to true should be used. repeated Permission permissions = 1 [(validate.rules).repeated = {min_items: 1}]; // Required. The set of principals that are assigned/denied the role based on // “action”. Each principal is matched with OR semantics. To match all - // downstreams for this policy, a single Principal with the `any` field set to + // downstreams for this policy, a single Principal with the ``any`` field set to // true should be used. repeated Principal principals = 2 [(validate.rules).repeated = {min_items: 1}]; @@ -152,7 +153,7 @@ message Policy { message Permission { option (udpa.annotations.versioning).previous_message_type = "envoy.config.rbac.v2.Permission"; - // Used in the `and_rules` and `or_rules` fields in the `rule` oneof. Depending on the context, + // Used in the ``and_rules`` and ``or_rules`` fields in the ``rule`` oneof. Depending on the context, // each are applied with the associated behavior. message Set { option (udpa.annotations.versioning).previous_message_type = @@ -175,7 +176,7 @@ message Permission { // A header (or pseudo-header such as :path or :method) on the incoming HTTP request. Only // available for HTTP request. - // Note: the pseudo-header :path includes the query and fragment string. Use the `url_path` + // Note: the pseudo-header :path includes the query and fragment string. Use the ``url_path`` // field if you want to match the URL path without the query and fragment string. route.v3.HeaderMatcher header = 4; @@ -195,8 +196,8 @@ message Permission { type.matcher.v3.MetadataMatcher metadata = 7; // Negates matching the provided permission. For instance, if the value of - // `not_rule` would match, this permission would not match. Conversely, if - // the value of `not_rule` would not match, this permission would match. + // ``not_rule`` would match, this permission would not match. Conversely, if + // the value of ``not_rule`` would not match, this permission would match. Permission not_rule = 8; // The request server from the client's connection request. This is @@ -208,7 +209,7 @@ message Permission { // as explained below. // // * If the :ref:`TLS Inspector ` - // filter is not added, and if a `FilterChainMatch` is not defined for + // filter is not added, and if a ``FilterChainMatch`` is not defined for // the :ref:`server name // `, // a TLS connection's requested SNI server name will be treated as if it @@ -229,11 +230,11 @@ message Permission { // Principal defines an identity or a group of identities for a downstream // subject. -// [#next-free-field: 12] +// [#next-free-field: 13] message Principal { option (udpa.annotations.versioning).previous_message_type = "envoy.config.rbac.v2.Principal"; - // Used in the `and_ids` and `or_ids` fields in the `identifier` oneof. + // Used in the ``and_ids`` and ``or_ids`` fields in the ``identifier`` oneof. // Depending on the context, each are applied with the associated behavior. message Set { option (udpa.annotations.versioning).previous_message_type = @@ -294,7 +295,7 @@ message Principal { // A header (or pseudo-header such as :path or :method) on the incoming HTTP // request. Only available for HTTP request. Note: the pseudo-header :path - // includes the query and fragment string. Use the `url_path` field if you + // includes the query and fragment string. Use the ``url_path`` field if you // want to match the URL path without the query and fragment string. route.v3.HeaderMatcher header = 6; @@ -304,9 +305,38 @@ message Principal { // Metadata that describes additional information about the principal. type.matcher.v3.MetadataMatcher metadata = 7; + // Identifies the principal using a filter state object. + type.matcher.v3.FilterStateMatcher filter_state = 12; + // Negates matching the provided principal. For instance, if the value of - // `not_id` would match, this principal would not match. Conversely, if the - // value of `not_id` would not match, this principal would match. + // ``not_id`` would match, this principal would not match. Conversely, if the + // value of ``not_id`` would not match, this principal would match. Principal not_id = 8; } } + +// Action defines the result of allowance or denial when a request matches the matcher. +message Action { + // The name indicates the policy name. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // The action to take if the matcher matches. Every action either allows or denies a request, + // and can also carry out action-specific operations. + // + // Actions: + // + // * ``ALLOW``: If the request gets matched on ALLOW, it is permitted. + // * ``DENY``: If the request gets matched on DENY, it is not permitted. + // * ``LOG``: If the request gets matched on LOG, it is permitted. Besides, the + // dynamic metadata key ``access_log_hint`` under the shared key namespace + // ``envoy.common`` will be set to the value ``true``. + // * If the request cannot get matched, it will fallback to ``DENY``. + // + // Log behavior: + // + // If the RBAC matcher contains at least one LOG action, the dynamic + // metadata key ``access_log_hint`` will be set based on if the request + // get matched on the LOG action. + // + RBAC.Action action = 2; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route.proto b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route.proto index 8579f0af7c..d7bc85411b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route.proto @@ -6,6 +6,7 @@ import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/config_source.proto"; import "envoy/config/route/v3/route_components.proto"; +import "google/protobuf/any.proto"; import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; @@ -22,7 +23,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // * Routing :ref:`architecture overview ` // * HTTP :ref:`router filter ` -// [#next-free-field: 15] +// [#next-free-field: 17] message RouteConfiguration { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.RouteConfiguration"; @@ -36,10 +37,10 @@ message RouteConfiguration { repeated VirtualHost virtual_hosts = 2; // An array of virtual hosts will be dynamically loaded via the VHDS API. - // Both *virtual_hosts* and *vhds* fields will be used when present. *virtual_hosts* can be used - // for a base routing table or for infrequently changing virtual hosts. *vhds* is used for + // Both ``virtual_hosts`` and ``vhds`` fields will be used when present. ``virtual_hosts`` can be used + // for a base routing table or for infrequently changing virtual hosts. ``vhds`` is used for // on-demand discovery of virtual hosts. The contents of these two fields will be merged to - // generate a routing table for a given RouteConfiguration, with *vhds* derived configuration + // generate a routing table for a given RouteConfiguration, with ``vhds`` derived configuration // taking precedence. Vhds vhds = 9; @@ -90,7 +91,6 @@ message RouteConfiguration { // To allow setting overrides at the route or virtual host level, this order can be reversed // by setting this option to true. Defaults to false. // - // [#next-major-version: In the v3 API, this will default to true.] bool most_specific_header_mutations_wins = 10; // An optional boolean that specifies whether the clusters that the route @@ -123,7 +123,7 @@ message RouteConfiguration { // A list of plugins and their configurations which may be used by a // :ref:`cluster specifier plugin name ` - // within the route. All *extension.name* fields in this list must be unique. + // within the route. All ``extension.name`` fields in this list must be unique. repeated ClusterSpecifierPlugin cluster_specifier_plugins = 12; // Specify a set of default request mirroring policies which apply to all routes under its virtual hosts. @@ -135,6 +135,26 @@ message RouteConfiguration { // NOTE: this option will not strip the port number (if any) contained in route config // :ref:`envoy_v3_api_msg_config.route.v3.VirtualHost`.domains field. bool ignore_port_in_host_matching = 14; + + // Ignore path-parameters in path-matching. + // Before RFC3986, URI were like(RFC1808): :///;?# + // Envoy by default takes ":path" as ";". + // For users who want to only match path on the "" portion, this option should be true. + bool ignore_path_parameters_in_path_matching = 15; + + // The typed_per_filter_config field can be used to provide RouteConfiguration level per filter config. + // The key should match the :ref:`filter config name + // `. + // The canonical filter name (e.g., ``envoy.filters.http.buffer`` for the HTTP buffer filter) can also + // be used for the backwards compatibility. If there is no entry referred by the filter config name, the + // entry referred by the canonical filter name will be provided to the filters as fallback. + // + // Use of this field is filter specific; + // see the :ref:`HTTP filter documentation ` for if and how it is utilized. + // [#comment: An entry's value may be wrapped in a + // :ref:`FilterConfig` + // message to specify additional options.] + map typed_per_filter_config = 16; } message Vhds { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto index b3ec0c594a..786481ccd2 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto @@ -41,7 +41,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // host header. This allows a single listener to service multiple top level domain path trees. Once // a virtual host is selected based on the domain, the routes are processed in order to see which // upstream cluster to route to or whether to perform a redirect. -// [#next-free-field: 23] +// [#next-free-field: 24] message VirtualHost { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualHost"; @@ -91,11 +91,11 @@ message VirtualHost { // The list of routes that will be matched, in order, for incoming requests. // The first route that matches will be used. - // Only one of this and `matcher` can be specified. + // Only one of this and ``matcher`` can be specified. repeated Route routes = 3; // [#next-major-version: This should be included in a oneof with routes wrapped in a message.] - // The match tree to use when resolving route actions for incoming requests. Only one of this and `routes` + // The match tree to use when resolving route actions for incoming requests. Only one of this and ``routes`` // can be specified. xds.type.matcher.v3.Matcher matcher = 21 [(xds.annotations.v3.field_status).work_in_progress = true]; @@ -142,14 +142,26 @@ message VirtualHost { items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}} }]; - // Indicates that the virtual host has a CORS policy. - CorsPolicy cors = 8; + // Indicates that the virtual host has a CORS policy. This field is ignored if related cors policy is + // found in the + // :ref:`VirtualHost.typed_per_filter_config`. + // + // .. attention:: + // + // This option has been deprecated. Please use + // :ref:`VirtualHost.typed_per_filter_config` + // to configure the CORS HTTP filter. + CorsPolicy cors = 8 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // The per_filter_config field can be used to provide virtual host-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. + // The per_filter_config field can be used to provide virtual host-specific configurations for filters. + // The key should match the :ref:`filter config name + // `. + // The canonical filter name (e.g., ``envoy.filters.http.buffer`` for the HTTP buffer filter) can also + // be used for the backwards compatibility. If there is no entry referred by the filter config name, the + // entry referred by the canonical filter name will be provided to the filters as fallback. + // + // Use of this field is filter specific; + // see the :ref:`HTTP filter documentation ` for if and how it is utilized. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` // message to specify additional options.] @@ -194,6 +206,10 @@ message VirtualHost { // independently (e.g.: values are not inherited). HedgePolicy hedge_policy = 17; + // Decides whether to include the :ref:`x-envoy-is-timeout-retry ` + // request header in retries initiated by per try timeouts. + bool include_is_timeout_retry_header = 23; + // The maximum bytes which will be buffered for retries and shadowing. // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum // value of this and the listener per_connection_buffer_limit_bytes. @@ -212,6 +228,13 @@ message FilterAction { google.protobuf.Any action = 1; } +// This can be used in route matcher :ref:`VirtualHost.matcher `. +// When the matcher matches, routes will be matched and run. +message RouteList { + // The list of routes that will be matched and run, in order. The first route that matches will be used. + repeated Route routes = 1; +} + // A route is both a specification of how to match a request as well as an indication of what to do // next (e.g., redirect, forward, rewrite, etc.). // @@ -219,7 +242,7 @@ message FilterAction { // // Envoy supports routing on HTTP method via :ref:`header matching // `. -// [#next-free-field: 19] +// [#next-free-field: 20] message Route { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Route"; @@ -263,17 +286,21 @@ message Route { // about the route. It can be used for configuration, stats, and logging. // The metadata should go under the filter namespace that will need it. // For instance, if the metadata is intended for the Router filter, - // the filter name should be specified as *envoy.filters.http.router*. + // the filter name should be specified as ``envoy.filters.http.router``. core.v3.Metadata metadata = 4; // Decorator for the matched route. Decorator decorator = 5; - // The typed_per_filter_config field can be used to provide route-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` for - // if and how it is utilized. + // The per_filter_config field can be used to provide route-specific configurations for filters. + // The key should match the :ref:`filter config name + // `. + // The canonical filter name (e.g., ``envoy.filters.http.buffer`` for the HTTP buffer filter) can also + // be used for the backwards compatibility. If there is no entry referred by the filter config name, the + // entry referred by the canonical filter name will be provided to the filters as fallback. + // + // Use of this field is filter specific; + // see the :ref:`HTTP filter documentation ` for if and how it is utilized. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` // message to specify additional options.] @@ -317,6 +344,21 @@ message Route { // If set, the bytes actually buffered will be the minimum value of this and the // listener per_connection_buffer_limit_bytes. google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; + + // The human readable prefix to use when emitting statistics for this endpoint. + // The statistics are rooted at vhost..route.. + // This should be set for highly critical + // endpoints that one wishes to get “per-route” statistics on. + // If not set, endpoint statistics are not generated. + // + // The emitted statistics are the same as those documented for :ref:`virtual clusters `. + // + // .. warning:: + // + // We do not recommend setting up a stat prefix for + // every application endpoint. This is both not easily maintainable and + // statistics use a non-trivial amount of memory(approximately 1KiB per route). + string stat_prefix = 19; } // Compared to the :ref:`cluster ` field that specifies a @@ -337,13 +379,13 @@ message WeightedCluster { reserved "per_filter_config"; - // Only one of *name* and *cluster_header* may be specified. + // Only one of ``name`` and ``cluster_header`` may be specified. // [#next-major-version: Need to add back the validation rule: (validate.rules).string = {min_len: 1}] // Name of the upstream cluster. The cluster must exist in the // :ref:`cluster manager configuration `. string name = 1 [(udpa.annotations.field_migrate).oneof_promotion = "cluster_specifier"]; - // Only one of *name* and *cluster_header* may be specified. + // Only one of ``name`` and ``cluster_header`` may be specified. // [#next-major-version: Need to add back the validation rule: (validate.rules).string = {min_len: 1 }] // Envoy will determine the cluster to route to by reading the value of the // HTTP header named by cluster_header from the request headers. If the @@ -352,8 +394,8 @@ message WeightedCluster { // // .. attention:: // - // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 - // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. + // Internally, Envoy always uses the HTTP/2 ``:authority`` header to represent the HTTP/1 + // ``Host`` header. Thus, if attempting to match on ``Host``, match on ``:authority`` instead. // // .. note:: // @@ -363,17 +405,18 @@ message WeightedCluster { (udpa.annotations.field_migrate).oneof_promotion = "cluster_specifier" ]; - // An integer between 0 and :ref:`total_weight - // `. When a request matches the route, - // the choice of an upstream cluster is determined by its weight. The sum of weights across all - // entries in the clusters array must add up to the total_weight, which defaults to 100. + // The weight of the cluster. This value is relative to the other clusters' + // weights. When a request matches the route, the choice of an upstream cluster + // is determined by its weight. The sum of weights across all + // entries in the clusters array must be greater than 0, and must not exceed + // uint32_t maximal value (4294967295). google.protobuf.UInt32Value weight = 2; // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in // the upstream cluster with metadata matching what is set in this field will be considered for // load balancing. Note that this will be merged with what's provided in // :ref:`RouteAction.metadata_match `, with - // values here taking precedence. The filter name should be specified as *envoy.lb*. + // values here taking precedence. The filter name should be specified as ``envoy.lb``. core.v3.Metadata metadata_match = 3; // Specifies a list of headers to be added to requests when this cluster is selected @@ -408,11 +451,16 @@ message WeightedCluster { items {string {well_known_regex: HTTP_HEADER_NAME strict: false}} }]; - // The per_filter_config field can be used to provide weighted cluster-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. + // The per_filter_config field can be used to provide weighted cluster-specific configurations + // for filters. + // The key should match the :ref:`filter config name + // `. + // The canonical filter name (e.g., ``envoy.filters.http.buffer`` for the HTTP buffer filter) can also + // be used for the backwards compatibility. If there is no entry referred by the filter config name, the + // entry referred by the canonical filter name will be provided to the filters as fallback. + // + // Use of this field is filter specific; + // see the :ref:`HTTP filter documentation ` for if and how it is utilized. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` // message to specify additional options.] @@ -430,14 +478,17 @@ message WeightedCluster { repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; // Specifies the total weight across all clusters. The sum of all cluster weights must equal this - // value, which must be greater than 0. Defaults to 100. - google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 1}]; + // value, if this is greater than 0. + // This field is now deprecated, and the client will use the sum of all + // cluster weights. It is up to the management server to supply the correct weights. + google.protobuf.UInt32Value total_weight = 3 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Specifies the runtime key prefix that should be used to construct the - // runtime keys associated with each cluster. When the *runtime_key_prefix* is + // runtime keys associated with each cluster. When the ``runtime_key_prefix`` is // specified, the router will look for weights associated with each upstream - // cluster under the key *runtime_key_prefix* + "." + *cluster[i].name* where - // *cluster[i]* denotes an entry in the clusters array field. If the runtime + // cluster under the key ``runtime_key_prefix`` + ``.`` + ``cluster[i].name`` where + // ``cluster[i]`` denotes an entry in the clusters array field. If the runtime // key for the cluster does not exist, the value specified in the // configuration file will be used as the default weight. See the :ref:`runtime documentation // ` for how key names map to the underlying implementation. @@ -449,7 +500,8 @@ message WeightedCluster { // If header is not present or invalid, Envoy will fall back to use the internally generated random value. // This header is expected to be single-valued header as we only want to have one selected value throughout // the process for the consistency. And the value is a unsigned number between 0 and UINT64_MAX. - string header_name = 4; + string header_name = 4 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}]; } } @@ -466,7 +518,7 @@ message ClusterSpecifierPlugin { bool is_optional = 2; } -// [#next-free-field: 15] +// [#next-free-field: 16] message RouteMatch { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteMatch"; @@ -500,17 +552,17 @@ message RouteMatch { option (validate.required) = true; // If specified, the route is a prefix rule meaning that the prefix must - // match the beginning of the *:path* header. + // match the beginning of the ``:path`` header. string prefix = 1; // If specified, the route is an exact path rule meaning that the path must - // exactly match the *:path* header once the query string is removed. + // exactly match the ``:path`` header once the query string is removed. string path = 2; // If specified, the route is a regular expression rule meaning that the - // regex must match the *:path* header once the query string is removed. The entire path + // regex must match the ``:path`` header once the query string is removed. The entire path // (without the query string) must match the regex. The rule will not match if only a - // subsequence of the *:path* header matches the regex. + // subsequence of the ``:path`` header matches the regex. // // [#next-major-version: In the v3 API we should redo how path specification works such // that we utilize StringMatcher, and additionally have consistent options around whether we @@ -542,6 +594,9 @@ message RouteMatch { // // Expect the value to not contain ``?`` or ``#`` and not to end in ``/`` string path_separated_prefix = 14 [(validate.rules).string = {pattern: "^[^?#]+[^?#/]$"}]; + + // [#extension-category: envoy.path.match] + core.v3.TypedExtensionConfig path_match_policy = 15; } // Indicates that prefix/path matching should be case sensitive. The default @@ -574,9 +629,9 @@ message RouteMatch { repeated HeaderMatcher headers = 6; // Specifies a set of URL query parameters on which the route should - // match. The router will check the query string from the *path* header + // match. The router will check the query string from the ``path`` header // against all the specified query parameters. If the number of specified - // query parameters is nonzero, they all must match the *path* header's + // query parameters is nonzero, they all must match the ``path`` header's // query string for a match to occur. // // .. note:: @@ -606,7 +661,15 @@ message RouteMatch { repeated type.matcher.v3.MetadataMatcher dynamic_metadata = 13; } -// [#next-free-field: 12] +// Cors policy configuration. +// +// .. attention:: +// +// This message has been deprecated. Please use +// :ref:`CorsPolicy in filter extension ` +// as as alternative. +// +// [#next-free-field: 13] message CorsPolicy { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.CorsPolicy"; @@ -618,16 +681,16 @@ message CorsPolicy { // string matchers match. repeated type.matcher.v3.StringMatcher allow_origin_string_match = 11; - // Specifies the content for the *access-control-allow-methods* header. + // Specifies the content for the ``access-control-allow-methods`` header. string allow_methods = 2; - // Specifies the content for the *access-control-allow-headers* header. + // Specifies the content for the ``access-control-allow-headers`` header. string allow_headers = 3; - // Specifies the content for the *access-control-expose-headers* header. + // Specifies the content for the ``access-control-expose-headers`` header. string expose_headers = 4; - // Specifies the content for the *access-control-max-age* header. + // Specifies the content for the ``access-control-max-age`` header. string max_age = 5; // Specifies whether the resource allows credentials. @@ -652,11 +715,17 @@ message CorsPolicy { // // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate - // and track the request's *Origin* to determine if it's valid but will not enforce any policies. + // and track the request's ``Origin`` to determine if it's valid but will not enforce any policies. core.v3.RuntimeFractionalPercent shadow_enabled = 10; + + // Specify whether allow requests whose target server's IP address is more private than that from + // which the request initiator was fetched. + // + // More details refer to https://developer.chrome.com/blog/private-network-access-preflight. + google.protobuf.BoolValue allow_private_network_access = 12; } -// [#next-free-field: 40] +// [#next-free-field: 42] message RouteAction { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction"; @@ -666,6 +735,9 @@ message RouteAction { // HTTP status code - 404 Not Found. NOT_FOUND = 1; + + // HTTP status code - 500 Internal Server Error. + INTERNAL_SERVER_ERROR = 2; } // Configures :ref:`internal redirect ` behavior. @@ -682,12 +754,16 @@ message RouteAction { // respond before returning the response from the primary cluster. All normal statistics are // collected for the shadow cluster making this feature useful for testing. // - // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is - // useful for logging. For example, *cluster1* becomes *cluster1-shadow*. + // During shadowing, the host/authority header is altered such that ``-shadow`` is appended. This is + // useful for logging. For example, ``cluster1`` becomes ``cluster1-shadow``. // // .. note:: // // Shadowing will not be triggered if the primary cluster does not exist. + // + // .. note:: + // + // Shadowing doesn't support Http CONNECT and upgrades. // [#next-free-field: 6] message RequestMirrorPolicy { option (udpa.annotations.versioning).previous_message_type = @@ -697,13 +773,13 @@ message RouteAction { reserved "runtime_key"; - // Only one of *cluster* and *cluster_header* can be specified. + // Only one of ``cluster`` and ``cluster_header`` can be specified. // [#next-major-version: Need to add back the validation rule: (validate.rules).string = {min_len: 1}] // Specifies the cluster that requests will be mirrored to. The cluster must // exist in the cluster manager configuration. string cluster = 1 [(udpa.annotations.field_migrate).oneof_promotion = "cluster_specifier"]; - // Only one of *cluster* and *cluster_header* can be specified. + // Only one of ``cluster`` and ``cluster_header`` can be specified. // Envoy will determine the cluster to route to by reading the value of the // HTTP header named by cluster_header from the request headers. Only the first value in header is used, // and no shadow request will happen if the value is not found in headers. Envoy will not wait for @@ -711,8 +787,8 @@ message RouteAction { // // .. attention:: // - // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 - // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. + // Internally, Envoy always uses the HTTP/2 ``:authority`` header to represent the HTTP/1 + // ``Host`` header. Thus, if attempting to match on ``Host``, match on ``:authority`` instead. // // .. note:: // @@ -724,7 +800,7 @@ message RouteAction { // If not specified, all requests to the target cluster will be mirrored. // - // If specified, this field takes precedence over the `runtime_key` field and requests must also + // If specified, this field takes precedence over the ``runtime_key`` field and requests must also // fall under the percentage of matches indicated by this field. // // For some fraction N/D, a random number in the range [0,D) is selected. If the @@ -908,11 +984,11 @@ message RouteAction { // If present, and the request contains a `grpc-timeout header // `_, use that value as the - // *max_stream_duration*, but limit the applied timeout to the maximum value specified here. - // If set to 0, the `grpc-timeout` header is used without modification. + // ``max_stream_duration``, but limit the applied timeout to the maximum value specified here. + // If set to 0, the ``grpc-timeout`` header is used without modification. google.protobuf.Duration grpc_timeout_header_max = 2; - // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by + // If present, Envoy will adjust the timeout provided by the ``grpc-timeout`` header by // subtracting the provided duration from the header. This is useful for allowing Envoy to set // its global timeout to be less than that of the deadline imposed by the calling client, which // makes it more likely that Envoy will handle the timeout instead of having the call canceled @@ -939,8 +1015,8 @@ message RouteAction { // // .. attention:: // - // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 - // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. + // Internally, Envoy always uses the HTTP/2 ``:authority`` header to represent the HTTP/1 + // ``Host`` header. Thus, if attempting to match on ``Host``, match on ``:authority`` instead. // // .. note:: // @@ -975,7 +1051,7 @@ message RouteAction { // in the upstream cluster with metadata matching what's set in this field will be considered // for load balancing. If using :ref:`weighted_clusters // `, metadata will be merged, with values - // provided there taking precedence. The filter name should be specified as *envoy.lb*. + // provided there taking precedence. The filter name should be specified as ``envoy.lb``. core.v3.Metadata metadata_match = 4; // Indicates that during forwarding, the matched prefix (or path) should be @@ -984,16 +1060,16 @@ message RouteAction { // place the original path before rewrite into the :ref:`x-envoy-original-path // ` header. // - // Only one of *prefix_rewrite* or - // :ref:`regex_rewrite ` - // may be specified. + // Only one of :ref:`regex_rewrite ` + // :ref:`path_rewrite_policy `, + // or :ref:`prefix_rewrite ` may be specified. // // .. attention:: // // Pay careful attention to the use of trailing slashes in the // :ref:`route's match ` prefix value. // Stripping a prefix from a path requires multiple Routes to handle all cases. For example, - // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single + // rewriting ``/prefix`` to ``/`` and ``/prefix/etc`` to ``/etc`` cannot be done in a single // :ref:`Route `, as shown by the below config entries: // // .. code-block:: yaml @@ -1007,8 +1083,8 @@ message RouteAction { // route: // prefix_rewrite: "/" // - // Having above entries in the config, requests to */prefix* will be stripped to */*, while - // requests to */prefix/etc* will be stripped to */etc*. + // Having above entries in the config, requests to ``/prefix`` will be stripped to ``/``, while + // requests to ``/prefix/etc`` will be stripped to ``/etc``. string prefix_rewrite = 5 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; @@ -1021,8 +1097,10 @@ message RouteAction { // before the rewrite into the :ref:`x-envoy-original-path // ` header. // - // Only one of :ref:`prefix_rewrite ` - // or *regex_rewrite* may be specified. + // Only one of :ref:`regex_rewrite `, + // :ref:`prefix_rewrite `, or + // :ref:`path_rewrite_policy `] + // may be specified. // // Examples using Google's `RE2 `_ engine: // @@ -1042,6 +1120,9 @@ message RouteAction { // ``/aaa/yyy/bbb``. type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 32; + // [#extension-category: envoy.path.rewrite] + core.v3.TypedExtensionConfig path_rewrite_policy = 41; + oneof host_rewrite_specifier { // Indicates that during forwarding, the host header will be swapped with // this value. Using this option will append the @@ -1054,7 +1135,7 @@ message RouteAction { // Indicates that during forwarding, the host header will be swapped with // the hostname of the upstream host chosen by the cluster manager. This // option is applicable only when the destination cluster for a route is of - // type *strict_dns* or *logical_dns*. Setting this to true with other cluster types + // type ``strict_dns`` or ``logical_dns``. Setting this to true with other cluster types // has no effect. Using this option will append the // :ref:`config_http_conn_man_headers_x-forwarded-host` header if // :ref:`append_x_forwarded_host ` @@ -1097,7 +1178,7 @@ message RouteAction { // regex: "^/(.+)/.+$" // substitution: \1 // - // Would rewrite the host header to `envoyproxy.io` given the path `/envoyproxy.io/some/path`. + // Would rewrite the host header to ``envoyproxy.io`` given the path ``/envoyproxy.io/some/path``. type.matcher.v3.RegexMatchAndSubstitute host_rewrite_path_regex = 35; } @@ -1147,6 +1228,11 @@ message RouteAction { // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE `. google.protobuf.Duration idle_timeout = 24; + // Specifies how to send request over TLS early data. + // If absent, allows `safe HTTP requests `_ to be sent on early data. + // [#extension-category: envoy.route.early_data_policy] + core.v3.TypedExtensionConfig early_data_policy = 40; + // Indicates that the route has a retry policy. Note that if this is set, // it'll take precedence over the virtual host level retry policy entirely // (e.g.: policies are not merged, most internal one becomes the enforced policy). @@ -1194,8 +1280,17 @@ message RouteAction { // ignoring the rest of the hash policy list. repeated HashPolicy hash_policy = 15; - // Indicates that the route has a CORS policy. - CorsPolicy cors = 17; + // Indicates that the route has a CORS policy. This field is ignored if related cors policy is + // found in the :ref:`Route.typed_per_filter_config` or + // :ref:`WeightedCluster.ClusterWeight.typed_per_filter_config`. + // + // .. attention:: + // + // This option has been deprecated. Please use + // :ref:`Route.typed_per_filter_config` or + // :ref:`WeightedCluster.ClusterWeight.typed_per_filter_config` + // to configure the CORS HTTP filter. + CorsPolicy cors = 17 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Deprecated by :ref:`grpc_timeout_header_max ` // If present, and the request is a gRPC request, use the @@ -1203,7 +1298,7 @@ message RouteAction { // or its default value (infinity) instead of // :ref:`timeout `, but limit the applied timeout // to the maximum value specified here. If configured as 0, the maximum allowed timeout for - // gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used + // gRPC requests is infinity. If not configured at all, the ``grpc-timeout`` header is not used // and gRPC requests time out like any other requests using // :ref:`timeout ` or its default. // This can be used to prevent unexpected upstream request timeouts due to potentially long @@ -1221,7 +1316,7 @@ message RouteAction { [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Deprecated by :ref:`grpc_timeout_header_offset `. - // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting + // If present, Envoy will adjust the timeout provided by the ``grpc-timeout`` header by subtracting // the provided duration from the header. This is useful in allowing Envoy to set its global // timeout to be less than that of the deadline imposed by the calling client, which makes it more // likely that Envoy will handle the timeout instead of having the call canceled by the client. @@ -1324,8 +1419,8 @@ message RetryPolicy { }]; // Specifies the maximum interval between retries. This parameter is optional, but must be - // greater than or equal to the `base_interval` if set. The default is 10 times the - // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion + // greater than or equal to the ``base_interval`` if set. The default is 10 times the + // ``base_interval``. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion // of Envoy's back-off algorithm. google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; } @@ -1470,7 +1565,7 @@ message RetryPolicy { // Specifies parameters that control exponential retry back off. This parameter is optional, in which case the // default base interval is 25 milliseconds or, if set, the current value of the - // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times + // ``upstream.base_retry_backoff_ms`` runtime parameter. The default maximum interval is 10 times // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries` // describes Envoy's back-off algorithm. RetryBackOff retry_back_off = 8; @@ -1480,7 +1575,7 @@ message RetryPolicy { // return a response header like ``Retry-After`` or ``X-RateLimit-Reset`` to // provide feedback to the client on how long to wait before retrying. If // configured, this back-off strategy will be used instead of the - // default exponential back off strategy (configured using `retry_back_off`) + // default exponential back off strategy (configured using ``retry_back_off``) // whenever a response includes the matching headers. RateLimitedRetryBackOff rate_limited_retry_back_off = 11; @@ -1547,10 +1642,10 @@ message RedirectAction { } // When the scheme redirection take place, the following rules apply: - // 1. If the source URI scheme is `http` and the port is explicitly - // set to `:80`, the port will be removed after the redirection - // 2. If the source URI scheme is `https` and the port is explicitly - // set to `:443`, the port will be removed after the redirection + // 1. If the source URI scheme is ``http`` and the port is explicitly + // set to ``:80``, the port will be removed after the redirection + // 2. If the source URI scheme is ``https`` and the port is explicitly + // set to ``:443``, the port will be removed after the redirection oneof scheme_rewrite_specifier { // The scheme portion of the URL will be swapped with "https". bool https_redirect = 4; @@ -1644,7 +1739,7 @@ message DirectResponseAction { // // .. note:: // - // Headers can be specified using *response_headers_to_add* in the enclosing + // Headers can be specified using ``response_headers_to_add`` in the enclosing // :ref:`envoy_v3_api_msg_config.route.v3.Route`, :ref:`envoy_v3_api_msg_config.route.v3.RouteConfiguration` or // :ref:`envoy_v3_api_msg_config.route.v3.VirtualHost`. core.v3.DataSource body = 2; @@ -1733,7 +1828,7 @@ message VirtualCluster { reserved "pattern", "method"; // Specifies a list of header matchers to use for matching requests. Each specified header must - // match. The pseudo-headers `:path` and `:method` can be used to match the request path and + // match. The pseudo-headers ``:path`` and ``:method`` can be used to match the request path and // method, respectively. repeated HeaderMatcher headers = 4; @@ -1748,7 +1843,7 @@ message VirtualCluster { message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit"; - // [#next-free-field: 11] + // [#next-free-field: 12] message Action { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action"; @@ -1787,7 +1882,7 @@ message RateLimit { } // The following descriptor entry is appended when a header contains a key that matches the - // *header_name*: + // ``header_name``: // // .. code-block:: cpp // @@ -1831,14 +1926,14 @@ message RateLimit { message MaskedRemoteAddress { // Length of prefix mask len for IPv4 (e.g. 0, 32). // Defaults to 32 when unset. - // For example, trusted address from x-forwarded-for is `192.168.1.1`, + // For example, trusted address from x-forwarded-for is ``192.168.1.1``, // the descriptor entry is ("masked_remote_address", "192.168.1.1/32"); // if mask len is 24, the descriptor entry is ("masked_remote_address", "192.168.1.0/24"). google.protobuf.UInt32Value v4_prefix_mask_len = 1 [(validate.rules).uint32 = {lte: 32}]; // Length of prefix mask len for IPv6 (e.g. 0, 128). // Defaults to 128 when unset. - // For example, trusted address from x-forwarded-for is `2001:abcd:ef01:2345:6789:abcd:ef01:234`, + // For example, trusted address from x-forwarded-for is ``2001:abcd:ef01:2345:6789:abcd:ef01:234``, // the descriptor entry is ("masked_remote_address", "2001:abcd:ef01:2345:6789:abcd:ef01:234/128"); // if mask len is 64, the descriptor entry is ("masked_remote_address", "2001:abcd:ef01:2345::/64"). google.protobuf.UInt32Value v6_prefix_mask_len = 2 [(validate.rules).uint32 = {lte: 128}]; @@ -1870,7 +1965,7 @@ message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch"; - // The key to use in the descriptor entry. Defaults to `header_match`. + // The key to use in the descriptor entry. Defaults to ``header_match``. string descriptor_key = 4; // The value to use in the descriptor entry. @@ -1907,7 +2002,7 @@ message RateLimit { // only happen if the value in the dynamic metadata is of type string. type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}]; - // An optional value to use if *metadata_key* is empty. If not set and + // An optional value to use if ``metadata_key`` is empty. If not set and // no value is present under the metadata_key then no descriptor is generated. string default_value = 3; } @@ -1917,6 +2012,7 @@ message RateLimit { // .. code-block:: cpp // // ("", "") + // [#next-free-field: 6] message MetaData { enum Source { // Query :ref:`dynamic metadata ` @@ -1933,12 +2029,45 @@ message RateLimit { // only happen if the value in the metadata is of type string. type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}]; - // An optional value to use if *metadata_key* is empty. If not set and - // no value is present under the metadata_key then no descriptor is generated. + // An optional value to use if ``metadata_key`` is empty. If not set and + // no value is present under the metadata_key then ``skip_if_absent`` is followed to + // skip calling the rate limiting service or skip the descriptor. string default_value = 3; // Source of metadata Source source = 4 [(validate.rules).enum = {defined_only: true}]; + + // If set to true, Envoy skips the descriptor while calling rate limiting service + // when ``metadata_key`` is empty and ``default_value`` is not set. By default it skips calling the + // rate limiting service in that case. + bool skip_if_absent = 5; + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("query_match", "") + message QueryParameterValueMatch { + // The key to use in the descriptor entry. Defaults to ``query_match``. + string descriptor_key = 4; + + // The value to use in the descriptor entry. + string descriptor_value = 1 [(validate.rules).string = {min_len: 1}]; + + // If set to true, the action will append a descriptor entry when the + // request matches the headers. If set to false, the action will append a + // descriptor entry when the request does not match the headers. The + // default value is true. + google.protobuf.BoolValue expect_match = 2; + + // Specifies a set of query parameters that the rate limit action should match + // on. The action will check the request’s query parameters against all the + // specified query parameters in the config. A match will happen if all the + // query parameters in the config are present in the request with the same values + // (or based on presence if the value field is not in the config). + repeated QueryParameterMatcher query_parameters = 3 + [(validate.rules).repeated = {min_items: 1}]; } oneof action_specifier { @@ -1987,6 +2116,9 @@ message RateLimit { // Rate limit on masked remote address. MaskedRemoteAddress masked_remote_address = 10; + + // Rate limit on the existence of query parameters. + QueryParameterValueMatch query_parameter_value_match = 11; } } @@ -2037,19 +2169,21 @@ message RateLimit { // .. attention:: // -// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host* -// header. Thus, if attempting to match on *Host*, match on *:authority* instead. +// Internally, Envoy always uses the HTTP/2 ``:authority`` header to represent the HTTP/1 ``Host`` +// header. Thus, if attempting to match on ``Host``, match on ``:authority`` instead. // // .. attention:: // -// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both +// To route on HTTP method, use the special HTTP/2 ``:method`` header. This works for both // HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., // // .. code-block:: json // // { // "name": ":method", -// "exact_match": "POST" +// "string_match": { +// "exact": "POST" +// } // } // // .. attention:: @@ -2059,7 +2193,7 @@ message RateLimit { // value. // // [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] -// [#next-free-field: 14] +// [#next-free-field: 15] message HeaderMatcher { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HeaderMatcher"; @@ -2094,8 +2228,8 @@ message HeaderMatcher { // // Examples: // - // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, - // "-1somestring" + // * For range [-10,0), route will match for header value -1, but not for 0, ``somestring``, 10.9, + // ``-1somestring`` type.v3.Int64Range range_match = 6; // If specified as true, header match will be performed based on whether the header is in the @@ -2108,7 +2242,7 @@ message HeaderMatcher { // // Examples: // - // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. + // * The prefix ``abcd`` matches the value ``abcdxyz``, but not for ``abcxyz``. string prefix_match = 9 [ deprecated = true, (validate.rules).string = {min_len: 1}, @@ -2121,7 +2255,7 @@ message HeaderMatcher { // // Examples: // - // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. + // * The suffix ``abcd`` matches the value ``xyzabcd``, but not for ``xyzbcd``. string suffix_match = 10 [ deprecated = true, (validate.rules).string = {min_len: 1}, @@ -2135,7 +2269,7 @@ message HeaderMatcher { // // Examples: // - // * The value *abcd* matches the value *xyzabcdpqr*, but not for *xyzbcdpqr*. + // * The value ``abcd`` matches the value ``xyzabcdpqr``, but not for ``xyzbcdpqr``. string contains_match = 12 [ deprecated = true, (validate.rules).string = {min_len: 1}, @@ -2150,9 +2284,37 @@ message HeaderMatcher { // // Examples: // - // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. + // * The regex ``\d{3}`` does not match the value ``1234``, so it will match when inverted. // * The range [-10,0) will match the value -1, so it will not match when inverted. bool invert_match = 8; + + // If specified, for any header match rule, if the header match rule specified header + // does not exist, this header value will be treated as empty. Defaults to false. + // + // Examples: + // + // * The header match rule specified header "header1" to range match of [0, 10], + // :ref:`invert_match ` + // is set to true and :ref:`treat_missing_header_as_empty ` + // is set to true; The "header1" header is not present. The match rule will + // treat the "header1" as an empty header. The empty header does not match the range, + // so it will match when inverted. + // * The header match rule specified header "header2" to range match of [0, 10], + // :ref:`invert_match ` + // is set to true and :ref:`treat_missing_header_as_empty ` + // is set to false; The "header2" header is not present and the header + // matcher rule for "header2" will be ignored so it will not match. + // * The header match rule specified header "header3" to a string regex match + // ``^$`` which means an empty string, and + // :ref:`treat_missing_header_as_empty ` + // is set to true; The "header3" header is not present. + // The match rule will treat the "header3" header as an empty header so it will match. + // * The header match rule specified header "header4" to a string regex match + // ``^$`` which means an empty string, and + // :ref:`treat_missing_header_as_empty ` + // is set to false; The "header4" header is not present. + // The match rule for "header4" will be ignored so it will not match. + bool treat_missing_header_as_empty = 14; } // Query parameter matching treats the query string of a request's :path header @@ -2167,7 +2329,7 @@ message QueryParameterMatcher { reserved "value", "regex"; // Specifies the name of a key that must be present in the requested - // *path*'s query string. + // ``path``'s query string. string name = 1 [(validate.rules).string = {min_len: 1 max_bytes: 1024}]; oneof query_parameter_match_specifier { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/scoped_route.proto b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/scoped_route.proto index 4ac0ca7c23..27bcd617ae 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/scoped_route.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/scoped_route.proto @@ -77,7 +77,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Host: foo.com // X-Route-Selector: vip=172.10.10.20 // -// would result in the routing table defined by the `route-config1` +// would result in the routing table defined by the ``route-config1`` // RouteConfiguration being assigned to the HTTP request/stream. // // [#next-free-field: 6] diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/datadog.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/datadog.proto index 1a01f6a33c..bed6c8eec3 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/datadog.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/datadog.proto @@ -27,4 +27,8 @@ message DatadogConfig { // The name used for the service when traces are generated by envoy. string service_name = 2 [(validate.rules).string = {min_len: 1}]; + + // Optional hostname to use when sending spans to the collector_cluster. Useful for collectors + // that require a specific hostname. Defaults to :ref:`collector_cluster ` above. + string collector_hostname = 3; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/lightstep.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/lightstep.proto index 0e2680832f..96dbbedd54 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/lightstep.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/lightstep.proto @@ -22,6 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the LightStep tracer. // [#extension: envoy.tracers.lightstep] +// [#not-implemented-hide:] message LightstepConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.LightstepConfig"; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto new file mode 100644 index 0000000000..e9c7430dcf --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto @@ -0,0 +1,28 @@ +syntax = "proto3"; + +package envoy.config.trace.v3; + +import "envoy/config/core/v3/grpc_service.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.config.trace.v3"; +option java_outer_classname = "OpentelemetryProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/trace/v3;tracev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: OpenTelemetry tracer] + +// Configuration for the OpenTelemetry tracer. +// [#extension: envoy.tracers.opentelemetry] +message OpenTelemetryConfig { + // The upstream gRPC cluster that will receive OTLP traces. + // Note that the tracer drops traces if the server does not read data fast enough. + // This field can be left empty to disable reporting traces to the collector. + core.v3.GrpcService grpc_service = 1; + + // The name for the service. This will be populated in the ResourceSpan Resource attributes. + // If it is not provided, it will default to "unknown_service:envoy". + string service_name = 2; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/trace.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/trace.proto index 5e5895e26b..8ca43718ca 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/trace.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/trace.proto @@ -7,6 +7,7 @@ import public "envoy/config/trace/v3/dynamic_ot.proto"; import public "envoy/config/trace/v3/http_tracer.proto"; import public "envoy/config/trace/v3/lightstep.proto"; import public "envoy/config/trace/v3/opencensus.proto"; +import public "envoy/config/trace/v3/opentelemetry.proto"; import public "envoy/config/trace/v3/service.proto"; import public "envoy/config/trace/v3/zipkin.proto"; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto index 1d76b81376..96556c7b29 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto @@ -21,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the Zipkin tracer. // [#extension: envoy.tracers.zipkin] -// [#next-free-field: 7] +// [#next-free-field: 8] message ZipkinConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.ZipkinConfig"; @@ -68,4 +68,19 @@ message ZipkinConfig { // Optional hostname to use when sending spans to the collector_cluster. Useful for collectors // that require a specific hostname. Defaults to :ref:`collector_cluster ` above. string collector_hostname = 6; + + // If this is set to true, then Envoy will be treated as an independent hop in trace chain. A complete span pair will be created for a single + // request. Server span will be created for the downstream request and client span will be created for the related upstream request. + // This should be set to true in the following cases: + // + // * The Envoy Proxy is used as gateway or ingress. + // * The Envoy Proxy is used as sidecar but inbound traffic capturing or outbound traffic capturing is disabled. + // * Any case that the `start_child_span of router ` is set to true. + // + // .. attention:: + // + // If this is set to true, then the + // :ref:`start_child_span of router ` + // SHOULD be set to true also to ensure the correctness of trace chain. + bool split_spans_for_request = 7; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/fault/v3/fault.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/fault/v3/fault.proto index 64dbf89e43..5d55cfe001 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/fault/v3/fault.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/fault/v3/fault.proto @@ -65,7 +65,7 @@ message HTTPFault { common.fault.v3.FaultDelay delay = 1; // If specified, the filter will abort requests based on the values in - // the object. At least *abort* or *delay* must be specified. + // the object. At least ``abort`` or ``delay`` must be specified. FaultAbort abort = 2; // Specifies the name of the (destination) upstream cluster that the @@ -81,7 +81,7 @@ message HTTPFault { // The filter will check the request's headers against all the specified // headers in the filter config. A match will happen if all the headers in the // config are present in the request with the same values (or based on - // presence if the *value* field is not in the config). + // presence if the ``value`` field is not in the config). repeated config.route.v3.HeaderMatcher headers = 4; // Faults are injected for the specified list of downstream hosts. If this @@ -96,9 +96,9 @@ message HTTPFault { // filter. Note that because this setting can be overridden at the route level, it's possible // for the number of active faults to be greater than this value (if injected via a different // route). If not specified, defaults to unlimited. This setting can be overridden via - // `runtime ` and any faults that are not injected - // due to overflow will be indicated via the `faults_overflow - // ` stat. + // ``runtime `` and any faults that are not injected + // due to overflow will be indicated via the ``faults_overflow + // `` stat. // // .. attention:: // Like other :ref:`circuit breakers ` in Envoy, this is a fuzzy diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto index 008818456e..eeb505a17f 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto @@ -4,6 +4,10 @@ package envoy.extensions.filters.http.rbac.v3; import "envoy/config/rbac/v3/rbac.proto"; +import "xds/annotations/v3/status.proto"; +import "xds/type/matcher/v3/matcher.proto"; + +import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; @@ -18,6 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.filters.http.rbac] // RBAC filter config. +// [#next-free-field: 6] message RBAC { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.rbac.v2.RBAC"; @@ -25,12 +30,33 @@ message RBAC { // Specify the RBAC rules to be applied globally. // If absent, no enforcing RBAC policy will be applied. // If present and empty, DENY. - config.rbac.v3.RBAC rules = 1; + // If both rules and matcher are configured, rules will be ignored. + config.rbac.v3.RBAC rules = 1 + [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"]; + + // The match tree to use when resolving RBAC action for incoming requests. Requests do not + // match any matcher will be denied. + // If absent, no enforcing RBAC matcher will be applied. + // If present and empty, deny all requests. + xds.type.matcher.v3.Matcher matcher = 4 [ + (udpa.annotations.field_migrate).oneof_promotion = "rules_specifier", + (xds.annotations.v3.field_status).work_in_progress = true + ]; // Shadow rules are not enforced by the filter (i.e., returning a 403) // but will emit stats and logs and can be used for rule testing. // If absent, no shadow RBAC policy will be applied. - config.rbac.v3.RBAC shadow_rules = 2; + // If both shadow rules and shadow matcher are configured, shadow rules will be ignored. + config.rbac.v3.RBAC shadow_rules = 2 + [(udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier"]; + + // The match tree to use for emitting stats and logs which can be used for rule testing for + // incoming requests. + // If absent, no shadow matcher will be applied. + xds.type.matcher.v3.Matcher shadow_matcher = 5 [ + (udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier", + (xds.annotations.v3.field_status).work_in_progress = true + ]; // If specified, shadow rules will emit stats with the given prefix. // This is useful to distinguish the stat when there are more than 1 RBAC filter configured with diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto index 7ce8b37dbb..b6c4963a18 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto @@ -3,6 +3,7 @@ syntax = "proto3"; package envoy.extensions.filters.http.router.v3; import "envoy/config/accesslog/v3/accesslog.proto"; +import "envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"; import "google/protobuf/wrappers.proto"; @@ -20,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Router :ref:`configuration overview `. // [#extension: envoy.filters.http.router] -// [#next-free-field: 8] +// [#next-free-field: 9] message Router { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.router.v2.Router"; @@ -41,10 +42,10 @@ message Router { // requests may be made for each downstream (inbound) request. repeated config.accesslog.v3.AccessLog upstream_log = 3; - // Do not add any additional *x-envoy-* headers to requests or responses. This - // only affects the :ref:`router filter generated *x-envoy-* headers + // Do not add any additional ``x-envoy-`` headers to requests or responses. This + // only affects the :ref:`router filter generated x-envoy- headers // `, other Envoy filters and the HTTP - // connection manager may continue to set *x-envoy-* headers. + // connection manager may continue to set ``x-envoy-`` headers. bool suppress_envoy_headers = 4; // Specifies a list of HTTP headers to strictly validate. Envoy will reject a @@ -89,4 +90,20 @@ message Router { // :ref:`gRPC stats filter` documentation // for more details. bool suppress_grpc_request_failure_code_stats = 7; + + // .. note:: + // Upstream HTTP filters are currently in alpha. + // + // Optional HTTP filters for the upstream filter chain. + // + // These filters will be applied for all requests that pass through the router. + // They will also be applied to shadowed requests. + // Upstream filters cannot change route or cluster. + // Upstream filters specified on the cluster will override these filters. + // + // If using upstream filters, please be aware that local errors sent by + // upstream filters will not trigger retries, and local errors sent by + // upstream filters will count as a final response if hedging is configured. + // [#extension-category: envoy.filters.http.upstream] + repeated network.http_connection_manager.v3.HttpFilter upstream_http_filters = 8; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index d7e8e799d3..b9f037c2c6 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -36,7 +36,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // HTTP connection manager :ref:`configuration overview `. // [#extension: envoy.filters.network.http_connection_manager] -// [#next-free-field: 50] +// [#next-free-field: 53] message HttpConnectionManager { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"; @@ -187,7 +187,7 @@ message HttpConnectionManager { // If not specified, no tracing will be performed. // // .. attention:: - // Please be aware that *envoy.tracers.opencensus* provider can only be configured once + // Please be aware that ``envoy.tracers.opencensus`` provider can only be configured once // in Envoy lifetime. // Any attempts to reconfigure it or to use different configurations for different HCM filters // will be rejected. @@ -280,13 +280,13 @@ message HttpConnectionManager { // path will be visible internally if a transformation is enabled. Any path rewrites that the // router performs (e.g. :ref:`regex_rewrite // ` or :ref:`prefix_rewrite - // `) will apply to the *:path* header + // `) will apply to the ``:path`` header // destined for the upstream. // - // Note: access logging and tracing will show the original *:path* header. + // Note: access logging and tracing will show the original ``:path`` header. message PathNormalizationOptions { // [#not-implemented-hide:] Normalization applies internally before any processing of requests by - // HTTP filters, routing, and matching *and* will affect the forwarded *:path* header. Defaults + // HTTP filters, routing, and matching *and* will affect the forwarded ``:path`` header. Defaults // to :ref:`NormalizePathRFC3986 // `. When not // specified, this value may be overridden by the runtime variable @@ -297,7 +297,7 @@ message HttpConnectionManager { // [#not-implemented-hide:] Normalization only applies internally before any processing of // requests by HTTP filters, routing, and matching. These will be applied after full - // transformation is applied. The *:path* header before this transformation will be restored in + // transformation is applied. The ``:path`` header before this transformation will be restored in // the router filter and sent upstream unless it was mutated by a filter. Defaults to no // transformations. // Multiple actions can be applied in the same Transformation, forming a sequential @@ -320,36 +320,36 @@ message HttpConnectionManager { // [#next-free-field: 7] message ProxyStatusConfig { // If true, the details field of the Proxy-Status header is not populated with stream_info.response_code_details. - // This value defaults to `false`, i.e. the `details` field is populated by default. + // This value defaults to ``false``, i.e. the ``details`` field is populated by default. bool remove_details = 1; // If true, the details field of the Proxy-Status header will not contain - // connection termination details. This value defaults to `false`, i.e. the - // `details` field will contain connection termination details by default. + // connection termination details. This value defaults to ``false``, i.e. the + // ``details`` field will contain connection termination details by default. bool remove_connection_termination_details = 2; // If true, the details field of the Proxy-Status header will not contain an - // enumeration of the Envoy ResponseFlags. This value defaults to `false`, - // i.e. the `details` field will contain a list of ResponseFlags by default. + // enumeration of the Envoy ResponseFlags. This value defaults to ``false``, + // i.e. the ``details`` field will contain a list of ResponseFlags by default. bool remove_response_flags = 3; // If true, overwrites the existing Status header with the response code // recommended by the Proxy-Status spec. - // This value defaults to `false`, i.e. the HTTP response code is not + // This value defaults to ``false``, i.e. the HTTP response code is not // overwritten. bool set_recommended_response_code = 4; // The name of the proxy as it appears at the start of the Proxy-Status // header. // - // If neither of these values are set, this value defaults to `server_name`, + // If neither of these values are set, this value defaults to ``server_name``, // which itself defaults to "envoy". oneof proxy_name { - // If `use_node_id` is set, Proxy-Status headers will use the Envoy's node + // If ``use_node_id`` is set, Proxy-Status headers will use the Envoy's node // ID as the name of the proxy. bool use_node_id = 5; - // If `literal_proxy_name` is set, Proxy-Status headers will use this + // If ``literal_proxy_name`` is set, Proxy-Status headers will use this // value as the name of the proxy. string literal_proxy_name = 6; } @@ -403,6 +403,10 @@ message HttpConnectionManager { [(udpa.annotations.security).configure_for_untrusted_downstream = true]; // Additional HTTP/1 settings that are passed to the HTTP/1 codec. + // [#comment:TODO: The following fields are ignored when the + // :ref:`header validation configuration ` + // is present: + // 1. :ref:`allow_chunked_length `] config.core.v3.Http1ProtocolOptions http_protocol_options = 8; // Additional HTTP/2 settings that are passed directly to the HTTP/2 codec. @@ -414,7 +418,7 @@ message HttpConnectionManager { config.core.v3.Http3ProtocolOptions http3_protocol_options = 44; // An optional override that the connection manager will write to the server - // header in responses. If not set, the default is *envoy*. + // header in responses. If not set, the default is ``envoy``. string server_name = 10 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; @@ -575,6 +579,15 @@ message HttpConnectionManager { // [#extension-category: envoy.http.original_ip_detection] repeated config.core.v3.TypedExtensionConfig original_ip_detection_extensions = 46; + // The configuration for the early header mutation extensions. + // + // When configured the extensions will be called before any routing, tracing, or any filter processing. + // Each extension will be applied in the order they are configured. + // If the same header is mutated by multiple extensions, then the last extension will win. + // + // [#extension-category: envoy.http.early_header_mutation] + repeated config.core.v3.TypedExtensionConfig early_header_mutation_extensions = 52; + // Configures what network addresses are considered internal for stats and header sanitation // purposes. If unspecified, only RFC1918 IP addresses will be considered internal. // See the documentation for :ref:`config_http_conn_man_headers_x-envoy-internal` for more @@ -587,7 +600,7 @@ message HttpConnectionManager { // has mutated the request headers. While :ref:`use_remote_address // ` // will also suppress XFF addition, it has consequences for logging and other - // Envoy uses of the remote address, so *skip_xff_append* should be used + // Envoy uses of the remote address, so ``skip_xff_append`` should be used // when only an elision of XFF addition is intended. bool skip_xff_append = 21; @@ -621,8 +634,8 @@ message HttpConnectionManager { // ` // is APPEND_FORWARD or SANITIZE_SET and the client connection is mTLS. It specifies the fields in // the client certificate to be forwarded. Note that in the - // :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, *Hash* is always set, and - // *By* is always set when the client certificate presents the URI type Subject Alternative Name + // :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, ``Hash`` is always set, and + // ``By`` is always set when the client certificate presents the URI type Subject Alternative Name // value. SetCurrentClientCertDetails set_current_client_cert_details = 17; @@ -636,7 +649,7 @@ message HttpConnectionManager { // :ref:`use_remote_address // ` // is true and represent_ipv4_remote_address_as_ipv4_mapped_ipv6 is true and the remote address is - // an IPv4 address, the address will be mapped to IPv6 before it is appended to *x-forwarded-for*. + // an IPv4 address, the address will be mapped to IPv6 before it is appended to ``x-forwarded-for``. // This is useful for testing compatibility of upstream services that parse the header value. For // example, 50.0.0.1 is represented as ::FFFF:50.0.0.1. See `IPv4-Mapped IPv6 Addresses // `_ for details. This will also affect the @@ -650,7 +663,7 @@ message HttpConnectionManager { repeated UpgradeConfig upgrade_configs = 23; // Should paths be normalized according to RFC 3986 before any processing of - // requests by HTTP filters or routing? This affects the upstream *:path* header + // requests by HTTP filters or routing? This affects the upstream ``:path`` header // as well. For paths that fail this check, Envoy will respond with 400 to // paths that are malformed. This defaults to false currently but will default // true in the future. When not specified, this value may be overridden by the @@ -660,13 +673,19 @@ message HttpConnectionManager { // for details of normalization. // Note that Envoy does not perform // `case normalization `_ + // [#comment:TODO: This field is ignored when the + // :ref:`header validation configuration ` + // is present.] google.protobuf.BoolValue normalize_path = 30; // Determines if adjacent slashes in the path are merged into one before any processing of - // requests by HTTP filters or routing. This affects the upstream *:path* header as well. Without - // setting this option, incoming requests with path `//dir///file` will not match against route - // with `prefix` match set to `/dir`. Defaults to `false`. Note that slash merging is not part of + // requests by HTTP filters or routing. This affects the upstream ``:path`` header as well. Without + // setting this option, incoming requests with path ``//dir///file`` will not match against route + // with ``prefix`` match set to ``/dir``. Defaults to ``false``. Note that slash merging is not part of // `HTTP spec `_ and is provided for convenience. + // [#comment:TODO: This field is ignored when the + // :ref:`header validation configuration ` + // is present.] bool merge_slashes = 33; // Action to take when request URL path contains escaped slash sequences (%2F, %2f, %5C and %5c). @@ -674,6 +693,9 @@ message HttpConnectionManager { // runtime variable. // The :ref:`http_connection_manager.path_with_escaped_slashes_action_sampling` runtime // variable can be used to apply the action to a portion of all requests. + // [#comment:TODO: This field is ignored when the + // :ref:`header validation configuration ` + // is present.] PathWithEscapedSlashesAction path_with_escaped_slashes_action = 45; // The configuration of the request ID extension. This includes operations such as @@ -704,10 +726,10 @@ message HttpConnectionManager { // local port. This affects the upstream host header unless the method is // CONNECT in which case if no filter adds a port the original port will be restored before headers are // sent upstream. - // Without setting this option, incoming requests with host `example:443` will not match against - // route with :ref:`domains` match set to `example`. Defaults to `false`. Note that port removal is not part + // Without setting this option, incoming requests with host ``example:443`` will not match against + // route with :ref:`domains` match set to ``example``. Defaults to ``false``. Note that port removal is not part // of `HTTP spec `_ and is provided for convenience. - // Only one of `strip_matching_host_port` or `strip_any_host_port` can be set. + // Only one of ``strip_matching_host_port`` or ``strip_any_host_port`` can be set. bool strip_matching_host_port = 39 [(udpa.annotations.field_migrate).oneof_promotion = "strip_port_mode"]; @@ -716,10 +738,10 @@ message HttpConnectionManager { // of request by HTTP filters or routing. // This affects the upstream host header unless the method is CONNECT in // which case if no filter adds a port the original port will be restored before headers are sent upstream. - // Without setting this option, incoming requests with host `example:443` will not match against - // route with :ref:`domains` match set to `example`. Defaults to `false`. Note that port removal is not part + // Without setting this option, incoming requests with host ``example:443`` will not match against + // route with :ref:`domains` match set to ``example``. Defaults to ``false``. Note that port removal is not part // of `HTTP spec `_ and is provided for convenience. - // Only one of `strip_matching_host_port` or `strip_any_host_port` can be set. + // Only one of ``strip_matching_host_port`` or ``strip_any_host_port`` can be set. bool strip_any_host_port = 42; } @@ -737,14 +759,14 @@ message HttpConnectionManager { // ` or the new HTTP/2 option // :ref:`override_stream_error_on_invalid_http_message // ` - // *not* the deprecated but similarly named :ref:`stream_error_on_invalid_http_messaging + // ``not`` the deprecated but similarly named :ref:`stream_error_on_invalid_http_messaging // ` google.protobuf.BoolValue stream_error_on_invalid_http_message = 40; // [#not-implemented-hide:] Path normalization configuration. This includes // configurations for transformations (e.g. RFC 3986 normalization or merge // adjacent slashes) and the policy to apply them. The policy determines - // whether transformations affect the forwarded *:path* header. RFC 3986 path + // whether transformations affect the forwarded ``:path`` header. RFC 3986 path // normalization is enabled by default and the default policy is that the // normalized header will be forwarded. See :ref:`PathNormalizationOptions // ` @@ -754,17 +776,45 @@ message HttpConnectionManager { // Determines if trailing dot of the host should be removed from host/authority header before any // processing of request by HTTP filters or routing. // This affects the upstream host header. - // Without setting this option, incoming requests with host `example.com.` will not match against - // route with :ref:`domains` match set to `example.com`. Defaults to `false`. + // Without setting this option, incoming requests with host ``example.com.`` will not match against + // route with :ref:`domains` match set to ``example.com``. Defaults to ``false``. // When the incoming request contains a host/authority header that includes a port number, // setting this option will strip a trailing dot, if present, from the host section, - // leaving the port as is (e.g. host value `example.com.:443` will be updated to `example.com:443`). + // leaving the port as is (e.g. host value ``example.com.:443`` will be updated to ``example.com:443``). bool strip_trailing_host_dot = 47; // Proxy-Status HTTP response header configuration. // If this config is set, the Proxy-Status HTTP response header field is // populated. By default, it is not. ProxyStatusConfig proxy_status_config = 49; + + // Configuration options for Header Validation (UHV). + // UHV is an extensible mechanism for checking validity of HTTP requests as well as providing + // normalization for request attributes, such as URI path. + // If the typed_header_validation_config is present it overrides the following options: + // ``normalize_path``, ``merge_slashes``, ``path_with_escaped_slashes_action`` + // ``http_protocol_options.allow_chunked_length``, ``common_http_protocol_options.headers_with_underscores_action``. + // + // The default UHV checks the following: + // + // #. HTTP/1 header map validity according to `RFC 7230 section 3.2`_ + // #. Syntax of HTTP/1 request target URI and response status + // #. HTTP/2 header map validity according to `RFC 7540 section 8.1.2`_ + // #. Syntax of HTTP/3 pseudo headers + // #. Syntax of ``Content-Length`` and ``Transfer-Encoding`` + // #. Validation of HTTP/1 requests with both ``Content-Length`` and ``Transfer-Encoding`` headers + // #. Normalization of the URI path according to `Normalization and Comparison `_ + // without `case normalization `_ + // + // [#not-implemented-hide:] + // [#extension-category: envoy.http.header_validators] + config.core.v3.TypedExtensionConfig typed_header_validation_config = 50; + + // Append the `x-forwarded-port` header with the port value client used to connect to Envoy. It + // will be ignored if the `x-forwarded-port` header has been set by any trusted proxy in front of Envoy. + bool append_x_forwarded_port = 51; } // The configuration to customize local reply returned by Envoy. @@ -823,11 +873,11 @@ message ResponseMapper { // The new response status code if specified. google.protobuf.UInt32Value status_code = 2 [(validate.rules).uint32 = {lt: 600 gte: 200}]; - // The new local reply body text if specified. It will be used in the `%LOCAL_REPLY_BODY%` - // command operator in the `body_format`. + // The new local reply body text if specified. It will be used in the ``%LOCAL_REPLY_BODY%`` + // command operator in the ``body_format``. config.core.v3.DataSource body = 3; - // A per mapper `body_format` to override the :ref:`body_format `. + // A per mapper ``body_format`` to override the :ref:`body_format `. // It will be used when this mapper is matched. config.core.v3.SubstitutionFormatString body_format_override = 4; diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto new file mode 100644 index 0000000000..5becf769ad --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -0,0 +1,59 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3; + +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3"; +option java_outer_classname = "ClientSideWeightedRoundRobinProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3;client_side_weighted_round_robinv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Client-Side Weighted Round Robin Load Balancing Policy] +// [#not-implemented-hide:] + +// Configuration for the client_side_weighted_round_robin LB policy. +// +// This policy differs from the built-in ROUND_ROBIN policy in terms of +// how the endpoint weights are determined. In the ROUND_ROBIN policy, +// the endpoint weights are sent by the control plane via EDS. However, +// in this policy, the endpoint weights are instead determined via +// qps and CPU utilization metrics sent by the endpoint using the Open +// Request Cost Aggregation (ORCA) protocol. The weight of a given endpoint +// is computed as qps / cpu_utilization. +// +// See the :ref:`load balancing architecture overview` for more information. +// +// [#next-free-field: 6] +message ClientSideWeightedRoundRobin { + // Whether to enable out-of-band utilization reporting collection from + // the endpoints. By default, per-request utilization reporting is used. + google.protobuf.BoolValue enable_oob_load_report = 1; + + // Load reporting interval to request from the server. Note that the + // server may not provide reports as frequently as the client requests. + // Used only when enable_oob_load_report is true. Default is 10 seconds. + google.protobuf.Duration oob_reporting_period = 2; + + // A given endpoint must report load metrics continuously for at least + // this long before the endpoint weight will be used. This avoids + // churn when the set of endpoint addresses changes. Takes effect + // both immediately after we establish a connection to an endpoint and + // after weight_expiration_period has caused us to stop using the most + // recent load metrics. Default is 10 seconds. + google.protobuf.Duration blackout_period = 3; + + // If a given endpoint has not reported load metrics in this long, + // then we stop using the reported weight. This ensures that we do + // not continue to use very stale weights. Once we stop using a stale + // value, if we later start seeing fresh reports again, the + // blackout_period applies. Defaults to 3 minutes. + google.protobuf.Duration weight_expiration_period = 4; + + // How often endpoint weights are recalculated. Default is 1 second. + google.protobuf.Duration weight_update_period = 5; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto new file mode 100644 index 0000000000..51520690a2 --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto @@ -0,0 +1,114 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.common.v3; + +import "envoy/config/core/v3/base.proto"; +import "envoy/type/v3/percent.proto"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.common.v3"; +option java_outer_classname = "CommonProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/common/v3;commonv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Common configuration for two or more load balancing policy extensions] + +message LocalityLbConfig { + // Configuration for :ref:`zone aware routing + // `. + message ZoneAwareLbConfig { + // Configures percentage of requests that will be considered for zone aware routing + // if zone aware routing is configured. If not specified, the default is 100%. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + type.v3.Percent routing_enabled = 1; + + // Configures minimum upstream cluster size required for zone aware routing + // If upstream cluster size is less than specified, zone aware routing is not performed + // even if zone aware routing is configured. If not specified, the default is 6. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + google.protobuf.UInt64Value min_cluster_size = 2; + + // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic + // mode`. Instead, the cluster will fail all + // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a + // failing service. + bool fail_traffic_on_panic = 3; + } + + // Configuration for :ref:`locality weighted load balancing + // ` + message LocalityWeightedLbConfig { + } + + oneof locality_config_specifier { + option (validate.required) = true; + + // Configuration for local zone aware load balancing. + ZoneAwareLbConfig zone_aware_lb_config = 1; + + // Enable locality weighted load balancing. + LocalityWeightedLbConfig locality_weighted_lb_config = 2; + } +} + +// Configuration for :ref:`slow start mode `. +message SlowStartConfig { + // Represents the size of slow start window. + // If set, the newly created host remains in slow start mode starting from its creation time + // for the duration of slow start window. + google.protobuf.Duration slow_start_window = 1; + + // This parameter controls the speed of traffic increase over the slow start window. Defaults to 1.0, + // so that endpoint would get linearly increasing amount of traffic. + // When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly. + // The value of aggression parameter should be greater than 0.0. + // By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve. + // + // During slow start window, effective weight of an endpoint would be scaled with time factor and aggression: + // ``new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))``, + // where ``time_factor=(time_since_start_seconds / slow_start_time_seconds)``. + // + // As time progresses, more and more traffic would be sent to endpoint, which is in slow start window. + // Once host exits slow start, time_factor and aggression no longer affect its weight. + config.core.v3.RuntimeDouble aggression = 2; + + // Configures the minimum percentage of origin weight that avoids too small new weight, + // which may cause endpoints in slow start mode receive no traffic in slow start window. + // If not specified, the default is 10%. + type.v3.Percent min_weight_percent = 3; +} + +// Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.) +message ConsistentHashingLbConfig { + // If set to ``true``, the cluster will use hostname instead of the resolved + // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address. + bool use_hostname_for_hashing = 1; + + // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150 + // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster. + // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200. + // Minimum is 100. + // + // Applies to both Ring Hash and Maglev load balancers. + // + // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified + // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests + // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing + // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify + // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the + // cascading overflow effect when choosing the next host in the ring/table). + // + // If weights are specified on the hosts, they are respected. + // + // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts + // being probed, so use a higher value if you require better performance. + google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}]; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto index 97efd91832..87a379c669 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto @@ -2,8 +2,8 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.least_request.v3; -import "envoy/config/cluster/v3/cluster.proto"; import "envoy/config/core/v3/base.proto"; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; import "google/protobuf/wrappers.proto"; @@ -17,11 +17,11 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Least Request Load Balancing Policy] +// [#extension: envoy.load_balancing_policies.least_request] // This configuration allows the built-in LEAST_REQUEST LB policy to be configured via the LB policy // extension point. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.clusters.lb_policy] message LeastRequest { // The number of random healthy hosts from which the host with the fewest active requests will // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. @@ -54,5 +54,8 @@ message LeastRequest { // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. - config.cluster.v3.Cluster.SlowStartConfig slow_start_config = 3; + common.v3.SlowStartConfig slow_start_config = 3; + + // Configuration for local zone aware load balancing or locality weighted load balancing. + common.v3.LocalityLbConfig locality_lb_config = 4; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto index 9408734bec..ce29a0ac17 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto @@ -2,8 +2,11 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.ring_hash.v3; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; + import "google/protobuf/wrappers.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -14,12 +17,12 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Ring Hash Load Balancing Policy] +// [#extension: envoy.load_balancing_policies.ring_hash] // This configuration allows the built-in RING_HASH LB policy to be configured via the LB policy // extension point. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.clusters.lb_policy] -// [#next-free-field: 6] +// [#next-free-field: 8] message RingHash { // The hash function used to hash hosts onto the ketama ring. enum HashFunction { @@ -52,7 +55,12 @@ message RingHash { // If set to `true`, the cluster will use hostname instead of the resolved // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address. - bool use_hostname_for_hashing = 4; + // + // ..note:: + // This is deprecated and please use :ref:`consistent_hashing_lb_config + // ` instead. + bool use_hostname_for_hashing = 4 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150 // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster. @@ -70,5 +78,19 @@ message RingHash { // // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts // being probed, so use a higher value if you require better performance. - google.protobuf.UInt32Value hash_balance_factor = 5 [(validate.rules).uint32 = {gte: 100}]; + // + // ..note:: + // This is deprecated and please use :ref:`consistent_hashing_lb_config + // ` instead. + google.protobuf.UInt32Value hash_balance_factor = 5 [ + deprecated = true, + (validate.rules).uint32 = {gte: 100}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; + + // Common configuration for hashing-based load balancing policies. + common.v3.ConsistentHashingLbConfig consistent_hashing_lb_config = 6; + + // Enable locality weighted load balancing for ring hash lb explicitly. + common.v3.LocalityLbConfig.LocalityWeightedLbConfig locality_weighted_lb_config = 7; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto index 4875b632f9..63fe49e9b0 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto @@ -2,10 +2,9 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.round_robin.v3; -import "envoy/config/cluster/v3/cluster.proto"; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; import "udpa/annotations/status.proto"; -import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.round_robin.v3"; option java_outer_classname = "RoundRobinProto"; @@ -14,13 +13,16 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Round Robin Load Balancing Policy] +// [#extension: envoy.load_balancing_policies.round_robin] // This configuration allows the built-in ROUND_ROBIN LB policy to be configured via the LB policy // extension point. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.clusters.lb_policy] message RoundRobin { // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. - config.cluster.v3.Cluster.SlowStartConfig slow_start_config = 1; + common.v3.SlowStartConfig slow_start_config = 1; + + // Configuration for local zone aware load balancing or locality weighted load balancing. + common.v3.LocalityLbConfig locality_lb_config = 2; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto index cad403dd35..ab8367a401 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto @@ -14,10 +14,10 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Weighted Round Robin Locality-Picking Load Balancing Policy] +// [#not-implemented-hide:] // Configuration for the wrr_locality LB policy. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.clusters.lb_policy] message WrrLocality { // The child LB policy to create for endpoint-picking within the chosen locality. config.cluster.v3.LoadBalancingPolicy endpoint_picking_policy = 1 diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto index d38d4edf91..82b45bf9e2 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -45,6 +45,13 @@ message TlsParameters { } // Minimum TLS protocol version. By default, it's ``TLSv1_2`` for both clients and servers. + // + // TLS protocol versions below TLSv1_2 require setting compatible ciphers with the + // ``cipher_suites`` setting as the default ciphers no longer include compatible ciphers. + // + // .. attention:: + // + // Using TLS protocol versions below TLSv1_2 has serious security considerations and risks. TlsProtocol tls_minimum_protocol_version = 1 [(validate.rules).enum = {defined_only: true}]; // Maximum TLS protocol version. By default, it's ``TLSv1_2`` for clients and ``TLSv1_3`` for @@ -142,24 +149,24 @@ message TlsCertificate { // The TLS certificate chain. // - // If *certificate_chain* is a filesystem path, a watch will be added to the + // If ``certificate_chain`` is a filesystem path, a watch will be added to the // parent directory for any file moves to support rotation. This currently - // only applies to dynamic secrets, when the *TlsCertificate* is delivered via + // only applies to dynamic secrets, when the ``TlsCertificate`` is delivered via // SDS. config.core.v3.DataSource certificate_chain = 1; // The TLS private key. // - // If *private_key* is a filesystem path, a watch will be added to the parent + // If ``private_key`` is a filesystem path, a watch will be added to the parent // directory for any file moves to support rotation. This currently only - // applies to dynamic secrets, when the *TlsCertificate* is delivered via SDS. + // applies to dynamic secrets, when the ``TlsCertificate`` is delivered via SDS. config.core.v3.DataSource private_key = 2 [(udpa.annotations.sensitive) = true]; - // `Pkcs12` data containing TLS certificate, chain, and private key. + // ``Pkcs12`` data containing TLS certificate, chain, and private key. // - // If *pkcs12* is a filesystem path, the file will be read, but no watch will - // be added to the parent directory, since *pkcs12* isn't used by SDS. - // This field is mutually exclusive with *certificate_chain*, *private_key* and *private_key_provider*. + // If ``pkcs12`` is a filesystem path, the file will be read, but no watch will + // be added to the parent directory, since ``pkcs12`` isn't used by SDS. + // This field is mutually exclusive with ``certificate_chain``, ``private_key`` and ``private_key_provider``. // This can't be marked as ``oneof`` due to API compatibility reasons. Setting // both :ref:`private_key `, // :ref:`certificate_chain `, @@ -167,17 +174,17 @@ message TlsCertificate { // and :ref:`pkcs12 ` // fields will result in an error. Use :ref:`password // ` - // to specify the password to unprotect the `PKCS12` data, if necessary. + // to specify the password to unprotect the ``PKCS12`` data, if necessary. config.core.v3.DataSource pkcs12 = 8 [(udpa.annotations.sensitive) = true]; - // If specified, updates of file-based *certificate_chain* and *private_key* + // If specified, updates of file-based ``certificate_chain`` and ``private_key`` // sources will be triggered by this watch. The certificate/key pair will be // read together and validated for atomic read consistency (i.e. no // intervening modification occurred between cert/key read, verified by file // hash comparisons). This allows explicit control over the path watched, by // default the parent directories of the filesystem paths in - // *certificate_chain* and *private_key* are watched if this field is not - // specified. This only applies when a *TlsCertificate* is delivered by SDS + // ``certificate_chain`` and ``private_key`` are watched if this field is not + // specified. This only applies when a ``TlsCertificate`` is delivered by SDS // with references to filesystem paths. See the :ref:`SDS key rotation // ` documentation for further details. config.core.v3.WatchedDirectory watched_directory = 7; @@ -320,12 +327,16 @@ message CertificateValidationContext { // See :ref:`the TLS overview ` for a list of common // system CA locations. // - // If *trusted_ca* is a filesystem path, a watch will be added to the parent + // If ``trusted_ca`` is a filesystem path, a watch will be added to the parent // directory for any file moves to support rotation. This currently only - // applies to dynamic secrets, when the *CertificateValidationContext* is + // applies to dynamic secrets, when the ``CertificateValidationContext`` is // delivered via SDS. // - // Only one of *trusted_ca* and *ca_certificate_provider_instance* may be specified. + // X509_V_FLAG_PARTIAL_CHAIN is set by default, so non-root/intermediate ca certificate in ``trusted_ca`` + // can be treated as trust anchor as well. It allows verification with building valid partial chain instead + // of a full chain. + // + // Only one of ``trusted_ca`` and ``ca_certificate_provider_instance`` may be specified. // // [#next-major-version: This field and watched_directory below should ideally be moved into a // separate sub-message, since there's no point in specifying the latter field without this one.] @@ -334,16 +345,16 @@ message CertificateValidationContext { // Certificate provider instance for fetching TLS certificates. // - // Only one of *trusted_ca* and *ca_certificate_provider_instance* may be specified. + // Only one of ``trusted_ca`` and ``ca_certificate_provider_instance`` may be specified. // [#not-implemented-hide:] CertificateProviderPluginInstance ca_certificate_provider_instance = 13 [(udpa.annotations.field_migrate).oneof_promotion = "ca_cert_source"]; - // If specified, updates of a file-based *trusted_ca* source will be triggered + // If specified, updates of a file-based ``trusted_ca`` source will be triggered // by this watch. This allows explicit control over the path watched, by - // default the parent directory of the filesystem path in *trusted_ca* is + // default the parent directory of the filesystem path in ``trusted_ca`` is // watched if this field is not specified. This only applies when a - // *CertificateValidationContext* is delivered by SDS with references to + // ``CertificateValidationContext`` is delivered by SDS with references to // filesystem paths. See the :ref:`SDS key rotation ` // documentation for further details. config.core.v3.WatchedDirectory watched_directory = 11; @@ -477,10 +488,13 @@ message CertificateValidationContext { // certificate chain will be subject to validation by :ref:`CRL `. bool only_verify_leaf_cert_crl = 14; - // Config for the max number of intermediate certificates in chain that are parsed during verification. - // This does not include the leaf certificate. If configured, and the certificate chain is longer than allowed, the certificates - // above the limit are ignored, and certificate validation will fail. The default limit is 100, - // though this can be system-dependent. - // https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_verify_depth.html + // Defines maximum depth of a certificate chain accepted in verification, the default limit is 100, though this can be system-dependent. + // This number does not include the leaf, so a depth of 1 allows the leaf and one CA certificate. If a trusted issuer appears in the chain, + // but in a depth larger than configured, the certificate validation will fail. + // See `BoringSSL SSL_CTX_set_verify_depth ` + // If you use OpenSSL, its behavior is different from BoringSSL, this will define a limit on the number of certificates between the end-entity and trust-anchor certificates. + // Neither the end-entity nor the trust-anchor certificates count against depth. + // See `OpenSSL SSL set_verify_depth `_. + // Trusted issues are specified by setting :ref:`trusted_ca ` google.protobuf.UInt32Value max_verify_depth = 16 [(validate.rules).uint32 = {lte: 100}]; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto index 03cf5be8e6..ac761f5763 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto @@ -55,7 +55,7 @@ message UpstreamTlsContext { google.protobuf.UInt32Value max_session_keys = 4; } -// [#next-free-field: 9] +// [#next-free-field: 10] message DownstreamTlsContext { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.DownstreamTlsContext"; @@ -123,6 +123,11 @@ message DownstreamTlsContext { // an accompanying OCSP response or if the response expires at runtime. // Defaults to LENIENT_STAPLING OcspStaplePolicy ocsp_staple_policy = 8 [(validate.rules).enum = {defined_only: true}]; + + // Multiple certificates are allowed in Downstream transport socket to serve different SNI. + // If the client provides SNI but no such cert matched, it will decide to full scan certificates or not based on this config. + // Defaults to false. See more details in :ref:`Multiple TLS certificates `. + google.protobuf.BoolValue full_scan_certs_on_sni_mismatch = 9; } // TLS key log configuration. @@ -210,13 +215,13 @@ message CommonTlsContext { [(validate.rules).message = {required: true}]; // Certificate provider for fetching CA certs. This will populate the - // *default_validation_context.trusted_ca* field. + // ``default_validation_context.trusted_ca`` field. // [#not-implemented-hide:] CertificateProvider validation_context_certificate_provider = 3 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Certificate provider instance for fetching CA certs. This will populate the - // *default_validation_context.trusted_ca* field. + // ``default_validation_context.trusted_ca`` field. // [#not-implemented-hide:] CertificateProviderInstance validation_context_certificate_provider_instance = 4 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -227,15 +232,12 @@ message CommonTlsContext { // TLS protocol versions, cipher suites etc. TlsParameters tls_params = 1; + // Only a single TLS certificate is supported in client contexts. In server contexts, // :ref:`Multiple TLS certificates ` can be associated with the - // same context to allow both RSA and ECDSA certificates. + // same context to allow both RSA and ECDSA certificates and support SNI-based selection. // - // Only a single TLS certificate is supported in client contexts. In server contexts, the first - // RSA certificate is used for clients that only support RSA and the first ECDSA certificate is - // used for clients that support ECDSA. - // - // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*, - // and *tls_certificate_provider_instance* may be used. + // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``, + // and ``tls_certificate_provider_instance`` may be used. // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's // not legal to put a repeated field in a oneof. In the next major version, we should rework // this to avoid this problem.] @@ -247,18 +249,17 @@ message CommonTlsContext { // The same number and types of certificates as :ref:`tls_certificates ` // are valid in the the certificates fetched through this setting. // - // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*, - // and *tls_certificate_provider_instance* may be used. + // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``, + // and ``tls_certificate_provider_instance`` may be used. // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's // not legal to put a repeated field in a oneof. In the next major version, we should rework // this to avoid this problem.] - repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6 - [(validate.rules).repeated = {max_items: 2}]; + repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6; // Certificate provider instance for fetching TLS certs. // - // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*, - // and *tls_certificate_provider_instance* may be used. + // Only one of ``tls_certificates``, ``tls_certificate_sds_secret_configs``, + // and ``tls_certificate_provider_instance`` may be used. // [#not-implemented-hide:] CertificateProviderPluginInstance tls_certificate_provider_instance = 14; diff --git a/xds/third_party/envoy/src/main/proto/envoy/service/discovery/v3/discovery.proto b/xds/third_party/envoy/src/main/proto/envoy/service/discovery/v3/discovery.proto index ab269b0876..b7270f246d 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/service/discovery/v3/discovery.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/service/discovery/v3/discovery.proto @@ -68,12 +68,12 @@ message DiscoveryRequest { repeated string resource_names = 3; // [#not-implemented-hide:] - // Alternative to *resource_names* field that allows specifying dynamic + // Alternative to ``resource_names`` field that allows specifying dynamic // parameters along with each resource name. Clients that populate this // field must be able to handle responses from the server where resources // are wrapped in a Resource message. // Note that it is legal for a request to have some resources listed - // in *resource_names* and others in *resource_locators*. + // in ``resource_names`` and others in ``resource_locators``. repeated ResourceLocator resource_locators = 7; // Type of the resource that is being requested, e.g. @@ -90,7 +90,7 @@ message DiscoveryRequest { string response_nonce = 5; // This is populated when the previous :ref:`DiscoveryResponse ` - // failed to update configuration. The *message* field in *error_details* provides the Envoy + // failed to update configuration. The ``message`` field in ``error_details`` provides the Envoy // internal exception related to the failure. It is only intended for consumption during manual // debugging, the string provided is not guaranteed to be stable across Envoy versions. google.rpc.Status error_detail = 6; @@ -180,9 +180,9 @@ message DeltaDiscoveryRequest { config.core.v3.Node node = 1; // Type of the resource that is being requested, e.g. - // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This does not need to be set if - // resources are only referenced via *xds_resource_subscribe* and - // *xds_resources_unsubscribe*. + // ``type.googleapis.com/envoy.api.v2.ClusterLoadAssignment``. This does not need to be set if + // resources are only referenced via ``xds_resource_subscribe`` and + // ``xds_resources_unsubscribe``. string type_url = 2; // DeltaDiscoveryRequests allow the client to add or remove individual @@ -212,17 +212,17 @@ message DeltaDiscoveryRequest { repeated string resource_names_unsubscribe = 4; // [#not-implemented-hide:] - // Alternative to *resource_names_subscribe* field that allows specifying dynamic parameters + // Alternative to ``resource_names_subscribe`` field that allows specifying dynamic parameters // along with each resource name. // Note that it is legal for a request to have some resources listed - // in *resource_names_subscribe* and others in *resource_locators_subscribe*. + // in ``resource_names_subscribe`` and others in ``resource_locators_subscribe``. repeated ResourceLocator resource_locators_subscribe = 8; // [#not-implemented-hide:] - // Alternative to *resource_names_unsubscribe* field that allows specifying dynamic parameters + // Alternative to ``resource_names_unsubscribe`` field that allows specifying dynamic parameters // along with each resource name. // Note that it is legal for a request to have some resources listed - // in *resource_names_unsubscribe* and others in *resource_locators_unsubscribe*. + // in ``resource_names_unsubscribe`` and others in ``resource_locators_unsubscribe``. repeated ResourceLocator resource_locators_unsubscribe = 9; // Informs the server of the versions of the resources the xDS client knows of, to enable the @@ -242,7 +242,7 @@ message DeltaDiscoveryRequest { string response_nonce = 6; // This is populated when the previous :ref:`DiscoveryResponse ` - // failed to update configuration. The *message* field in *error_details* + // failed to update configuration. The ``message`` field in ``error_details`` // provides the Envoy internal exception related to the failure. google.rpc.Status error_detail = 7; } @@ -332,7 +332,7 @@ message DynamicParameterConstraints { } } -// [#next-free-field: 9] +// [#next-free-field: 10] message Resource { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Resource"; @@ -346,13 +346,13 @@ message Resource { } // The resource's name, to distinguish it from others of the same type of resource. - // Only one of *name* or *resource_name* may be set. + // Only one of ``name`` or ``resource_name`` may be set. string name = 3; - // Alternative to the *name* field, to be used when the server supports + // Alternative to the ``name`` field, to be used when the server supports // multiple variants of the named resource that are differentiated by // dynamic parameter constraints. - // Only one of *name* or *resource_name* may be set. + // Only one of ``name`` or ``resource_name`` may be set. ResourceName resource_name = 8; // The aliases are a list of other names that this resource can go by. @@ -383,4 +383,8 @@ message Resource { // Cache control properties for the resource. // [#not-implemented-hide:] CacheControl cache_control = 7; + + // The Metadata field can be used to provide additional information for the resource. + // E.g. the trace data for debugging. + config.core.v3.Metadata metadata = 9; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/service/load_stats/v3/lrs.proto b/xds/third_party/envoy/src/main/proto/envoy/service/load_stats/v3/lrs.proto index 6f7545376d..d28cfc3677 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/service/load_stats/v3/lrs.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/service/load_stats/v3/lrs.proto @@ -17,7 +17,7 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/load_s option java_generic_services = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Load Reporting service (LRS)] +// [#protodoc-title: Load reporting service (LRS)] // Load Reporting Service is an Envoy API to emit load reports. Envoy will initiate a bi-directional // stream with a management server. Upon connecting, the management server can send a @@ -79,7 +79,7 @@ message LoadStatsResponse { "envoy.service.load_stats.v2.LoadStatsResponse"; // Clusters to report stats for. - // Not populated if *send_all_clusters* is true. + // Not populated if ``send_all_clusters`` is true. repeated string clusters = 1; // If true, the client should send all clusters it knows about. @@ -90,14 +90,14 @@ message LoadStatsResponse { // The minimum interval of time to collect stats over. This is only a minimum for two reasons: // // 1. There may be some delay from when the timer fires until stats sampling occurs. - // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic - // that is observed in between the corresponding previous *LoadStatsRequest* and this - // *LoadStatsResponse* will also be accumulated and billed to the cluster. This avoids a period + // 2. For clusters that were already feature in the previous ``LoadStatsResponse``, any traffic + // that is observed in between the corresponding previous ``LoadStatsRequest`` and this + // ``LoadStatsResponse`` will also be accumulated and billed to the cluster. This avoids a period // of inobservability that might otherwise exists between the messages. New clusters are not // subject to this consideration. google.protobuf.Duration load_reporting_interval = 2; - // Set to *true* if the management server supports endpoint granularity + // Set to ``true`` if the management server supports endpoint granularity // report. bool report_endpoint_granularity = 3; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/service/status/v3/csds.proto b/xds/third_party/envoy/src/main/proto/envoy/service/status/v3/csds.proto index 89d92efd2d..70ab587fa7 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/service/status/v3/csds.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/service/status/v3/csds.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.service.status.v3; -import "envoy/admin/v3/config_dump.proto"; +import "envoy/admin/v3/config_dump_shared.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/type/matcher/v3/node.proto"; @@ -21,7 +21,7 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/status option java_generic_services = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Client Status Discovery Service (CSDS)] +// [#protodoc-title: Client status discovery service (CSDS)] // CSDS is Client Status Discovery Service. It can be used to get the status of // an xDS-compliant client from the management server's point of view. It can diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/http/v3/path_transformation.proto b/xds/third_party/envoy/src/main/proto/envoy/type/http/v3/path_transformation.proto index 50350c48f9..2e974ca383 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/http/v3/path_transformation.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/http/v3/path_transformation.proto @@ -34,10 +34,10 @@ message PathTransformation { } // Determines if adjacent slashes are merged into one. A common use case is for a request path - // header. Using this option in `:ref: PathNormalizationOptions - // ` - // will allow incoming requests with path `//dir///file` to match against route with `prefix` - // match set to `/dir`. When using for header transformations, note that slash merging is not + // header. Using this option in ``:ref: PathNormalizationOptions + // `` + // will allow incoming requests with path ``//dir///file`` to match against route with ``prefix`` + // match set to ``/dir``. When using for header transformations, note that slash merging is not // part of `HTTP spec `_ and is provided for convenience. message MergeSlashes { } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/regex.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/regex.proto index 6daa16e478..e009a5a5bc 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/regex.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/regex.proto @@ -21,11 +21,11 @@ message RegexMatcher { // the documented `syntax `_. The engine is designed // to complete execution in linear time as well as limit the amount of memory used. // - // Envoy supports program size checking via runtime. The runtime keys `re2.max_program_size.error_level` - // and `re2.max_program_size.warn_level` can be set to integers as the maximum program size or + // Envoy supports program size checking via runtime. The runtime keys ``re2.max_program_size.error_level`` + // and ``re2.max_program_size.warn_level`` can be set to integers as the maximum program size or // complexity that a compiled regex can have before an exception is thrown or a warning is - // logged, respectively. `re2.max_program_size.error_level` defaults to 100, and - // `re2.max_program_size.warn_level` has no default if unset (will not check/log a warning). + // logged, respectively. ``re2.max_program_size.error_level`` defaults to 100, and + // ``re2.max_program_size.warn_level`` has no default if unset (will not check/log a warning). // // Envoy emits two stats for tracking the program size of regexes: the histogram `re2.program_size`, // which records the program size, and the counter `re2.exceeded_warn_level`, which is incremented diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/filter_state.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/filter_state.proto new file mode 100644 index 0000000000..f813178ae0 --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/filter_state.proto @@ -0,0 +1,29 @@ +syntax = "proto3"; + +package envoy.type.matcher.v3; + +import "envoy/type/matcher/v3/string.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.type.matcher.v3"; +option java_outer_classname = "FilterStateProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/type/matcher/v3;matcherv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Filter state matcher] + +// FilterStateMatcher provides a general interface for matching the filter state objects. +message FilterStateMatcher { + // The filter state key to retrieve the object. + string key = 1 [(validate.rules).string = {min_len: 1}]; + + oneof matcher { + option (validate.required) = true; + + // Matches the filter state object as a string value. + StringMatcher string_match = 2; + } +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/path.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/path.proto index d332a17d6b..46b758e22e 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/path.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/path.proto @@ -23,9 +23,9 @@ message PathMatcher { oneof rule { option (validate.required) = true; - // The `path` must match the URL path portion of the :path header. The query and fragment + // The ``path`` must match the URL path portion of the :path header. The query and fragment // string (if present) are removed in the URL path portion. - // For example, the path */data* will match the *:path* header */data#fragment?param=value*. + // For example, the path ``/data`` will match the ``:path`` header ``/data#fragment?param=value``. StringMatcher path = 1 [(validate.rules).message = {required: true}]; } } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/regex.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/regex.proto index f18bd03e2b..69cb8ba13f 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/regex.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/regex.proto @@ -25,14 +25,14 @@ message RegexMatcher { // the documented `syntax `_. The engine is designed // to complete execution in linear time as well as limit the amount of memory used. // - // Envoy supports program size checking via runtime. The runtime keys `re2.max_program_size.error_level` - // and `re2.max_program_size.warn_level` can be set to integers as the maximum program size or + // Envoy supports program size checking via runtime. The runtime keys ``re2.max_program_size.error_level`` + // and ``re2.max_program_size.warn_level`` can be set to integers as the maximum program size or // complexity that a compiled regex can have before an exception is thrown or a warning is - // logged, respectively. `re2.max_program_size.error_level` defaults to 100, and - // `re2.max_program_size.warn_level` has no default if unset (will not check/log a warning). + // logged, respectively. ``re2.max_program_size.error_level`` defaults to 100, and + // ``re2.max_program_size.warn_level`` has no default if unset (will not check/log a warning). // - // Envoy emits two stats for tracking the program size of regexes: the histogram `re2.program_size`, - // which records the program size, and the counter `re2.exceeded_warn_level`, which is incremented + // Envoy emits two stats for tracking the program size of regexes: the histogram ``re2.program_size``, + // which records the program size, and the counter ``re2.exceeded_warn_level``, which is incremented // each time the program size exceeds the warn level threshold. message GoogleRE2 { option (udpa.annotations.versioning).previous_message_type = @@ -56,10 +56,12 @@ message RegexMatcher { } oneof engine_type { - option (validate.required) = true; - // Google's RE2 regex engine. - GoogleRE2 google_re2 = 1 [(validate.rules).message = {required: true}]; + GoogleRE2 google_re2 = 1 [ + deprecated = true, + (validate.rules).message = {required: true}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; } // The regex match string. The string must be supported by the configured engine. The regex is matched @@ -93,5 +95,6 @@ message RegexMatchAndSubstitute { // backslash followed by the capture group number to denote a numbered // capture group. E.g., ``\1`` refers to capture group 1, and ``\2`` refers // to capture group 2. - string substitution = 2; + string substitution = 2 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/string.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/string.proto index efea6c0ab4..2df1bd37a6 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/string.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/string.proto @@ -32,7 +32,7 @@ message StringMatcher { // // Examples: // - // * *abc* only matches the value *abc*. + // * ``abc`` only matches the value ``abc``. string exact = 1; // The input string must have the prefix specified here. @@ -40,7 +40,7 @@ message StringMatcher { // // Examples: // - // * *abc* matches the value *abc.xyz* + // * ``abc`` matches the value ``abc.xyz`` string prefix = 2 [(validate.rules).string = {min_len: 1}]; // The input string must have the suffix specified here. @@ -48,7 +48,7 @@ message StringMatcher { // // Examples: // - // * *abc* matches the value *xyz.abc* + // * ``abc`` matches the value ``xyz.abc`` string suffix = 3 [(validate.rules).string = {min_len: 1}]; // The input string must match the regular expression specified here. @@ -59,13 +59,13 @@ message StringMatcher { // // Examples: // - // * *abc* matches the value *xyz.abc.def* + // * ``abc`` matches the value ``xyz.abc.def`` string contains = 7 [(validate.rules).string = {min_len: 1}]; } // If true, indicates the exact/prefix/suffix/contains matching should be case insensitive. This // has no effect for the safe_regex match. - // For example, the matcher *data* will match both input string *Data* and *data* if set to true. + // For example, the matcher ``data`` will match both input string ``Data`` and ``data`` if set to true. bool ignore_case = 6; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/struct.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/struct.proto index ad72e2cc78..1b963343b3 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/struct.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/struct.proto @@ -17,7 +17,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Struct matcher] // StructMatcher provides a general interface to check if a given value is matched in -// google.protobuf.Struct. It uses `path` to retrieve the value +// google.protobuf.Struct. It uses ``path`` to retrieve the value // from the struct and then check if it's matched to the specified value. // // For example, for the following Struct: diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/metadata/v3/metadata.proto b/xds/third_party/envoy/src/main/proto/envoy/type/metadata/v3/metadata.proto index 0d535374b8..2075857750 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/metadata/v3/metadata.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/metadata/v3/metadata.proto @@ -14,7 +14,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Metadata] -// MetadataKey provides a general interface using `key` and `path` to retrieve value from +// MetadataKey provides a general interface using ``key`` and ``path`` to retrieve value from // :ref:`Metadata `. // // For example, for the following Metadata: diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/v3/semantic_version.proto b/xds/third_party/envoy/src/main/proto/envoy/type/v3/semantic_version.proto index e1567612ab..e032b4cd22 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/v3/semantic_version.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/v3/semantic_version.proto @@ -11,7 +11,7 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/type/v3;typev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Semantic Version] +// [#protodoc-title: Semantic version] // Envoy uses SemVer (https://semver.org/). Major/minor versions indicate // expected behaviors and APIs, the patch version field is used only