diff --git a/repositories.bzl b/repositories.bzl index dd74a48da4..e4e88481fc 100644 --- a/repositories.bzl +++ b/repositories.bzl @@ -141,10 +141,10 @@ def grpc_java_repositories(bzlmod = False): if not native.existing_rule("envoy_api"): http_archive( name = "envoy_api", - sha256 = "ecf71817233eba19cc8b4ee14e126ffd5838065d5b5a92b2506258a42ac55199", - strip_prefix = "data-plane-api-0bc95493c5e88b7b07e62758d23b39341813a827", + sha256 = "cd8b49614408b43bd45d90e3e98d69e24eea632ff42ac3bfb8bca68bc31e377f", + strip_prefix = "data-plane-api-4de3c74cf21a9958c1cf26d8993c55c6e0d28b49", urls = [ - "https://github.com/envoyproxy/data-plane-api/archive/0bc95493c5e88b7b07e62758d23b39341813a827.tar.gz", + "https://github.com/envoyproxy/data-plane-api/archive/4de3c74cf21a9958c1cf26d8993c55c6e0d28b49.tar.gz", ], ) diff --git a/xds/third_party/envoy/import.sh b/xds/third_party/envoy/import.sh index 7a6b33871b..f4838d04c9 100755 --- a/xds/third_party/envoy/import.sh +++ b/xds/third_party/envoy/import.sh @@ -17,7 +17,7 @@ set -e # import VERSION from the google internal copybara_version.txt for Envoy -VERSION=0b90f64539c88dc3d2a6792dc714e8207bce0c08 +VERSION=969348a552e76101e5dadde6b8f65694a5198fdf DOWNLOAD_URL="https://github.com/envoyproxy/envoy/archive/${VERSION}.tar.gz" DOWNLOAD_BASE_DIR="envoy-${VERSION}" SOURCE_PROTO_BASE_DIR="${DOWNLOAD_BASE_DIR}/api" @@ -46,6 +46,7 @@ envoy/config/core/v3/http_uri.proto envoy/config/core/v3/protocol.proto envoy/config/core/v3/proxy_protocol.proto envoy/config/core/v3/resolver.proto +envoy/config/core/v3/socket_cmsg_headers.proto envoy/config/core/v3/socket_option.proto envoy/config/core/v3/substitution_format_string.proto envoy/config/core/v3/udp_socket_config.proto @@ -97,6 +98,7 @@ envoy/service/load_stats/v3/lrs.proto envoy/service/rate_limit_quota/v3/rlqs.proto envoy/service/status/v3/csds.proto envoy/type/http/v3/path_transformation.proto +envoy/type/matcher/v3/address.proto envoy/type/matcher/v3/filter_state.proto envoy/type/matcher/v3/http_inputs.proto envoy/type/matcher/v3/metadata.proto 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 index 8de77e18e1..b34e004d98 100644 --- 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 @@ -39,6 +39,14 @@ enum ClientResourceStatus { // Client received this resource and replied with NACK. NACKED = 4; + + // Client received an error from the control plane. The attached config + // dump is the most recent accepted one. If no config is accepted yet, + // the attached config dump will be empty. + RECEIVED_ERROR = 5; + + // Client timed out waiting for the resource from the control plane. + TIMEOUT = 6; } message UpdateFailureState { 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 5599f8082d..5f8c3e36bd 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 @@ -152,35 +152,38 @@ message TraceableFilter { "envoy.config.filter.accesslog.v2.TraceableFilter"; } -// Filters for random sampling of requests. +// Filters requests based on runtime-configurable sampling rates. message RuntimeFilter { option (udpa.annotations.versioning).previous_message_type = "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 - // default numerator. + // Specifies a key used to look up a custom sampling rate from the runtime configuration. If a value is found for this + // key, it will override the default sampling rate specified in ``percent_sampled``. string runtime_key = 1 [(validate.rules).string = {min_len: 1}]; - // The default sampling percentage. If not specified, defaults to 0% with - // denominator of 100. + // Defines the default sampling percentage when no runtime override is present. If not specified, the default is + // **0%** (with a denominator of 100). type.v3.FractionalPercent percent_sampled = 2; - // By default, sampling pivots on the header - // :ref:`x-request-id` being - // present. If :ref:`x-request-id` - // 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 - // randomly sample based on the runtime key value alone. - // ``use_independent_randomness`` can be used for logging kill switches within - // complex nested :ref:`AndFilter - // ` and :ref:`OrFilter - // ` blocks that are easier to - // reason about from a probability perspective (i.e., setting to true will - // cause the filter to behave like an independent random variable when - // composed within logical operator filters). + // Controls how sampling decisions are made. + // + // - Default behavior (``false``): + // + // * Uses the :ref:`x-request-id` as a consistent sampling pivot. + // * When :ref:`x-request-id` is present, sampling will be consistent + // across multiple hosts based on both the ``runtime_key`` and + // :ref:`x-request-id`. + // * Useful for tracking related requests across a distributed system. + // + // - When set to ``true`` or :ref:`x-request-id` is missing: + // + // * Sampling decisions are made randomly based only on the ``runtime_key``. + // * Useful in complex filter configurations (like nested + // :ref:`AndFilter`/ + // :ref:`OrFilter` blocks) where independent probability + // calculations are desired. + // * Can be used to implement logging kill switches with predictable probability distributions. + // bool use_independent_randomness = 3; } 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 0d2d6f1918..ac0135e255 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 @@ -942,6 +942,7 @@ message Cluster { // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on // specific options. // [#next-major-version: make this a list of typed extensions.] + // [#extension-category: envoy.upstream_options] map typed_extension_protocol_options = 36; // If the DNS refresh rate is specified and the cluster type is either @@ -953,8 +954,15 @@ message Cluster { // :ref:`STRICT_DNS` // and :ref:`LOGICAL_DNS` // this setting is ignored. - google.protobuf.Duration dns_refresh_rate = 16 - [(validate.rules).duration = {gt {nanos: 1000000}}]; + // This field is deprecated in favor of using the :ref:`cluster_type` + // extension point and configuring it with :ref:`DnsCluster`. + // If :ref:`cluster_type` is configured with + // :ref:`DnsCluster`, this field will be ignored. + google.protobuf.Duration dns_refresh_rate = 16 [ + deprecated = true, + (validate.rules).duration = {gt {nanos: 1000000}}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; // DNS jitter can be optionally specified if the cluster type is either // :ref:`STRICT_DNS`, @@ -965,7 +973,15 @@ message Cluster { // :ref:`STRICT_DNS` // and :ref:`LOGICAL_DNS` // this setting is ignored. - google.protobuf.Duration dns_jitter = 58; + // This field is deprecated in favor of using the :ref:`cluster_type` + // extension point and configuring it with :ref:`DnsCluster`. + // If :ref:`cluster_type` is configured with + // :ref:`DnsCluster`, this field will be ignored. + google.protobuf.Duration dns_jitter = 58 [ + deprecated = true, + (validate.rules).duration = {gte {}}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; // If the DNS failure refresh rate is specified and the cluster type is either // :ref:`STRICT_DNS`, @@ -975,16 +991,31 @@ message Cluster { // other than :ref:`STRICT_DNS` and // :ref:`LOGICAL_DNS` this setting is // ignored. - RefreshRate dns_failure_refresh_rate = 44; + // This field is deprecated in favor of using the :ref:`cluster_type` + // extension point and configuring it with :ref:`DnsCluster`. + // If :ref:`cluster_type` is configured with + // :ref:`DnsCluster`, this field will be ignored. + RefreshRate dns_failure_refresh_rate = 44 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true, // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS // resolution. - bool respect_dns_ttl = 39; + // This field is deprecated in favor of using the :ref:`cluster_type` + // extension point and configuring it with :ref:`DnsCluster`. + // If :ref:`cluster_type` is configured with + // :ref:`DnsCluster`, this field will be ignored. + bool respect_dns_ttl = 39 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // The DNS IP address resolution policy. If this setting is not specified, the // value defaults to // :ref:`AUTO`. + // For logical and strict dns cluster, this field is deprecated in favor of using the + // :ref:`cluster_type` + // extension point and configuring it with :ref:`DnsCluster`. + // If :ref:`cluster_type` is configured with + // :ref:`DnsCluster`, this field will be ignored. DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}]; // If DNS resolvers are specified and the cluster type is either @@ -1024,6 +1055,9 @@ message Cluster { // 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. + // Also note that this field is deprecated for logical dns and strict dns clusters and will be ignored when + // :ref:`cluster_type` is configured with + // :ref:`DnsCluster`. // [#extension-category: envoy.network.dns_resolver] core.v3.TypedExtensionConfig typed_dns_resolver_config = 55; 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 57f5937339..48ff5e7eee 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 @@ -303,12 +303,31 @@ message RuntimeFeatureFlag { string runtime_key = 2 [(validate.rules).string = {min_len: 1}]; } +// Please use :ref:`KeyValuePair ` instead. +// [#not-implemented-hide:] message KeyValue { + // The key of the key/value pair. + string key = 1 [ + deprecated = true, + (validate.rules).string = {min_len: 1 max_bytes: 16384}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; + + // The value of the key/value pair. + // + // The ``bytes`` type is used. This means if JSON or YAML is used to to represent the + // configuration, the value must be base64 encoded. This is unfriendly for users in most + // use scenarios of this message. + // + bytes value = 2 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; +} + +message KeyValuePair { // The key of the key/value pair. string key = 1 [(validate.rules).string = {min_len: 1 max_bytes: 16384}]; // The value of the key/value pair. - bytes value = 2; + google.protobuf.Value value = 2; } // Key/value pair plus option to control append behavior. This is used to specify @@ -339,8 +358,18 @@ message KeyValueAppend { OVERWRITE_IF_EXISTS = 3; } - // Key/value pair entry that this option to append or overwrite. - KeyValue entry = 1 [(validate.rules).message = {required: true}]; + // The single key/value pair record to be appended or overridden. This field must be set. + KeyValuePair record = 3; + + // Key/value pair entry that this option to append or overwrite. This field is deprecated + // and please use :ref:`record ` + // as replacement. + // [#not-implemented-hide:] + KeyValue entry = 1 [ + deprecated = true, + (validate.rules).message = {skip: true}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; // Describes the action taken to append/overwrite the given value for an existing // key or to only add this key if it's absent. @@ -349,10 +378,12 @@ message KeyValueAppend { // Key/value pair to append or remove. message KeyValueMutation { - // Key/value pair to append or overwrite. Only one of ``append`` or ``remove`` can be set. + // Key/value pair to append or overwrite. Only one of ``append`` or ``remove`` can be set or + // the configuration will be rejected. KeyValueAppend append = 1; - // Key to remove. Only one of ``append`` or ``remove`` can be set. + // Key to remove. Only one of ``append`` or ``remove`` can be set or the configuration will be + // rejected. string remove = 2 [(validate.rules).string = {max_bytes: 16384}]; } 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 821f042bbe..fd4440d8fa 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 @@ -375,13 +375,13 @@ message HealthCheck { // The default value for "healthy edge interval" is the same as the default interval. google.protobuf.Duration healthy_edge_interval = 16 [(validate.rules).duration = {gt {}}]; - // .. attention:: - // This field is deprecated in favor of the extension - // :ref:`event_logger ` and - // :ref:`event_log_path ` - // in the file sink extension. - // // Specifies the path to the :ref:`health check event log `. + // + // .. attention:: + // This field is deprecated in favor of the extension + // :ref:`event_logger ` and + // :ref:`event_log_path ` + // in the file sink extension. string event_log_path = 17 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; 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 7160cfb641..4bd823bc18 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 @@ -449,7 +449,7 @@ message KeepaliveSettings { [(validate.rules).duration = {gte {nanos: 1000000}}]; } -// [#next-free-field: 17] +// [#next-free-field: 18] message Http2ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Http2ProtocolOptions"; @@ -633,6 +633,9 @@ message Http2ProtocolOptions { // If unset, HTTP/2 codec is selected based on envoy.reloadable_features.http2_use_oghttp2. google.protobuf.BoolValue use_oghttp2_codec = 16 [(xds.annotations.v3.field_status).work_in_progress = true]; + + // Configure the maximum amount of metadata than can be handled per stream. Defaults to 1 MB. + google.protobuf.UInt64Value max_metadata_size = 17; } // [#not-implemented-hide:] diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_cmsg_headers.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_cmsg_headers.proto index 4c8da0d1e4..cc3e58e099 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_cmsg_headers.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_cmsg_headers.proto @@ -25,4 +25,4 @@ message SocketCmsgHeaders { // Expected size of cmsg value. Default is zero. uint32 expected_size = 3; -} \ No newline at end of file +} 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 e33a533e25..6593ccab5f 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 @@ -206,8 +206,10 @@ message Policy { // metadata should be sourced from, rather than only matching against dynamic metadata. // // The matcher can be configured to look up metadata from: +// // * Dynamic metadata: Runtime metadata added by filters during request processing // * Route metadata: Static metadata configured on the route entry +// message SourcedMetadata { // Metadata matcher configuration that defines what metadata to match against. This includes the filter name, // metadata key path, and expected value. 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 ce781d100c..6225ae0059 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 @@ -815,7 +815,10 @@ message RouteAction { // value, the request will be mirrored. core.v3.RuntimeFractionalPercent runtime_fraction = 3; - // Determines if the trace span should be sampled. Defaults to true. + // Specifies whether the trace span for the shadow request should be sampled. If this field is not explicitly set, + // the shadow request will inherit the sampling decision of its parent span. This ensures consistency with the trace + // sampling policy of the original request and prevents oversampling, especially in scenarios where runtime sampling + // is disabled. google.protobuf.BoolValue trace_sampled = 4; // Disables appending the ``-shadow`` suffix to the shadowed ``Host`` header. Defaults to ``false``. @@ -1868,10 +1871,11 @@ message VirtualCluster { // Global rate limiting :ref:`architecture overview `. // Also applies to Local rate limiting :ref:`using descriptors `. +// [#next-free-field: 7] message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit"; - // [#next-free-field: 12] + // [#next-free-field: 13] message Action { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action"; @@ -1928,9 +1932,48 @@ message RateLimit { // The key to use in the descriptor entry. string descriptor_key = 2 [(validate.rules).string = {min_len: 1}]; - // If set to true, Envoy skips the descriptor while calling rate limiting service - // when header is not present in the request. By default it skips calling the - // rate limiting service if this header is not present in the request. + // Controls the behavior when the specified header is not present in the request. + // + // If set to ``false`` (default): + // + // * Envoy does **NOT** call the rate limiting service for this descriptor. + // * Useful if the header is optional and you prefer to skip rate limiting when it's absent. + // + // If set to ``true``: + // + // * Envoy calls the rate limiting service but omits this descriptor if the header is missing. + // * Useful if you want Envoy to enforce rate limiting even when the header is not present. + // + bool skip_if_absent = 3; + } + + // The following descriptor entry is appended when a query parameter contains a key that matches the + // ``query_parameter_name``: + // + // .. code-block:: cpp + // + // ("", "") + message QueryParameters { + // The name of the query parameter to use for rate limiting. Value of this query parameter is used to populate + // the value of the descriptor entry for the descriptor_key. + string query_parameter_name = 1 [(validate.rules).string = {min_len: 1}]; + + // The key to use when creating the rate limit descriptor entry. his descriptor key will be used to identify the + // rate limit rule in the rate limiting service. + string descriptor_key = 2 [(validate.rules).string = {min_len: 1}]; + + // Controls the behavior when the specified query parameter is not present in the request. + // + // If set to ``false`` (default): + // + // * Envoy does **NOT** call the rate limiting service for this descriptor. + // * Useful if the query parameter is optional and you prefer to skip rate limiting when it's absent. + // + // If set to ``true``: + // + // * Envoy calls the rate limiting service but omits this descriptor if the query parameter is missing. + // * Useful if you want Envoy to enforce rate limiting even when the query parameter is not present. + // bool skip_if_absent = 3; } @@ -2065,9 +2108,19 @@ message RateLimit { // 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. + // Controls the behavior when the specified ``metadata_key`` is empty and ``default_value`` is not set. + // + // If set to ``false`` (default): + // + // * Envoy does **NOT** call the rate limiting service for this descriptor. + // * Useful if the metadata is optional and you prefer to skip rate limiting when it's absent. + // + // If set to ``true``: + // + // * Envoy calls the rate limiting service but omits this descriptor if the ``metadata_key`` is empty and + // ``default_value`` is missing. + // * Useful if you want Envoy to enforce rate limiting even when the metadata is not present. + // bool skip_if_absent = 5; } @@ -2110,6 +2163,9 @@ message RateLimit { // Rate limit on request headers. RequestHeaders request_headers = 3; + // Rate limit on query parameters. + QueryParameters query_parameters = 12; + // Rate limit on remote address. RemoteAddress remote_address = 4; @@ -2168,6 +2224,33 @@ message RateLimit { } } + message HitsAddend { + // Fixed number of hits to add to the rate limit descriptor. + // + // One of the ``number`` or ``format`` fields should be set but not both. + google.protobuf.UInt64Value number = 1 [(validate.rules).uint64 = {lte: 1000000000}]; + + // Substitution format string to extract the number of hits to add to the rate limit descriptor. + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here. + // + // .. note:: + // + // The format string must contains only single valid substitution field. If the format string + // not meets the requirement, the configuration will be rejected. + // + // The substitution field should generates a non-negative number or string representation of + // a non-negative number. The value of the non-negative number should be less than or equal + // to 1000000000 like the ``number`` field. If the output of the substitution field not meet + // the requirement, this will be treated as an error and the current descriptor will be ignored. + // + // For example, the ``%BYTES_RECEIVED%`` format string will be replaced with the number of bytes + // received in the request. + // + // One of the ``number`` or ``format`` fields should be set but not both. + string format = 2 [(validate.rules).string = {prefix: "%" suffix: "%" ignore_empty: true}]; + } + // Refers to the stage set in the filter. The rate limit configuration only // applies to filters with the same stage number. The default stage number is // 0. @@ -2175,9 +2258,19 @@ message RateLimit { // .. note:: // // The filter supports a range of 0 - 10 inclusively for stage numbers. + // + // .. note:: + // This is not supported if the rate limit action is configured in the ``typed_per_filter_config`` like + // :ref:`VirtualHost.typed_per_filter_config` or + // :ref:`Route.typed_per_filter_config`, etc. google.protobuf.UInt32Value stage = 1 [(validate.rules).uint32 = {lte: 10}]; // The key to be set in runtime to disable this rate limit configuration. + // + // .. note:: + // This is not supported if the rate limit action is configured in the ``typed_per_filter_config`` like + // :ref:`VirtualHost.typed_per_filter_config` or + // :ref:`Route.typed_per_filter_config`, etc. string disable_key = 2; // A list of actions that are to be applied for this rate limit configuration. @@ -2192,7 +2285,38 @@ message RateLimit { // rate limit configuration. If the override value is invalid or cannot be resolved // from metadata, no override is provided. See :ref:`rate limit override // ` for more information. + // + // .. note:: + // This is not supported if the rate limit action is configured in the ``typed_per_filter_config`` like + // :ref:`VirtualHost.typed_per_filter_config` or + // :ref:`Route.typed_per_filter_config`, etc. Override limit = 4; + + // An optional hits addend to be appended to the descriptor produced by this rate limit + // configuration. + // + // .. note:: + // This is only supported if the rate limit action is configured in the ``typed_per_filter_config`` like + // :ref:`VirtualHost.typed_per_filter_config` or + // :ref:`Route.typed_per_filter_config`, etc. + HitsAddend hits_addend = 5; + + // If true, the rate limit request will be applied when the stream completes. The default value is false. + // This is useful when the rate limit budget needs to reflect the response context that is not available + // on the request path. + // + // For example, let's say the upstream service calculates the usage statistics and returns them in the response body + // and we want to utilize these numbers to apply the rate limit action for the subsequent requests. + // Combined with another filter that can set the desired addend based on the response (e.g. Lua filter), + // this can be used to subtract the usage statistics from the rate limit budget. + // + // A rate limit applied on the stream completion is "fire-and-forget" by nature, and rate limit is not enforced by this config. + // In other words, the current request won't be blocked when this is true, but the budget will be updated for the subsequent + // requests based on the action with this field set to true. Users should ensure that the rate limit is enforced by the actions + // applied on the request path, i.e. the ones with this field set to false. + // + // Currently, this is only supported by the HTTP global rate filter. + bool apply_on_stream_done = 6; } // .. attention:: 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 649869a255..6efd47ac58 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 @@ -27,48 +27,53 @@ message RBAC { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.rbac.v2.RBAC"; - // Specify the RBAC rules to be applied globally. - // If absent, no enforcing RBAC policy will be applied. - // If present and empty, DENY. - // If both rules and matcher are configured, rules will be ignored. + // The primary RBAC policy which will be applied globally, to all the incoming requests. + // + // * If absent, no RBAC enforcement occurs. + // * If set but empty, all requests are denied. + // + // .. note:: + // + // When both ``rules`` and ``matcher`` are configured, ``rules`` will be ignored. + // config.rbac.v3.RBAC rules = 1 [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"]; // If specified, 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 - // rules. + // This is useful for distinguishing metrics when multiple RBAC filters are configured. string rules_stat_prefix = 6; - // 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 - ]; + // Match tree for evaluating RBAC actions on incoming requests. Requests not matching any matcher will be denied. + // + // * If absent, no RBAC enforcement occurs. + // * If set but empty, all requests are denied. + // + xds.type.matcher.v3.Matcher matcher = 4 + [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"]; - // 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. - // If both shadow rules and shadow matcher are configured, shadow rules will be ignored. + // Shadow policy for testing RBAC rules without enforcing them. These rules generate stats and logs but do not deny + // requests. If absent, no shadow RBAC policy will be applied. + // + // .. note:: + // + // When 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. + // Match tree for testing RBAC rules through stats and logs without enforcing them. + // If absent, no shadow matching occurs. 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 - // shadow rules. + // This is useful for distinguishing metrics when multiple RBAC filters use shadow rules. string shadow_rules_stat_prefix = 3; - // If track_per_rule_stats is true, counters will be published for each rule and shadow rule. + // If ``track_per_rule_stats`` is ``true``, counters will be published for each rule and shadow rule. bool track_per_rule_stats = 7; } @@ -78,7 +83,7 @@ message RBACPerRoute { reserved 1; - // Override the global configuration of the filter with this new config. - // If absent, the global RBAC policy will be disabled for this route. + // Per-route specific RBAC configuration that overrides the global RBAC configuration. + // If absent, RBAC policy will be disabled for this route. RBAC rbac = 2; } 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 5fb9f24cc7..ce549d6a90 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 @@ -185,14 +185,6 @@ message HttpConnectionManager { // Configuration for an external tracing provider. // If not specified, no tracing will be performed. - // - // .. attention:: - // 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. - // Such a constraint is inherent to OpenCensus itself. It cannot be overcome without changes - // on OpenCensus side. config.trace.v3.Tracing.Http provider = 9; // Create separate tracing span for each upstream request if true. And if this flag is set to true, 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 46d86b6585..bb53b4eee7 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 @@ -232,12 +232,13 @@ message TlsCertificate { config.core.v3.WatchedDirectory watched_directory = 7; // BoringSSL private key method provider. This is an alternative to :ref:`private_key - // ` field. This can't be - // marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key - // ` and - // :ref:`private_key_provider - // ` fields will result in an - // error. + // ` field. + // When both :ref:`private_key ` and + // :ref:`private_key_provider ` fields are set, + // ``private_key_provider`` takes precedence. + // If ``private_key_provider`` is unavailable and :ref:`fallback + // ` + // is enabled, ``private_key`` will be used. PrivateKeyProvider private_key_provider = 6; // The password to decrypt the TLS private key. If this field is not set, it is assumed that the 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 44b8d26932..b292b18c45 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 @@ -34,9 +34,8 @@ message UpstreamTlsContext { // // .. attention:: // - // Server certificate verification is not enabled by default. Configure - // :ref:`trusted_ca` to enable - // verification. + // Server certificate verification is not enabled by default. To enable verification, configure + // :ref:`trusted_ca`. CommonTlsContext common_tls_context = 1; // SNI string to use when creating TLS backend connections. @@ -51,14 +50,13 @@ message UpstreamTlsContext { // interacts with other validation options. bool auto_host_sni = 6; - // If true, replace any Subject Alternative Name validations with a validation for a DNS SAN matching - // the SNI value sent. Note that the validation will be against the actual requested SNI, regardless of how it - // is configured. + // If true, replaces any Subject Alternative Name (SAN) validations with a validation for a DNS SAN matching + // the SNI value sent. The validation uses the actual requested SNI, regardless of how the SNI is configured. // - // For the common case where an SNI value is sent and it is expected that the server certificate contains a SAN - // matching that SNI value, this option will do the correct SAN validation. + // For common cases where an SNI value is present and the server certificate should include a corresponding SAN, + // this option ensures the SAN is properly validated. // - // See :ref:`validation configuration ` for how this interacts with + // See the :ref:`validation configuration ` for how this interacts with // other validation options. bool auto_sni_san_validation = 7; @@ -70,16 +68,19 @@ message UpstreamTlsContext { bool allow_renegotiation = 3; // Maximum number of session keys (Pre-Shared Keys for TLSv1.3+, Session IDs and Session Tickets - // for TLSv1.2 and older) to store for the purpose of session resumption. + // for TLSv1.2 and older) to be stored for session resumption. // // Defaults to 1, setting this to 0 disables session resumption. google.protobuf.UInt32Value max_session_keys = 4; - // This field is used to control the enforcement, whereby the handshake will fail if the keyUsage extension - // is present and incompatible with the TLS usage. Currently, the default value is false (i.e., enforcement off) - // but it is expected to be changed to true by default in a future release. - // ``ssl.was_key_usage_invalid`` in :ref:`listener metrics ` will be set for certificate - // configurations that would fail if this option were set to true. + // Controls enforcement of the ``keyUsage`` extension in peer certificates. If set to ``true``, the handshake will fail if + // the ``keyUsage`` is incompatible with TLS usage. + // + // .. note:: + // The default value is ``false`` (i.e., enforcement off). It is expected to change to ``true`` in a future release. + // + // The ``ssl.was_key_usage_invalid`` in :ref:`listener metrics ` metric will be incremented + // for configurations that would fail if this option were enabled. google.protobuf.BoolValue enforce_rsa_key_usage = 5; } @@ -89,24 +90,16 @@ message DownstreamTlsContext { "envoy.api.v2.auth.DownstreamTlsContext"; enum OcspStaplePolicy { - // OCSP responses are optional. If an OCSP response is absent - // or expired, the associated certificate will be used for - // connections without an OCSP staple. + // OCSP responses are optional. If absent or expired, the certificate is used without stapling. LENIENT_STAPLING = 0; - // OCSP responses are optional. If an OCSP response is absent, - // the associated certificate will be used without an - // OCSP staple. If a response is provided but is expired, - // the associated certificate will not be used for - // subsequent connections. If no suitable certificate is found, - // the connection is rejected. + // OCSP responses are optional. If absent, the certificate is used without stapling. If present but expired, + // the certificate is not used for subsequent connections. Connections are rejected if no suitable certificate + // is found. STRICT_STAPLING = 1; - // OCSP responses are required. Configuration will fail if - // a certificate is provided without an OCSP response. If a - // response expires, the associated certificate will not be - // used connections. If no suitable certificate is found, the - // connection is rejected. + // OCSP responses are required. Connections fail if a certificate lacks a valid OCSP response. Expired responses + // prevent certificate use in new connections, and connections are rejected if no suitable certificate is available. MUST_STAPLE = 2; } @@ -139,46 +132,54 @@ message DownstreamTlsContext { bool disable_stateless_session_resumption = 7; } - // If set to true, the TLS server will not maintain a session cache of TLS sessions. (This is - // relevant only for TLSv1.2 and earlier.) + // If ``true``, the TLS server will not maintain a session cache of TLS sessions. + // + // .. note:: + // This applies only to TLSv1.2 and earlier. + // bool disable_stateful_session_resumption = 10; - // If specified, ``session_timeout`` will change the maximum lifetime (in seconds) of the TLS session. - // Currently this value is used as a hint for the `TLS session ticket lifetime (for TLSv1.2) `_. - // Only seconds can be specified (fractional seconds are ignored). + // Maximum lifetime of TLS sessions. If specified, ``session_timeout`` will change the maximum lifetime + // of the TLS session. + // + // This serves as a hint for the `TLS session ticket lifetime (for TLSv1.2) `_. + // Only whole seconds are considered; fractional seconds are ignored. google.protobuf.Duration session_timeout = 6 [(validate.rules).duration = { lt {seconds: 4294967296} gte {} }]; - // Config for whether to use certificates if they do not have - // an accompanying OCSP response or if the response expires at runtime. - // Defaults to LENIENT_STAPLING + // Configuration for handling certificates without an OCSP response or with expired responses. + // + // 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 `. + // This option controls the behavior when no matching certificate is found for the received SNI value, + // or no SNI value was sent. If enabled, all certificates will be evaluated for a match for non-SNI criteria + // such as key type and OCSP settings. If disabled, the first provided certificate will be used. + // Defaults to ``false``. See more details in :ref:`Multiple TLS certificates `. google.protobuf.BoolValue full_scan_certs_on_sni_mismatch = 9; - // By default, Envoy as a server uses its preferred cipher during the handshake. - // Setting this to true would allow the downstream client's preferred cipher to be used instead. - // Has no effect when using TLSv1_3. + // If ``true``, the downstream client's preferred cipher is used during the handshake. If ``false``, Envoy + // uses its preferred cipher. + // + // .. note:: + // This has no effect when using TLSv1_3. + // bool prefer_client_ciphers = 11; } // TLS key log configuration. // The key log file format is "format used by NSS for its SSLKEYLOGFILE debugging output" (text taken from openssl man page) message TlsKeyLog { - // The path to save the TLS key log. + // Path to save the TLS key log. string path = 1 [(validate.rules).string = {min_len: 1}]; - // The local IP address that will be used to filter the connection which should save the TLS key log - // If it is not set, any local IP address will be matched. + // Local IP address ranges to filter connections for TLS key logging. If not set, matches any local IP address. repeated config.core.v3.CidrRange local_address_range = 2; - // The remote IP address that will be used to filter the connection which should save the TLS key log - // If it is not set, any remote IP address will be matched. + // Remote IP address ranges to filter connections for TLS key logging. If not set, matches any remote IP address. repeated config.core.v3.CidrRange remote_address_range = 3; } @@ -187,8 +188,8 @@ message TlsKeyLog { message CommonTlsContext { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext"; - // Config for Certificate provider to get certificates. This provider should allow certificates to be - // fetched/refreshed over the network asynchronously with respect to the TLS handshake. + // Config for the Certificate Provider to fetch certificates. Certificates are fetched/refreshed asynchronously over + // the network relative to the TLS handshake. // // DEPRECATED: This message is not currently used, but if we ever do need it, we will want to // move it out of CommonTlsContext and into common.proto, similar to the existing @@ -281,7 +282,7 @@ message CommonTlsContext { // fetched/refreshed over the network asynchronously with respect to the TLS handshake. // // The same number and types of certificates as :ref:`tls_certificates ` - // are valid in the the certificates fetched through this setting. + // are valid in the certificates fetched through this setting. // // If ``tls_certificates`` or ``tls_certificate_provider_instance`` are set, this field // is ignored. @@ -319,13 +320,17 @@ message CommonTlsContext { // fetched/refreshed over the network asynchronously with respect to the TLS handshake. SdsSecretConfig validation_context_sds_secret_config = 7; - // Combined certificate validation context holds a default CertificateValidationContext - // and SDS config. When SDS server returns dynamic CertificateValidationContext, both dynamic - // and default CertificateValidationContext are merged into a new CertificateValidationContext - // for validation. This merge is done by Message::MergeFrom(), so dynamic - // CertificateValidationContext overwrites singular fields in default - // CertificateValidationContext, and concatenates repeated fields to default - // CertificateValidationContext, and logical OR is applied to boolean fields. + // Combines the default ``CertificateValidationContext`` with the SDS-provided dynamic context for certificate + // validation. + // + // When the SDS server returns a dynamic ``CertificateValidationContext``, it is merged + // with the default context using ``Message::MergeFrom()``. The merging rules are as follows: + // + // * **Singular Fields:** Dynamic fields override the default singular fields. + // * **Repeated Fields:** Dynamic repeated fields are concatenated with the default repeated fields. + // * **Boolean Fields:** Boolean fields are combined using a logical OR operation. + // + // The resulting ``CertificateValidationContext`` is used to perform certificate validation. CombinedCertificateValidationContext combined_validation_context = 8; // Certificate provider for fetching validation context. 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 b7270f246d..6f3b12356c 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 @@ -41,6 +41,17 @@ message ResourceName { DynamicParameterConstraints dynamic_parameter_constraints = 2; } +// [#not-implemented-hide:] +// An error associated with a specific resource name, returned to the +// client by the server. +message ResourceError { + // The name of the resource. + ResourceName resource_name = 1; + + // The error reported for the resource. + google.rpc.Status error_detail = 2; +} + // A DiscoveryRequest requests a set of versioned resources of the same type for // a given Envoy node on some API. // [#next-free-field: 8] @@ -96,7 +107,7 @@ message DiscoveryRequest { google.rpc.Status error_detail = 6; } -// [#next-free-field: 7] +// [#next-free-field: 8] message DiscoveryResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DiscoveryResponse"; @@ -138,6 +149,13 @@ message DiscoveryResponse { // The control plane instance that sent the response. config.core.v3.ControlPlane control_plane = 6; + + // [#not-implemented-hide:] + // Errors associated with specific resources. Clients are expected to + // remember the most recent error for a given resource across responses; + // the error condition is not considered to be cleared until a response is + // received that contains the resource in the 'resources' field. + repeated ResourceError resource_errors = 7; } // DeltaDiscoveryRequest and DeltaDiscoveryResponse are used in a new gRPC @@ -247,7 +265,7 @@ message DeltaDiscoveryRequest { google.rpc.Status error_detail = 7; } -// [#next-free-field: 9] +// [#next-free-field: 10] message DeltaDiscoveryResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DeltaDiscoveryResponse"; @@ -281,6 +299,13 @@ message DeltaDiscoveryResponse { // [#not-implemented-hide:] // The control plane instance that sent the response. config.core.v3.ControlPlane control_plane = 7; + + // [#not-implemented-hide:] + // Errors associated with specific resources. Note that a resource in + // this field with a status of NOT_FOUND should be treated the same as + // a resource listed in the 'removed_resources' or 'removed_resource_names' + // fields. + repeated ResourceError resource_errors = 9; } // A set of dynamic parameter constraints associated with a variant of an individual xDS resource. 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 1c51f2bac3..de62fbf9b0 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 @@ -72,6 +72,11 @@ enum ClientConfigStatus { // config dump is not the NACKed version, but the most recent accepted one. If // no config is accepted yet, the attached config dump will be empty. CLIENT_NACKED = 3; + + // Client received an error from the control plane. The attached config + // dump is the most recent accepted one. If no config is accepted yet, + // the attached config dump will be empty. + CLIENT_RECEIVED_ERROR = 4; } // Request for client status of clients identified by a list of NodeMatchers. diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto new file mode 100644 index 0000000000..8a03a5320a --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto @@ -0,0 +1,22 @@ +syntax = "proto3"; + +package envoy.type.matcher.v3; + +import "xds/core/v3/cidr.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.type.matcher.v3"; +option java_outer_classname = "AddressProto"; +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: Address Matcher] + +// Match an IP against a repeated CIDR range. This matcher is intended to be +// used in other matchers, for example in the filter state matcher to match a +// filter state object as an IP. +message AddressMatcher { + repeated xds.core.v3.CidrRange ranges = 1; +} 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 index f813178ae0..8c38a515ae 100644 --- 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 @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.type.matcher.v3; +import "envoy/type/matcher/v3/address.proto"; import "envoy/type/matcher/v3/string.proto"; import "udpa/annotations/status.proto"; @@ -25,5 +26,8 @@ message FilterStateMatcher { // Matches the filter state object as a string value. StringMatcher string_match = 2; + + // Matches the filter state object as a ip Instance. + AddressMatcher address_match = 3; } }