diff --git a/xds-api/src/main/proto/envoy/admin/v3/server_info.proto b/xds-api/src/main/proto/envoy/admin/v3/server_info.proto index adf5ab440a4..6614ce45c85 100644 --- a/xds-api/src/main/proto/envoy/admin/v3/server_info.proto +++ b/xds-api/src/main/proto/envoy/admin/v3/server_info.proto @@ -59,7 +59,7 @@ message ServerInfo { config.core.v3.Node node = 7; } -// [#next-free-field: 42] +// [#next-free-field: 43] message CommandLineOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.CommandLineOptions"; @@ -161,6 +161,9 @@ message CommandLineOptions { // See :option:`--file-flush-interval-msec` for details. google.protobuf.Duration file_flush_interval = 16; + // See :option:`--file-flush-min-size-kb` for details. + uint32 file_flush_min_size = 42; + // See :option:`--drain-time-s` for details. google.protobuf.Duration drain_time = 17; diff --git a/xds-api/src/main/proto/envoy/config/accesslog/v3/accesslog.proto b/xds-api/src/main/proto/envoy/config/accesslog/v3/accesslog.proto index 6753ab6ab52..f273f2e695f 100644 --- a/xds-api/src/main/proto/envoy/config/accesslog/v3/accesslog.proto +++ b/xds-api/src/main/proto/envoy/config/accesslog/v3/accesslog.proto @@ -108,6 +108,9 @@ message ComparisonFilter { // <= LE = 2; + + // != + NE = 3; } // Comparison operator. diff --git a/xds-api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto b/xds-api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto index 28b1eba6680..7b862c1021a 100644 --- a/xds-api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto +++ b/xds-api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto @@ -16,6 +16,7 @@ import "envoy/config/metrics/v3/stats.proto"; import "envoy/config/overload/v3/overload.proto"; import "envoy/config/trace/v3/http_tracer.proto"; import "envoy/extensions/transport_sockets/tls/v3/secret.proto"; +import "envoy/type/matcher/v3/string.proto"; import "envoy/type/v3/percent.proto"; import "google/protobuf/duration.proto"; @@ -76,7 +77,7 @@ message Bootstrap { // :ref:`LDS ` configuration source. core.v3.ConfigSource lds_config = 1; - // xdstp:// resource locator for listener collection. + // ``xdstp://`` resource locator for listener collection. // [#not-implemented-hide:] string lds_resources_locator = 5; @@ -85,7 +86,7 @@ message Bootstrap { // configuration source. core.v3.ConfigSource cds_config = 2; - // xdstp:// resource locator for cluster collection. + // ``xdstp://`` resource locator for cluster collection. // [#not-implemented-hide:] string cds_resources_locator = 6; @@ -126,17 +127,19 @@ message Bootstrap { // When the flag is enabled, Envoy will lazily initialize a subset of the stats (see below). // This will save memory and CPU cycles when creating the objects that own these stats, if those // stats are never referenced throughout the lifetime of the process. However, it will incur additional - // memory overhead for these objects, and a small increase of CPU usage when a at least one of the stats + // memory overhead for these objects, and a small increase of CPU usage when at least one of the stats // is updated for the first time. + // // Groups of stats that will be lazily initialized: + // // - Cluster traffic stats: a subgroup of the :ref:`cluster statistics ` - // that are used when requests are routed to the cluster. + // that are used when requests are routed to the cluster. bool enable_deferred_creation_stats = 1; } message GrpcAsyncClientManagerConfig { // Optional field to set the expiration time for the cached gRPC client object. - // The minimal value is 5s and the default is 50s. + // The minimal value is ``5s`` and the default is ``50s``. google.protobuf.Duration max_cached_entry_idle_duration = 1 [(validate.rules).duration = {gte {seconds: 5}}]; } @@ -151,25 +154,25 @@ message Bootstrap { // A list of :ref:`Node ` field names // that will be included in the context parameters of the effective - // xdstp:// URL that is sent in a discovery request when resource + // ``xdstp://`` URL that is sent in a discovery request when resource // locators are used for LDS/CDS. Any non-string field will have its JSON // encoding set as the context parameter value, with the exception of // metadata, which will be flattened (see example below). The supported field // names are: - // - "cluster" - // - "id" - // - "locality.region" - // - "locality.sub_zone" - // - "locality.zone" - // - "metadata" - // - "user_agent_build_version.metadata" - // - "user_agent_build_version.version" - // - "user_agent_name" - // - "user_agent_version" + // - ``cluster`` + // - ``id`` + // - ``locality.region`` + // - ``locality.sub_zone`` + // - ``locality.zone`` + // - ``metadata`` + // - ``user_agent_build_version.metadata`` + // - ``user_agent_build_version.version`` + // - ``user_agent_name`` + // - ``user_agent_version`` // // The node context parameters act as a base layer dictionary for the context // parameters (i.e. more specific resource specific context parameters will - // override). Field names will be prefixed with “udpa.node.” when included in + // override). Field names will be prefixed with ````"udpa.node."```` when included in // context parameters. // // For example, if node_context_params is ``["user_agent_name", "metadata"]``, @@ -211,10 +214,10 @@ 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`` + // 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`` // can be set. - // Duration must be at least 1ms and at most 5 min. + // Duration must be at least ``1ms`` and at most ``5 min``. google.protobuf.Duration stats_flush_interval = 7 [ (validate.rules).duration = { lt {seconds: 300} @@ -271,23 +274,28 @@ message Bootstrap { (udpa.annotations.security).configure_for_untrusted_upstream = true ]; - // Enable :ref:`stats for event dispatcher `, defaults to false. - // Note that this records a value for each iteration of the event loop on every thread. This - // should normally be minimal overhead, but when using - // :ref:`statsd `, it will send each observed value - // over the wire individually because the statsd protocol doesn't have any way to represent a - // histogram summary. Be aware that this can be a very large volume of data. + // Enable :ref:`stats for event dispatcher `. Defaults to ``false``. + // + // .. note:: + // + // This records a value for each iteration of the event loop on every thread. This + // should normally be minimal overhead, but when using + // :ref:`statsd `, it will send each observed value + // over the wire individually because the statsd protocol doesn't have any way to represent a + // histogram summary. Be aware that this can be a very large volume of data. bool enable_dispatcher_stats = 16; - // Optional string which will be used in lieu of x-envoy in prefixing headers. + // Optional string which will be used in lieu of ``x-envoy`` in prefixing headers. // - // For example, if this string is present and set to X-Foo, then x-envoy-retry-on will be - // transformed into x-foo-retry-on etc. + // For example, if this string is present and set to ``X-Foo``, then ``x-envoy-retry-on`` will be + // transformed into ``x-foo-retry-on`` etc. + // + // .. note:: // - // Note this applies to the headers Envoy will generate, the headers Envoy will sanitize, and the - // headers Envoy will trust for core code and core extensions only. Be VERY careful making - // changes to this string, especially in multi-layer Envoy deployments or deployments using - // extensions which are not upstream. + // This applies to the headers Envoy will generate, the headers Envoy will sanitize, and the + // headers Envoy will trust for core code and core extensions only. Be VERY careful making + // changes to this string, especially in multi-layer Envoy deployments or deployments using + // extensions which are not upstream. string header_prefix = 18; // Optional proxy version which will be used to set the value of :ref:`server.version statistic @@ -295,8 +303,8 @@ message Bootstrap { // :ref:`stats sinks `. google.protobuf.UInt64Value stats_server_version_override = 19; - // Always use TCP queries instead of UDP queries for DNS lookups. - // This may be overridden on a per-cluster basis in cds_config, + // Always use ``TCP`` queries instead of ``UDP`` queries for DNS lookups. + // This may be overridden on a per-cluster basis in ``cds_config``, // when :ref:`dns_resolvers ` and // :ref:`use_tcp_for_dns_lookups ` are // specified. @@ -305,8 +313,8 @@ message Bootstrap { bool use_tcp_for_dns_lookups = 20 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // DNS resolution configuration which includes the underlying dns resolver addresses and options. - // This may be overridden on a per-cluster basis in cds_config, when + // DNS resolution configuration which includes the underlying DNS resolver addresses and options. + // This may be overridden on a per-cluster basis in ``cds_config``, when // :ref:`dns_resolution_config ` // is specified. // This field is deprecated in favor of @@ -314,14 +322,15 @@ message Bootstrap { core.v3.DnsResolutionConfig dns_resolution_config = 30 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // DNS resolver type configuration extension. This extension can be used to configure c-ares, apple, + // DNS resolver type configuration extension. This extension can be used to configure ``c-ares``, ``apple``, // 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 // :ref:`dns_resolution_config ` // configuration. - // During the transition period when both ``dns_resolution_config`` and ``typed_dns_resolver_config`` exists, + // + // During the transition period when both ``dns_resolution_config`` and ``typed_dns_resolver_config`` exist, // 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] @@ -337,9 +346,10 @@ message Bootstrap { repeated FatalAction fatal_actions = 28; // Configuration sources that will participate in - // xdstp:// URL authority resolution. The algorithm is as + // ``xdstp://`` URL authority resolution. The algorithm is as // follows: - // 1. The authority field is taken from the xdstp:// URL, call + // + // 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 @@ -355,7 +365,7 @@ message Bootstrap { // [#not-implemented-hide:] repeated core.v3.ConfigSource config_sources = 22; - // Default configuration source for xdstp:// URLs if all + // Default configuration source for ``xdstp://`` URLs if all // other resolution fails. // [#not-implemented-hide:] core.v3.ConfigSource default_config_source = 23; @@ -375,28 +385,30 @@ message Bootstrap { // allows users to customize the inline headers on-demand at Envoy startup without modifying // Envoy's source code. // - // Note that the 'set-cookie' header cannot be registered as inline header. + // .. note:: + // + // The ``set-cookie`` header cannot be registered as inline header. repeated CustomInlineHeader inline_headers = 32; - // Optional path to a file with performance tracing data created by "Perfetto" SDK in binary - // ProtoBuf format. The default value is "envoy.pftrace". + // 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. + // 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. + // 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. + // process xDS resources and messages. If a value is not specified, no ``XdsConfigTracker`` will be used. // // .. note:: // @@ -408,14 +420,14 @@ message Bootstrap { // [#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. + // Envoy only supports ``ListenerManager`` for this field and Envoy Mobile + // supports ``ApiListenerManager``. core.v3.TypedExtensionConfig listener_manager = 37; // Optional application log configuration. ApplicationLogConfig application_log_config = 38; - // Optional gRPC async manager config. + // Optional gRPC async client manager config. GrpcAsyncClientManagerConfig grpc_async_client_manager_config = 40; // Optional configuration for memory allocation manager. @@ -425,7 +437,7 @@ message Bootstrap { // Administration interface :ref:`operations documentation // `. -// [#next-free-field: 7] +// [#next-free-field: 8] message Admin { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Admin"; @@ -434,14 +446,14 @@ message Admin { repeated accesslog.v3.AccessLog access_log = 5; // 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 + // 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. string access_log_path = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // The cpu profiler output path for the administration server. If no profile - // path is specified, the default is ‘/var/log/envoy/envoy.prof’. + // The CPU profiler output path for the administration server. If no profile + // path is specified, the default is ``/var/log/envoy/envoy.prof``. string profile_path = 2; // The TCP address that the administration server will listen on. @@ -455,6 +467,21 @@ message Admin { // Indicates whether :ref:`global_downstream_max_connections ` // should apply to the admin interface or not. bool ignore_global_conn_limit = 6; + + // List of admin paths that are accessible. If not specified, all admin endpoints are accessible. + // + // When specified, only paths in this list will be accessible, all others will return ``HTTP 403 Forbidden``. + // + // Example: + // + // .. code-block:: yaml + // + // allow_paths: + // - exact: /stats + // - exact: /ready + // - prefix: /healthcheck + // + repeated type.matcher.v3.StringMatcher allow_paths = 7; } // Cluster manager :ref:`architecture overview `. @@ -491,7 +518,7 @@ message ClusterManager { OutlierDetection outlier_detection = 2; // Optional configuration used to bind newly established upstream connections. - // This may be overridden on a per-cluster basis by upstream_bind_config in the cds_config. + // This may be overridden on a per-cluster basis by ``upstream_bind_config`` in the ``cds_config``. core.v3.BindConfig upstream_bind_config = 3; // A management server endpoint to stream load stats to via @@ -502,7 +529,7 @@ message ClusterManager { // Whether the ClusterManager will create clusters on the worker threads // inline during requests. This will save memory and CPU cycles in cases where - // there are lots of inactive clusters and > 1 worker thread. + // there are lots of inactive clusters and ``> 1`` worker thread. bool enable_deferred_cluster_creation = 5; } @@ -525,12 +552,12 @@ message Watchdog { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Watchdog"; message WatchdogAction { - // The events are fired in this order: KILL, MULTIKILL, MEGAMISS, MISS. + // The events are fired in this order: ``KILL``, ``MULTIKILL``, ``MEGAMISS``, ``MISS``. // Within an event type, actions execute in the order they are configured. - // For KILL/MULTIKILL there is a default PANIC that will run after the + // For ``KILL``/``MULTIKILL`` there is a default ``PANIC`` that will run after the // registered actions and kills the process if it wasn't already killed. // It might be useful to specify several debug actions, and possibly an - // alternate FATAL action. + // alternate ``FATAL`` action. enum WatchdogEvent { UNKNOWN = 0; KILL = 1; @@ -545,46 +572,48 @@ message Watchdog { WatchdogEvent event = 2 [(validate.rules).enum = {defined_only: true}]; } - // Register actions that will fire on given WatchDog events. - // See ``WatchDogAction`` for priority of events. + // Register actions that will fire on given Watchdog 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 - // 1000ms. + // ``watchdog_mega_miss`` statistic. If not specified the default is ``1000ms``. google.protobuf.Duration megamiss_timeout = 2; // If a watched thread has been nonresponsive for this duration, assume a - // programming error and kill the entire Envoy process. Set to 0 to disable - // kill behavior. If not specified the default is 0 (disabled). + // programming error and kill the entire Envoy process. Set to ``0`` to disable + // 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 // 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). + // 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). + // 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``. - // If not specified the default is 0. + // If not specified the default is ``0``. type.v3.Percent multikill_threshold = 5; } // Fatal actions to run while crashing. Actions can be safe (meaning they are // async-signal safe) or unsafe. We run all safe actions before we run unsafe actions. -// If using an unsafe action that could get stuck or deadlock, it important to -// have an out of band system to terminate the process. +// +// .. note:: +// +// If using an unsafe action that could get stuck or deadlock, it is important to +// 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 @@ -667,7 +696,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 the ``rtds_config`` for the RTDS layer. string name = 1; // RTDS configuration source. @@ -708,11 +737,11 @@ message LayeredRuntime { // Used to specify the header that needs to be registered as an inline header. // // If request or response contain multiple headers with the same name and the header -// name is registered as an inline header. Then multiple headers will be folded +// name is registered as an inline header, then multiple headers will be folded // into one, and multiple header values will be concatenated by a suitable delimiter. // The delimiter is generally a comma. // -// For example, if 'foo' is registered as an inline header, and the headers contains +// For example, if ``foo`` is registered as an inline header, and the headers contain // the following two headers: // // .. code-block:: text @@ -752,6 +781,6 @@ message MemoryAllocatorManager { // Interval in milliseconds for memory releasing. If specified, during every // interval Envoy will try to release ``bytes_to_release`` of free memory back to operating system for reuse. - // Defaults to 1000 milliseconds. + // Defaults to ``1000`` milliseconds. google.protobuf.Duration memory_release_interval = 2; } diff --git a/xds-api/src/main/proto/envoy/config/cluster/v3/cluster.proto b/xds-api/src/main/proto/envoy/config/cluster/v3/cluster.proto index c5112458a71..192409096af 100644 --- a/xds-api/src/main/proto/envoy/config/cluster/v3/cluster.proto +++ b/xds-api/src/main/proto/envoy/config/cluster/v3/cluster.proto @@ -22,6 +22,7 @@ import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; import "xds/core/v3/collection_entry.proto"; +import "xds/type/matcher/v3/matcher.proto"; import "envoy/annotations/deprecation.proto"; import "udpa/annotations/migrate.proto"; @@ -45,7 +46,7 @@ message ClusterCollection { } // Configuration for a single upstream cluster. -// [#next-free-field: 59] +// [#next-free-field: 60] message Cluster { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster"; @@ -747,6 +748,9 @@ message Cluster { // If both this and preconnect_ratio are set, Envoy will make sure both predicted needs are met, // basically preconnecting max(predictive-preconnect, per-upstream-preconnect), for each // upstream. + // + // This is limited somewhat arbitrarily to 3 because preconnecting too aggressively can + // harm latency more than the preconnecting helps. google.protobuf.DoubleValue predictive_preconnect_ratio = 2 [(validate.rules).double = {lte: 3.0 gte: 1.0}]; } @@ -809,6 +813,41 @@ message Cluster { // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.] repeated TransportSocketMatch transport_socket_matches = 43; + // Optional matcher that selects a transport socket from + // :ref:`transport_socket_matches `. + // + // This matcher uses the generic xDS matcher framework to select a named transport socket + // based on various inputs available at transport socket selection time. + // + // Supported matching inputs: + // + // * ``endpoint_metadata``: Extract values from the selected endpoint's metadata. + // * ``locality_metadata``: Extract values from the endpoint's locality metadata. + // * ``transport_socket_filter_state``: Extract values from filter state that was explicitly shared from + // downstream to upstream via ``TransportSocketOptions``. This enables flexible + // downstream-connection-based matching, such as: + // + // - Network namespace matching. + // - Custom connection attributes. + // - Any data explicitly passed via filter state. + // + // .. note:: + // Filter state sharing follows the same pattern as tunneling in Envoy. Filters must explicitly + // share data by setting filter state with the appropriate sharing mode. The filter state is + // then accessible via the ``transport_socket_filter_state`` input during transport socket selection. + // + // If this field is set, it takes precedence over legacy metadata-based selection + // performed by :ref:`transport_socket_matches + // ` alone. + // If the matcher does not yield a match, Envoy uses the default transport socket + // configured for the cluster. + // + // When using this field, each entry in + // :ref:`transport_socket_matches ` + // must have a unique ``name``. The matcher outcome is expected to reference one of + // these names. + xds.type.matcher.v3.Matcher transport_socket_matcher = 59; + // Supplies the name of the cluster which must be unique across all clusters. // The cluster name is used when emitting // :ref:`statistics ` if :ref:`alt_stat_name diff --git a/xds-api/src/main/proto/envoy/config/core/v3/address.proto b/xds-api/src/main/proto/envoy/config/core/v3/address.proto index 238494a09c7..17a68269e34 100644 --- a/xds-api/src/main/proto/envoy/config/core/v3/address.proto +++ b/xds-api/src/main/proto/envoy/config/core/v3/address.proto @@ -115,16 +115,18 @@ message TcpKeepalive { // Maximum number of keepalive probes to send without response before deciding // the connection is dead. Default is to use the OS level configuration (unless - // overridden, Linux defaults to 9.) + // overridden, Linux defaults to 9.) Setting this to ``0`` disables TCP keepalive. google.protobuf.UInt32Value keepalive_probes = 1; // The number of seconds a connection needs to be idle before keep-alive probes // start being sent. Default is to use the OS level configuration (unless - // overridden, Linux defaults to 7200s (i.e., 2 hours.) + // overridden, Linux defaults to 7200s (i.e., 2 hours.) Setting this to ``0`` disables + // TCP keepalive. google.protobuf.UInt32Value keepalive_time = 2; // The number of seconds between keep-alive probes. Default is to use the OS - // level configuration (unless overridden, Linux defaults to 75s.) + // level configuration (unless overridden, Linux defaults to 75s.) Setting this to + // ``0`` disables TCP keepalive. google.protobuf.UInt32Value keepalive_interval = 3; } diff --git a/xds-api/src/main/proto/envoy/config/core/v3/cel.proto b/xds-api/src/main/proto/envoy/config/core/v3/cel.proto new file mode 100644 index 00000000000..940a66d0b10 --- /dev/null +++ b/xds-api/src/main/proto/envoy/config/core/v3/cel.proto @@ -0,0 +1,63 @@ +syntax = "proto3"; + +package envoy.config.core.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.config.core.v3"; +option java_outer_classname = "CelProto"; +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: CEL Expression Configuration] + +// CEL expression evaluation configuration. +// These options control the behavior of the Common Expression Language runtime for +// individual CEL expressions. +message CelExpressionConfig { + // Enable string conversion functions for CEL expressions. When enabled, CEL expressions + // can convert values to strings using the ``string()`` function. + // + // .. attention:: + // + // This option is disabled by default to avoid unbounded memory allocation. + // CEL evaluation cost is typically bounded by the expression size, but converting + // arbitrary values (e.g., large messages, lists, or maps) to strings may allocate + // memory proportional to input data size, which can be unbounded and lead to + // memory exhaustion. + bool enable_string_conversion = 1; + + // Enable string concatenation for CEL expressions. When enabled, CEL expressions + // can concatenate strings using the ``+`` operator. + // + // .. attention:: + // + // This option is disabled by default to avoid unbounded memory allocation. + // While CEL normally bounds evaluation by expression size, enabling string + // concatenation allows building outputs whose size depends on input data, + // potentially causing large intermediate allocations and memory exhaustion. + bool enable_string_concat = 2; + + // Enable string manipulation functions for CEL expressions. When enabled, CEL + // expressions can use additional string functions: + // + // * ``replace(old, new)`` - Replaces all occurrences of ``old`` with ``new``. + // * ``split(separator)`` - Splits a string into a list of substrings. + // * ``lowerAscii()`` - Converts ASCII characters to lowercase. + // * ``upperAscii()`` - Converts ASCII characters to uppercase. + // + // .. note:: + // + // Standard CEL string functions like ``contains()``, ``startsWith()``, and + // ``endsWith()`` are always available regardless of this setting. + // + // .. attention:: + // + // This option is disabled by default to avoid unbounded memory allocation. + // Although CEL generally bounds evaluation by expression size, functions such as + // ``replace``, ``split``, ``lowerAscii()``, and ``upperAscii()`` can allocate memory + // proportional to input data size. Under adversarial inputs this can lead to + // unbounded allocations and memory exhaustion. + bool enable_string_functions = 3; +} diff --git a/xds-api/src/main/proto/envoy/config/core/v3/grpc_service.proto b/xds-api/src/main/proto/envoy/config/core/v3/grpc_service.proto index f8feb2f516f..9c44006b2a9 100644 --- a/xds-api/src/main/proto/envoy/config/core/v3/grpc_service.proto +++ b/xds-api/src/main/proto/envoy/config/core/v3/grpc_service.proto @@ -45,10 +45,20 @@ message GrpcService { [(validate.rules).string = {min_len: 0 max_bytes: 16384 well_known_regex: HTTP_HEADER_VALUE strict: false}]; - // Indicates the retry policy for re-establishing the gRPC stream - // This field is optional. If max interval is not provided, it will be set to ten times the provided base interval. - // Currently only supported for xDS gRPC streams. - // If not set, xDS gRPC streams default base interval:500ms, maximum interval:30s will be applied. + // Specifies the retry backoff policy for re-establishing long‑lived xDS gRPC streams. + // + // This field is optional. If ``retry_back_off.max_interval`` is not provided, it will be set to + // ten times the configured ``retry_back_off.base_interval``. + // + // .. note:: + // + // This field is only honored for management‑plane xDS gRPC streams created from + // :ref:`ApiConfigSource ` that use + // ``envoy_grpc``. Data‑plane gRPC clients (for example external authorization or external + // processing filters) must use :ref:`GrpcService.retry_policy + // ` instead. + // + // If not set, xDS gRPC streams default to a base interval of 500ms and a maximum interval of 30s. RetryPolicy retry_policy = 3; // Maximum gRPC message size that is allowed to be received. @@ -329,7 +339,17 @@ message GrpcService { // `. repeated HeaderValue initial_metadata = 5; - // Optional default retry policy for streams toward the service. - // If an async stream doesn't have retry policy configured in its stream options, this retry policy is used. + // Optional default retry policy for RPCs or streams initiated toward this gRPC service. + // + // If an async stream does not have a retry policy configured in its per‑stream options, this + // policy is used as the default. + // + // .. note:: + // + // This field is only applied by Envoy gRPC (``envoy_grpc``) clients. Google gRPC + // (``google_grpc``) clients currently ignore this field. + // + // If not specified, no default retry policy is applied at the client level and retries only occur + // when explicitly configured in per‑stream options. RetryPolicy retry_policy = 6; } diff --git a/xds-api/src/main/proto/envoy/config/core/v3/protocol.proto b/xds-api/src/main/proto/envoy/config/core/v3/protocol.proto index 74fe641fe3a..63e189e689e 100644 --- a/xds-api/src/main/proto/envoy/config/core/v3/protocol.proto +++ b/xds-api/src/main/proto/envoy/config/core/v3/protocol.proto @@ -31,10 +31,13 @@ message TcpProtocolOptions { } // Config for keepalive probes in a QUIC connection. -// Note that QUIC keep-alive probing packets work differently from HTTP/2 keep-alive PINGs in a sense that the probing packet -// itself doesn't timeout waiting for a probing response. Quic has a shorter idle timeout than TCP, so it doesn't rely on such probing to discover dead connections. If the peer fails to respond, the connection will idle timeout eventually. Thus, they are configured differently from :ref:`connection_keepalive `. +// +// .. note:: +// +// QUIC keep-alive probing packets work differently from HTTP/2 keep-alive PINGs in a sense that the probing packet +// itself doesn't timeout waiting for a probing response. QUIC has a shorter idle timeout than TCP, so it doesn't rely on such probing to discover dead connections. If the peer fails to respond, the connection will idle timeout eventually. Thus, they are configured differently from :ref:`connection_keepalive `. message QuicKeepAliveSettings { - // The max interval for a connection to send keep-alive probing packets (with PING or PATH_RESPONSE). The value should be smaller than :ref:`connection idle_timeout ` to prevent idle timeout while not less than 1s to avoid throttling the connection or flooding the peer with probes. + // The max interval for a connection to send keep-alive probing packets (with ``PING`` or ``PATH_RESPONSE``). The value should be smaller than :ref:`connection idle_timeout ` to prevent idle timeout while not less than ``1s`` to avoid throttling the connection or flooding the peer with probes. // // If :ref:`initial_interval ` is absent or zero, a client connection will use this value to start probing. // @@ -54,20 +57,53 @@ message QuicKeepAliveSettings { } // QUIC protocol options which apply to both downstream and upstream connections. -// [#next-free-field: 10] +// [#next-free-field: 12] message QuicProtocolOptions { - // Maximum number of streams that the client can negotiate per connection. 100 + // Config for QUIC connection migration across network interfaces, i.e. cellular to WIFI, upon + // network change events from the platform, i.e. the current network gets + // disconnected, or upon the QUIC detecting a bad connection. After migration, the + // connection may be on a different network other than the default network + // picked by the platform. Both iOS and Android will use a default network to interact with the internet, usually prefer unmetered network (WIFI) + // over metered ones (cellular). And users can specify which network to be used as the default. A connection on non-default network is only allowed to + // serve new requests for a certain period of time before being drained, and + // meanwhile, QUIC will try to migrate to the default network if possible. + message ConnectionMigrationSettings { + // Config for options to migrate idle connections which aren't serving any requests. + message MigrateIdleConnectionSettings { + // If idle connections are allowed to be migrated, only migrate the connection + // if it hasn't been idle for longer than this idle period. Otherwise, the + // connection will be closed instead. + // Default to 30s. + google.protobuf.Duration max_idle_time_before_migration = 1 + [(validate.rules).duration = {gte {seconds: 1}}]; + } + + // Config whether and how to migrate idle connections. + // If absent, idle connections will not be migrated but be closed upon + // migration signals. + MigrateIdleConnectionSettings migrate_idle_connections = 1; + + // After migrating to a non-default network interface, the connection will + // only be allowed to stay on that network for up to this period of time before + // being drained unless it migrates to the default network or that network + // gets picked as the default by the device by then. + // Default to 128s. + google.protobuf.Duration max_time_on_non_default_network = 2 + [(validate.rules).duration = {gte {seconds: 1}}]; + } + + // Maximum number of streams that the client can negotiate per connection. ``100`` // if not specified. google.protobuf.UInt32Value max_concurrent_streams = 1 [(validate.rules).uint32 = {gte: 1}]; // `Initial stream-level flow-control receive window // `_ size. Valid values range from - // 1 to 16777216 (2^24, maximum supported by QUICHE) and defaults to 16777216 (16 * 1024 * 1024). + // ``1`` to ``16777216`` (``2^24``, maximum supported by QUICHE) and defaults to ``16777216`` (``16 * 1024 * 1024``). // // .. note:: // - // 16384 (2^14) is the minimum window size supported in Google QUIC. If configured smaller than it, we will use - // 16384 instead. QUICHE IETF Quic implementation supports 1 bytes window. We only support increasing the default + // ``16384`` (``2^14``) is the minimum window size supported in Google QUIC. If configured smaller than it, we will use + // ``16384`` instead. QUICHE IETF QUIC implementation supports ``1`` byte window. We only support increasing the default // window size now, so it's also the minimum. // // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the @@ -77,26 +113,26 @@ message QuicProtocolOptions { [(validate.rules).uint32 = {lte: 16777216 gte: 1}]; // Similar to ``initial_stream_window_size``, but for connection-level - // flow-control. Valid values range from 1 to 25165824 (24MB, maximum supported by QUICHE) and defaults - // to 25165824 (24 * 1024 * 1024). + // flow-control. Valid values range from ``1`` to ``25165824`` (``24MB``, maximum supported by QUICHE) and defaults + // to ``25165824`` (``24 * 1024 * 1024``). // // .. note:: // - // 16384 (2^14) is the minimum window size supported in Google QUIC. We only support increasing the default + // ``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. // google.protobuf.UInt32Value initial_connection_window_size = 3 [(validate.rules).uint32 = {lte: 25165824 gte: 1}]; // The number of timeouts that can occur before port migration is triggered for QUIC clients. - // This defaults to 4. If set to 0, port migration will not occur on path degrading. - // Timeout here refers to QUIC internal path degrading timeout mechanism, such as PTO. + // This defaults to ``4``. If set to ``0``, port migration will not occur on path degrading. + // Timeout here refers to QUIC internal path degrading timeout mechanism, such as ``PTO``. // This has no effect on server sessions. google.protobuf.UInt32Value num_timeouts_to_trigger_port_migration = 4 [(validate.rules).uint32 = {lte: 5 gte: 0}]; - // Probes the peer at the configured interval to solicit traffic, i.e. ACK or PATH_RESPONSE, from the peer to push back connection idle timeout. - // If absent, use the default keepalive behavior of which a client connection sends PINGs every 15s, and a server connection doesn't do anything. + // Probes the peer at the configured interval to solicit traffic, i.e. ``ACK`` or ``PATH_RESPONSE``, from the peer to push back connection idle timeout. + // If absent, use the default keepalive behavior of which a client connection sends ``PING``s every ``15s``, and a server connection doesn't do anything. QuicKeepAliveSettings connection_keepalive = 5; // A comma-separated list of strings representing QUIC connection options defined in @@ -108,16 +144,35 @@ message QuicProtocolOptions { string client_connection_options = 7; // The duration that a QUIC connection stays idle before it closes itself. If this field is not present, QUICHE - // default 600s will be applied. + // default ``600s`` will be applied. // For internal corporate network, a long timeout is often fine. - // But for client facing network, 30s is usually a good choice. - // Do not add an upper bound here. A long idle timeout is useful for maintaining warm connections at non-front-line proxy for low QPS services." + // But for client facing network, ``30s`` is usually a good choice. + // Do not add an upper bound here. A long idle timeout is useful for maintaining warm connections at non-front-line proxy for low QPS services. google.protobuf.Duration idle_network_timeout = 8 [(validate.rules).duration = {gte {seconds: 1}}]; // Maximum packet length for QUIC connections. It refers to the largest size of a QUIC packet that can be transmitted over the connection. // If not specified, one of the `default values in QUICHE `_ is used. google.protobuf.UInt64Value max_packet_length = 9; + + // A customized UDP socket and a QUIC packet writer using the socket for + // client connections. i.e. Mobile uses its own implementation to interact + // with platform socket APIs. + // If not present, the default platform-independent socket and writer will be used. + // [#extension-category: envoy.quic.client_packet_writer] + TypedExtensionConfig client_packet_writer = 10; + + // Enable QUIC `connection migration + // ` + // to a different network interface when the current network is degrading or + // has become bad. + // In order to use a different network interface other than the platform's default one, + // a customized :ref:`client_packet_writer ` needs to be configured to + // create UDP sockets on non-default networks. + // Only takes effect when runtime key ``envoy.reloadable_features.use_migration_in_quiche`` is true. + // If absent, the feature will be disabled. + // [#not-implemented-hide:] + ConnectionMigrationSettings connection_migration = 11; } message UpstreamHttpProtocolOptions { @@ -187,9 +242,9 @@ message AlternateProtocolsCacheOptions { // not the case. string name = 1 [(validate.rules).string = {min_len: 1}]; - // The maximum number of entries that the cache will hold. If not specified defaults to 1024. + // The maximum number of entries that the cache will hold. If not specified defaults to ``1024``. // - // .. note: + // .. note:: // // The implementation is approximate and enforced independently on each worker thread, thus // it is possible for the maximum entries in the cache to go slightly above the configured @@ -232,14 +287,14 @@ message HttpProtocolOptions { // Allow headers with underscores. This is the default behavior. ALLOW = 0; - // Reject client request. HTTP/1 requests are rejected with the 400 status. HTTP/2 requests - // end with the stream reset. The "httpN.requests_rejected_with_underscores_in_headers" counter + // Reject client request. HTTP/1 requests are rejected with ``HTTP 400`` status. HTTP/2 requests + // end with the stream reset. The ``httpN.requests_rejected_with_underscores_in_headers`` counter // is incremented for each rejected request. REJECT_REQUEST = 1; // Drop the client header with name containing underscores. The header is dropped before the filter chain is // invoked and as such filters will not see dropped headers. The - // "httpN.dropped_headers_with_underscores" is incremented for each dropped header. + // ``httpN.dropped_headers_with_underscores`` is incremented for each dropped header. DROP_HEADER = 2; } @@ -249,8 +304,12 @@ message HttpProtocolOptions { // downstream connection a drain sequence will occur prior to closing the connection, see // :ref:`drain_timeout // `. - // Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. - // If not specified, this defaults to 1 hour. To disable idle timeouts explicitly set this to 0. + // + // .. note:: + // + // Request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. + // + // If not specified, this defaults to ``1 hour``. To disable idle timeouts explicitly set this to ``0``. // // .. warning:: // Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP @@ -270,19 +329,19 @@ message HttpProtocolOptions { // The maximum number of headers (request headers if configured on HttpConnectionManager, // response headers when configured on a cluster). - // If unconfigured, the default maximum number of headers allowed is 100. + // If unconfigured, the default maximum number of headers allowed is ``100``. // The default value for requests can be overridden by setting runtime key ``envoy.reloadable_features.max_request_headers_count``. // The default value for responses can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_count``. - // Downstream requests that exceed this limit will receive a 431 response for HTTP/1.x and cause a stream + // Downstream requests that exceed this limit will receive a ``HTTP 431`` response for HTTP/1.x and cause a stream // reset for HTTP/2. - // Upstream responses that exceed this limit will result in a 502 response. + // Upstream responses that exceed this limit will result in a ``HTTP 502`` response. google.protobuf.UInt32Value max_headers_count = 2 [(validate.rules).uint32 = {gte: 1}]; // The maximum size of response headers. - // If unconfigured, the default is 60 KiB, except for HTTP/1 response headers which have a default - // of 80KiB. + // If unconfigured, the default is ``60 KiB``, except for HTTP/1 response headers which have a default + // of ``80 KiB``. // The default value can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_size_kb``. - // Responses that exceed this limit will result in a 503 response. + // Responses that exceed this limit will result in a ``HTTP 503`` response. // In Envoy, this setting is only valid when configured on an upstream cluster, not on the // :ref:`HTTP Connection Manager // `. @@ -291,8 +350,8 @@ message HttpProtocolOptions { // // Currently some protocol codecs impose limits on the maximum size of a single header. // - // * HTTP/2 (when using nghttp2) limits a single header to around 100kb. - // * HTTP/3 limits a single header to around 1024kb. + // * HTTP/2 (when using ``nghttp2``) limits a single header to around ``100kb``. + // * HTTP/3 limits a single header to around ``1024kb``. // google.protobuf.UInt32Value max_response_headers_kb = 7 [(validate.rules).uint32 = {lte: 8192 gt: 0}]; @@ -302,7 +361,7 @@ message HttpProtocolOptions { google.protobuf.Duration max_stream_duration = 4; // Action to take when a client request with a header name containing underscore characters is received. - // If this setting is not specified, the value defaults to ALLOW. + // If this setting is not specified, the value defaults to ``ALLOW``. // // .. note:: // @@ -316,7 +375,7 @@ message HttpProtocolOptions { // Optional maximum requests for both upstream and downstream connections. // If not specified, there is no limit. - // Setting this parameter to 1 will effectively disable keep alive. + // Setting this parameter to ``1`` will effectively disable keep alive. // For HTTP/2 and HTTP/3, due to concurrent stream processing, the limit is approximate. google.protobuf.UInt32Value max_requests_per_connection = 6; } @@ -341,9 +400,12 @@ message Http1ProtocolOptions { // Formats the header by proper casing words: the first character and any character following // a special character will be capitalized if it's an alpha character. For example, - // "content-type" becomes "Content-Type", and "foo$b#$are" becomes "Foo$B#$Are". - // Note that while this results in most headers following conventional casing, certain headers - // are not covered. For example, the "TE" header will be formatted as "Te". + // ``"content-type"`` becomes ``"Content-Type"``, and ``"foo$b#$are"`` becomes ``"Foo$B#$Are"``. + // + // .. note:: + // + // While this results in most headers following conventional casing, certain headers + // are not covered. For example, the ``"TE"`` header will be formatted as ``"Te"``. ProperCaseWords proper_case_words = 1; // Configuration for stateful formatter extensions that allow using received headers to @@ -359,7 +421,7 @@ message Http1ProtocolOptions { // ``http_proxy`` environment variable. google.protobuf.BoolValue allow_absolute_url = 1; - // Handle incoming HTTP/1.0 and HTTP 0.9 requests. + // 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. @@ -378,19 +440,20 @@ message Http1ProtocolOptions { // // .. attention:: // - // Note that this only happens when Envoy is chunk encoding which occurs when: + // This only happens when Envoy is chunk encoding which occurs when: // - The request is HTTP/1.1. - // - Is neither a HEAD only request nor a HTTP Upgrade. - // - Not a response to a HEAD request. - // - The content length header is not present. + // - Is neither a ``HEAD`` only request nor a HTTP Upgrade. + // - Not a response to a ``HEAD`` request. + // - The ``Content-Length`` header is not present. bool enable_trailers = 5; // 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. + // remove ``Content-Length`` header and process message. // See `RFC7230, sec. 3.3.3 `_ for details. // // .. 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 @@ -449,9 +512,12 @@ message KeepaliveSettings { google.protobuf.Duration interval = 1 [(validate.rules).duration = {gte {nanos: 1000000}}]; // How long to wait for a response to a keepalive PING. If a response is not received within this - // time period, the connection will be aborted. Note that in order to prevent the influence of - // Head-of-line (HOL) blocking the timeout period is extended when *any* frame is received on - // the connection, under the assumption that if a frame is received the connection is healthy. + // time period, the connection will be aborted. + // + // .. note:: + // + // In order to prevent the influence of Head-of-line (HOL) blocking the timeout period is extended when *any* frame is received on + // the connection, under the assumption that if a frame is received the connection is healthy. google.protobuf.Duration timeout = 2 [(validate.rules).duration = { required: true gte {nanos: 1000000} @@ -459,7 +525,7 @@ message KeepaliveSettings { // A random jitter amount as a percentage of interval that will be added to each interval. // A value of zero means there will be no jitter. - // The default value is 15%. + // The default value is ``15%``. type.v3.Percent interval_jitter = 3; // If the connection has been idle for this duration, send a HTTP/2 ping ahead @@ -473,7 +539,7 @@ message KeepaliveSettings { [(validate.rules).duration = {gte {nanos: 1000000}}]; } -// [#next-free-field: 18] +// [#next-free-field: 19] message Http2ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Http2ProtocolOptions"; @@ -496,13 +562,13 @@ message Http2ProtocolOptions { // `Maximum table size `_ // (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values - // range from 0 to 4294967295 (2^32 - 1) and defaults to 4096. 0 effectively disables header + // range from ``0`` to ``4294967295`` (``2^32 - 1``) and defaults to ``4096``. ``0`` effectively disables header // compression. google.protobuf.UInt32Value hpack_table_size = 1; // `Maximum concurrent streams `_ - // allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1) - // and defaults to 1024 for safety and should be sufficient for most use cases. + // allowed for peer on one HTTP/2 connection. Valid values range from ``1`` to ``2147483647`` (``2^31 - 1``) + // and defaults to ``1024`` for safety and should be sufficient for most use cases. // // For upstream connections, this also limits how many streams Envoy will initiate concurrently // on a single connection. If the limit is reached, Envoy may queue requests or establish @@ -515,13 +581,13 @@ message Http2ProtocolOptions { [(validate.rules).uint32 = {lte: 2147483647 gte: 1}]; // `Initial stream-level flow-control window - // `_ size. Valid values range from 65535 - // (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to - // 16MiB (16 * 1024 * 1024). + // `_ size. Valid values range from ``65535`` + // (``2^16 - 1``, HTTP/2 default) to ``2147483647`` (``2^31 - 1``, HTTP/2 maximum) and defaults to + // ``16MiB`` (``16 * 1024 * 1024``). // // .. note:: // - // 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window size now, + // ``65535`` is the initial window size from HTTP/2 spec. We only support increasing the default window size now, // so it's also the minimum. // // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the @@ -531,7 +597,7 @@ message Http2ProtocolOptions { [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; // Similar to ``initial_stream_window_size``, but for connection-level flow-control - // window. The default is 24MiB (24 * 1024 * 1024). + // window. The default is ``24MiB`` (``24 * 1024 * 1024``). google.protobuf.UInt32Value initial_connection_window_size = 4 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; @@ -549,51 +615,51 @@ message Http2ProtocolOptions { // Limit the number of pending outbound downstream frames of all types (frames that are waiting to // be written into the socket). Exceeding this limit triggers flood mitigation and connection is // terminated. The ``http2.outbound_flood`` stat tracks the number of terminated connections due - // to flood mitigation. The default limit is 10000. + // to flood mitigation. The default limit is ``10000``. google.protobuf.UInt32Value max_outbound_frames = 7 [(validate.rules).uint32 = {gte: 1}]; - // Limit the number of pending outbound downstream frames of types PING, SETTINGS and RST_STREAM, + // Limit the number of pending outbound downstream frames of types ``PING``, ``SETTINGS`` and ``RST_STREAM``, // preventing high memory utilization when receiving continuous stream of these frames. Exceeding // this limit triggers flood mitigation and connection is terminated. The // ``http2.outbound_control_flood`` stat tracks the number of terminated connections due to flood - // mitigation. The default limit is 1000. + // mitigation. The default limit is ``1000``. google.protobuf.UInt32Value max_outbound_control_frames = 8 [(validate.rules).uint32 = {gte: 1}]; - // Limit the number of consecutive inbound frames of types HEADERS, CONTINUATION and DATA with an + // Limit the number of consecutive inbound frames of types ``HEADERS``, ``CONTINUATION`` and ``DATA`` with an // empty payload and no end stream flag. Those frames have no legitimate use and are abusive, but - // might be a result of a broken HTTP/2 implementation. The `http2.inbound_empty_frames_flood`` + // might be a result of a broken HTTP/2 implementation. The ``http2.inbound_empty_frames_flood`` // stat tracks the number of connections terminated due to flood mitigation. - // Setting this to 0 will terminate connection upon receiving first frame with an empty payload - // and no end stream flag. The default limit is 1. + // Setting this to ``0`` will terminate connection upon receiving first frame with an empty payload + // and no end stream flag. The default limit is ``1``. google.protobuf.UInt32Value max_consecutive_inbound_frames_with_empty_payload = 9; - // Limit the number of inbound PRIORITY frames allowed per each opened stream. If the number - // of PRIORITY frames received over the lifetime of connection exceeds the value calculated + // Limit the number of inbound ``PRIORITY`` frames allowed per each opened stream. If the number + // 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``) // // 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 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 limit is 100. + // the number of connections terminated due to flood mitigation. The default limit is ``100``. google.protobuf.UInt32Value max_inbound_priority_frames_per_stream = 10; - // Limit the number of inbound WINDOW_UPDATE frames allowed per DATA frame sent. If the number - // of WINDOW_UPDATE frames received over the lifetime of connection exceeds the value calculated + // Limit the number of inbound ``WINDOW_UPDATE`` frames allowed per ``DATA`` frame sent. If the number + // 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 // 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, - // but more complex implementations that try to estimate available bandwidth require at least 2. + // 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, + // but more complex implementations that try to estimate available bandwidth require at least ``2``. google.protobuf.UInt32Value max_inbound_window_update_frames_per_data_frame_sent = 11 [(validate.rules).uint32 = {gte: 1}]; @@ -631,8 +697,10 @@ message Http2ProtocolOptions { // 2. SETTINGS_ENABLE_CONNECT_PROTOCOL (0x8) is only configurable through the named field // 'allow_connect'. // - // Note that custom parameters specified through this field can not also be set in the - // corresponding named parameters: + // .. note:: + // + // Custom parameters specified through this field can not also be set in the + // corresponding named parameters: // // .. code-block:: text // @@ -660,8 +728,14 @@ message Http2ProtocolOptions { 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. + // Configure the maximum amount of metadata than can be handled per stream. Defaults to ``1 MB``. google.protobuf.UInt64Value max_metadata_size = 17; + + // Controls whether to encode headers using huffman encoding. + // This can be useful in cases where the cpu spent encoding the headers isn't + // worth the network bandwidth saved e.g. for localhost. + // If unset, uses the data plane's default value. + google.protobuf.BoolValue enable_huffman_encoding = 18; } // [#not-implemented-hide:] @@ -690,7 +764,10 @@ message Http3ProtocolOptions { // `_ // and settings `proposed for HTTP/3 // `_ - // Note that HTTP/3 CONNECT is not yet an RFC. + // + // .. note:: + // + // HTTP/3 CONNECT is not yet an RFC. bool allow_extended_connect = 5 [(xds.annotations.v3.field_status).work_in_progress = true]; // [#not-implemented-hide:] Hiding until Envoy has full metadata support. @@ -705,7 +782,7 @@ message Http3ProtocolOptions { // Still under implementation. DO NOT USE. // // Disables QPACK compression related features for HTTP/3 including: - // No huffman encoding, zero dynamic table capacity and no cookie crumbing. + // No huffman encoding, zero dynamic table capacity and no cookie crumbling. // This can be useful for trading off CPU vs bandwidth when an upstream HTTP/3 connection multiplexes multiple downstream connections. bool disable_qpack = 7; @@ -718,13 +795,13 @@ message Http3ProtocolOptions { message SchemeHeaderTransformation { oneof transformation { // Overwrite any Scheme header with the contents of this string. - // If set, takes precedence over match_upstream. + // If set, takes precedence over ``match_upstream``. string scheme_to_overwrite = 1 [(validate.rules).string = {in: "http" in: "https"}]; } // Set the Scheme header to match the upstream transport protocol. For example, should a - // request be sent to the upstream over TLS, the scheme header will be set to "https". Should the - // request be sent over plaintext, the scheme header will be set to "http". - // If scheme_to_overwrite is set, this field is not used. + // request be sent to the upstream over TLS, the scheme header will be set to ``"https"``. Should the + // request be sent over plaintext, the scheme header will be set to ``"http"``. + // If ``scheme_to_overwrite`` is set, this field is not used. bool match_upstream = 2; } diff --git a/xds-api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto b/xds-api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto index a530db3dea2..2da5fe5fd4d 100644 --- a/xds-api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto +++ b/xds-api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto @@ -102,6 +102,9 @@ message ProxyProtocolConfig { // at the transport socket level and override them at the host level. // - Any TLV defined in the ``pass_through_tlvs`` field will be overridden by either the host-level // or transport socket-level TLV. + // + // If there are multiple TLVs with the same type, only the TLVs from the highest precedence level + // will be used. repeated TlvEntry added_tlvs = 3; } diff --git a/xds-api/src/main/proto/envoy/config/listener/v3/listener.proto b/xds-api/src/main/proto/envoy/config/listener/v3/listener.proto index ff2f79d1137..54ef2cfed38 100644 --- a/xds-api/src/main/proto/envoy/config/listener/v3/listener.proto +++ b/xds-api/src/main/proto/envoy/config/listener/v3/listener.proto @@ -15,7 +15,6 @@ import "envoy/config/listener/v3/udp_listener_config.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; -import "xds/annotations/v3/status.proto"; import "xds/core/v3/collection_entry.proto"; import "xds/type/matcher/v3/matcher.proto"; @@ -46,6 +45,14 @@ message AdditionalAddress { // or an empty list of :ref:`socket_options `, // it means no socket option will apply. core.v3.SocketOptionsOverride socket_options = 2; + + // Configures TCP keepalive settings for the additional address. + // If not set, the listener :ref:`tcp_keepalive ` + // configuration is inherited. You can explicitly disable TCP keepalive for the additional address by setting any keepalive field + // (:ref:`keepalive_probes `, + // :ref:`keepalive_time `, or + // :ref:`keepalive_interval `) to ``0``. + core.v3.TcpKeepalive tcp_keepalive = 3; } // Listener list collections. Entries are ``Listener`` resources or references. @@ -54,7 +61,7 @@ message ListenerCollection { repeated xds.core.v3.CollectionEntry entries = 1; } -// [#next-free-field: 37] +// [#next-free-field: 38] message Listener { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener"; @@ -141,6 +148,12 @@ message Listener { // 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. + // + // When the address contains a network namespace filepath (via + // :ref:`network_namespace_filepath `), + // Envoy automatically populates the filter state with key ``envoy.network.network_namespace`` + // when a connection is accepted. This provides read-only access to the network namespace for + // filters, access logs, and other components. core.v3.Address address = 2; // The additional addresses the listener should listen on. The addresses must be unique across all @@ -184,8 +197,7 @@ message Listener { // connections bound to the filter chain are not drained. If, however, the // filter chain is removed or structurally modified, then the drain for its // connections is initiated. - xds.type.matcher.v3.Matcher filter_chain_matcher = 32 - [(xds.annotations.v3.field_status).work_in_progress = true]; + xds.type.matcher.v3.Matcher filter_chain_matcher = 32; // 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 @@ -416,6 +428,12 @@ message Listener { // Whether the listener bypasses configured overload manager actions. bool bypass_overload_manager = 35; + + // If set, TCP keepalive settings are configured for the listener address and inherited by + // additional addresses. If not set, TCP keepalive settings are not configured for the + // listener address and additional addresses by default. See :ref:`tcp_keepalive ` + // to explicitly configure TCP keepalive settings for individual additional addresses. + core.v3.TcpKeepalive tcp_keepalive = 37; } // A placeholder proto so that users can explicitly configure the standard diff --git a/xds-api/src/main/proto/envoy/config/listener/v3/listener_components.proto b/xds-api/src/main/proto/envoy/config/listener/v3/listener_components.proto index cfa30afbb68..16b43568f39 100644 --- a/xds-api/src/main/proto/envoy/config/listener/v3/listener_components.proto +++ b/xds-api/src/main/proto/envoy/config/listener/v3/listener_components.proto @@ -250,9 +250,11 @@ message FilterChain { google.protobuf.Duration transport_socket_connect_timeout = 9; // The unique name (or empty) by which this filter chain is known. - // Note: :ref:`filter_chain_matcher - // ` - // requires that filter chains are uniquely named within a listener. + // + // .. note:: + // :ref:`filter_chain_matcher + // ` + // requires that filter chains are uniquely named within a listener. string name = 7; } diff --git a/xds-api/src/main/proto/envoy/config/listener/v3/quic_config.proto b/xds-api/src/main/proto/envoy/config/listener/v3/quic_config.proto index 6c0a5bd201f..c208a58f4a4 100644 --- a/xds-api/src/main/proto/envoy/config/listener/v3/quic_config.proto +++ b/xds-api/src/main/proto/envoy/config/listener/v3/quic_config.proto @@ -25,7 +25,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: 14] +// [#next-free-field: 15] message QuicProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.listener.QuicProtocolOptions"; @@ -99,4 +99,10 @@ message QuicProtocolOptions { // QUIC layer by replying with an empty version negotiation packet to the // client. bool reject_new_connections = 13; + + // Maximum number of QUIC sessions to create per event loop. + // If not specified, the default value is 16. + // This is an equivalent of the TCP listener option + // max_connections_to_accept_per_socket_event. + google.protobuf.UInt32Value max_sessions_per_event_loop = 14 [(validate.rules).uint32 = {gt: 0}]; } diff --git a/xds-api/src/main/proto/envoy/config/metrics/v3/metrics_service.proto b/xds-api/src/main/proto/envoy/config/metrics/v3/metrics_service.proto index 1c465b5deac..24b44b089d7 100644 --- a/xds-api/src/main/proto/envoy/config/metrics/v3/metrics_service.proto +++ b/xds-api/src/main/proto/envoy/config/metrics/v3/metrics_service.proto @@ -45,7 +45,7 @@ enum HistogramEmitMode { // "@type": type.googleapis.com/envoy.config.metrics.v3.MetricsServiceConfig // // [#extension: envoy.stat_sinks.metrics_service] -// [#next-free-field: 6] +// [#next-free-field: 7] message MetricsServiceConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.metrics.v2.MetricsServiceConfig"; @@ -70,4 +70,11 @@ message MetricsServiceConfig { // Specify which metrics types to emit for histograms. Defaults to SUMMARY_AND_HISTOGRAM. HistogramEmitMode histogram_emit_mode = 5 [(validate.rules).enum = {defined_only: true}]; + + // The maximum number of metrics to send in a single gRPC message. If not set or set to 0, + // all metrics will be sent in a single message (current behavior). When set to a positive value, + // metrics will be batched into multiple messages, with each message containing at most batch_size + // metric families. This helps avoid hitting gRPC message size limits (typically 4MB) when sending + // large numbers of metrics. + uint32 batch_size = 6 [(validate.rules).uint32 = {gte: 0}]; } diff --git a/xds-api/src/main/proto/envoy/config/metrics/v3/stats.proto b/xds-api/src/main/proto/envoy/config/metrics/v3/stats.proto index 02bb23aec9d..0fcf36c1c71 100644 --- a/xds-api/src/main/proto/envoy/config/metrics/v3/stats.proto +++ b/xds-api/src/main/proto/envoy/config/metrics/v3/stats.proto @@ -60,11 +60,6 @@ message StatsConfig { // `. They will be processed before // the custom tags. // - // .. note:: - // - // If any default tags are specified twice, the config will be considered - // invalid. - // // See :repo:`well_known_names.h ` for a list of the // default tags in Envoy. // diff --git a/xds-api/src/main/proto/envoy/config/rbac/v3/rbac.proto b/xds-api/src/main/proto/envoy/config/rbac/v3/rbac.proto index cdb1267a2c9..ef153ad177b 100644 --- a/xds-api/src/main/proto/envoy/config/rbac/v3/rbac.proto +++ b/xds-api/src/main/proto/envoy/config/rbac/v3/rbac.proto @@ -3,6 +3,7 @@ syntax = "proto3"; package envoy.config.rbac.v3; import "envoy/config/core/v3/address.proto"; +import "envoy/config/core/v3/cel.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/route/v3/route_components.proto"; import "envoy/type/matcher/v3/filter_state.proto"; @@ -173,6 +174,7 @@ message RBAC { // A policy matches if and only if at least one of its permissions match the // action taking place AND at least one of its principals match the downstream // AND the condition is true if specified. +// [#next-free-field: 6] message Policy { option (udpa.annotations.versioning).previous_message_type = "envoy.config.rbac.v2.Policy"; @@ -199,6 +201,12 @@ message Policy { // Only be used when condition is not used. google.api.expr.v1alpha1.CheckedExpr checked_condition = 4 [(udpa.annotations.field_migrate).oneof_promotion = "expression_specifier"]; + + // CEL expression configuration that modifies the evaluation behavior of the ``condition`` field. + // If specified, string conversion, concatenation, and manipulation functions may be enabled + // for the CEL expression. See :ref:`CelExpressionConfig ` + // for more details. + core.v3.CelExpressionConfig cel_config = 5; } // SourcedMetadata enables matching against metadata from different sources in the request processing diff --git a/xds-api/src/main/proto/envoy/config/route/v3/route.proto b/xds-api/src/main/proto/envoy/config/route/v3/route.proto index c4d507d22b0..5bd909f34c3 100644 --- a/xds-api/src/main/proto/envoy/config/route/v3/route.proto +++ b/xds-api/src/main/proto/envoy/config/route/v3/route.proto @@ -23,7 +23,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // * Routing :ref:`architecture overview ` // * HTTP :ref:`router filter ` -// [#next-free-field: 18] +// [#next-free-field: 19] message RouteConfiguration { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.RouteConfiguration"; @@ -129,10 +129,17 @@ message RouteConfiguration { // By default, port in :authority header (if any) is used in host matching. // With this option enabled, Envoy will ignore the port number in the :authority header (if any) when picking VirtualHost. - // 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. + // + // .. 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; + // Normally, virtual host matching is done using the :authority (or + // Host: in HTTP < 2) HTTP header. Setting this will instead, use a + // different HTTP header for this purpose. + string vhost_header = 18; + // Ignore path-parameters in path-matching. // Before RFC3986, URI were like(RFC1808): :///;?# // Envoy by default takes ":path" as ";". diff --git a/xds-api/src/main/proto/envoy/config/route/v3/route_components.proto b/xds-api/src/main/proto/envoy/config/route/v3/route_components.proto index 7364a96251e..4587ef10487 100644 --- a/xds-api/src/main/proto/envoy/config/route/v3/route_components.proto +++ b/xds-api/src/main/proto/envoy/config/route/v3/route_components.proto @@ -6,6 +6,7 @@ import "envoy/config/common/mutation_rules/v3/mutation_rules.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/proxy_protocol.proto"; +import "envoy/config/core/v3/substitution_format_string.proto"; import "envoy/type/matcher/v3/filter_state.proto"; import "envoy/type/matcher/v3/metadata.proto"; import "envoy/type/matcher/v3/regex.proto"; @@ -578,7 +579,7 @@ message ClusterSpecifierPlugin { bool is_optional = 2; } -// [#next-free-field: 17] +// [#next-free-field: 18] message RouteMatch { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteMatch"; @@ -713,6 +714,11 @@ message RouteMatch { // parameter is "foo%20bar", the message field will be "foo bar". repeated QueryParameterMatcher query_parameters = 7; + // Specifies a set of cookies on which the route should match. The router parses the ``Cookie`` + // header and evaluates the named cookie against each matcher. If the number of specified cookie + // matchers is nonzero, they all must match for the route to be selected. + repeated CookieMatcher cookies = 17; + // If specified, only gRPC requests will be matched. The router will check // that the ``Content-Type`` header has ``application/grpc`` or one of the various // ``application/grpc+`` values. @@ -805,7 +811,7 @@ message CorsPolicy { google.protobuf.BoolValue forward_not_matching_preflights = 13; } -// [#next-free-field: 43] +// [#next-free-field: 46] message RouteAction { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction"; @@ -1181,9 +1187,11 @@ message RouteAction { // place the original path before rewrite into the :ref:`x-envoy-original-path // ` header. // - // Only one of :ref:`regex_rewrite ` + // Only one of :ref:`regex_rewrite `, // :ref:`path_rewrite_policy `, - // or :ref:`prefix_rewrite ` may be specified. + // :ref:`path_rewrite `, + // or :ref:`prefix_rewrite ` + // may be specified. // // .. attention:: // @@ -1219,8 +1227,9 @@ message RouteAction { // ` header. // // Only one of :ref:`regex_rewrite `, - // :ref:`prefix_rewrite `, or - // :ref:`path_rewrite_policy `] + // :ref:`path_rewrite_policy `, + // :ref:`path_rewrite `, + // or :ref:`prefix_rewrite ` // may be specified. // // Examples using Google's `RE2 `_ engine: @@ -1244,6 +1253,33 @@ message RouteAction { // [#extension-category: envoy.path.rewrite] core.v3.TypedExtensionConfig path_rewrite_policy = 41; + // Rewrites the whole path (without query parameters) with the given path value. + // The router filter will + // place the original path before rewrite into the :ref:`x-envoy-original-path + // ` header. + // + // Only one of :ref:`regex_rewrite `, + // :ref:`path_rewrite_policy `, + // :ref:`path_rewrite `, + // or :ref:`prefix_rewrite ` + // may be specified. + // + // The :ref:`substitution format specifier ` could be applied here. + // For example, with the following config: + // + // .. code-block:: yaml + // + // path_rewrite: "/new_path_prefix%REQ(custom-path-header-name)%" + // + // Would rewrite the path to ``/new_path_prefix/some_value`` given the header + // ``custom-path-header-name: some_value``. If the header is not present, the path will be + // rewritten to ``/new_path_prefix``. + // + // + // If the final output of the path rewrite is empty, then the update will be ignored and the + // original path will be preserved. + string path_rewrite = 45; + // If one of the host rewrite specifiers is set and the // :ref:`suppress_envoy_headers // ` flag is not @@ -1302,6 +1338,25 @@ message RouteAction { // // Would rewrite the host header to ``envoyproxy.io`` given the path ``/envoyproxy.io/some/path``. type.matcher.v3.RegexMatchAndSubstitute host_rewrite_path_regex = 35; + + // Rewrites the host header with the value of this field. The router filter will + // place the original host header value before rewriting into the :ref:`x-envoy-original-host + // ` header. + // + // The :ref:`substitution format specifier ` could be applied here. + // For example, with the following config: + // + // .. code-block:: yaml + // + // host_rewrite: "prefix-%REQ(custom-host-header-name)%" + // + // Would rewrite the host header to ``prefix-some_value`` given the header + // ``custom-host-header-name: some_value``. If the header is not present, the host header will + // be rewritten to an value of ``prefix-``. + // + // If the final output of the host rewrite is empty, then the update will be ignored and the + // original host header will be preserved. + string host_rewrite = 44; } // If set, then a host rewrite action (one of @@ -1893,6 +1948,12 @@ message DirectResponseAction { // :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; + + // Specifies a format string for the response body. If present, the contents of + // ``body_format`` will be formatted and used as the response body, where the + // contents of ``body`` (may be empty) will be passed as the variable ``%LOCAL_REPLY_BODY%``. + // If neither are provided, no body is included in the generated response. + core.v3.SubstitutionFormatString body_format = 3; } // [#not-implemented-hide:] @@ -1916,6 +1977,7 @@ message Decorator { google.protobuf.BoolValue propagate = 2; } +// [#next-free-field: 7] message Tracing { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Tracing"; @@ -1951,6 +2013,34 @@ message Tracing { // each in the HTTP connection manager and the route level, the one configured here takes // priority. repeated type.tracing.v3.CustomTag custom_tags = 4; + + // The operation name of the span which will be used for tracing. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // This field will take precedence over and make following settings ineffective: + // + // * :ref:`route decorator `. + // * :ref:`x-envoy-decorator-operation `. + // * :ref:`HCM tracing operation + // `. + string operation = 5; + + // The operation name of the upstream span which will be used for tracing. + // This only takes effect when ``spawn_upstream_span`` is set to true and the upstream + // span is created. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // This field will take precedence over and make following settings ineffective: + // + // * :ref:`HCM tracing upstream operation + // ` + string upstream_operation = 6; } // A virtual cluster is a way of specifying a regex matching rule against @@ -2142,9 +2232,40 @@ message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action.GenericKey"; - // The value to use in the descriptor entry. + // Descriptor value of entry. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // .. note:: + // + // Formatter parsing is controlled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` + // (disabled by default). + // + // When enabled: The format string can contain multiple valid substitution + // fields. If multiple substitution fields are present, their results will be concatenated + // to form the final descriptor value. If it contains no substitution fields, the value + // will be used as is. If the final concatenated result is empty and ``default_value`` is set, + // the ``default_value`` will be used. If ``default_value`` is not set and the result is + // empty, this descriptor will be skipped and not included in the rate limit call. + // + // When disabled (default): The descriptor_value is used as a literal string without any formatter + // parsing or substitution. + // + // For example, ``static_value`` will be used as is since there are no substitution fields. + // ``%REQ(:method)%`` will be replaced with the HTTP method, and + // ``%REQ(:method)%%REQ(:path)%`` will be replaced with the concatenation of the HTTP method and path. + // ``%CEL(request.headers['user-id'])%`` will use CEL to extract the user ID from request headers. + // string descriptor_value = 1 [(validate.rules).string = {min_len: 1}]; + // An optional value to use if the final concatenated ``descriptor_value`` result is empty. + // Only applicable when formatter parsing is enabled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` (disabled by default). + string default_value = 3; + // An optional key to use in the descriptor entry. If not set it defaults // to 'generic_key' as the descriptor key. string descriptor_key = 2; @@ -2155,18 +2276,51 @@ message RateLimit { // .. code-block:: cpp // // ("header_match", "") + // [#next-free-field: 6] message HeaderValueMatch { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch"; + // Descriptor value of entry. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // .. note:: + // + // Formatter parsing is controlled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` + // (disabled by default). + // + // When enabled: The format string can contain multiple valid substitution + // fields. If multiple substitution fields are present, their results will be concatenated + // to form the final descriptor value. If it contains no substitution fields, the value + // will be used as is. All substitution fields will be evaluated and their results + // concatenated. If the final concatenated result is empty and ``default_value`` is set, + // the ``default_value`` will be used. If ``default_value`` is not set and the result is + // empty, this descriptor will be skipped and not included in the rate limit call. + // + // When disabled (default): The descriptor_value is used as a literal string without any formatter + // parsing or substitution. + // + // For example, ``static_value`` will be used as is since there are no substitution fields. + // ``%REQ(:method)%`` will be replaced with the HTTP method, and + // ``%REQ(:method)%%REQ(:path)%`` will be replaced with the concatenation of the HTTP method and path. + // ``%CEL(request.headers['user-id'])%`` will use CEL to extract the user ID from request headers. + // + string descriptor_value = 1 [(validate.rules).string = {min_len: 1}]; + + // An optional value to use if the final concatenated ``descriptor_value`` result is empty. + // Only applicable when formatter parsing is enabled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` (disabled by default). + string default_value = 5; + // The key to use in the descriptor entry. // // Defaults to ``header_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 @@ -2174,7 +2328,7 @@ message RateLimit { google.protobuf.BoolValue expect_match = 2; // Specifies a set of headers that the rate limit action should match - // on. The action will check the request’s headers against all the + // on. The action will check the request's headers against all the // specified headers in the 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). @@ -2254,15 +2408,48 @@ message RateLimit { // .. code-block:: cpp // // ("query_match", "") + // [#next-free-field: 6] message QueryParameterValueMatch { + // Descriptor value of entry. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // .. note:: + // + // Formatter parsing is controlled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` + // (disabled by default). + // + // When enabled: The format string can contain multiple valid substitution + // fields. If multiple substitution fields are present, their results will be concatenated + // to form the final descriptor value. If it contains no substitution fields, the value + // will be used as is. All substitution fields will be evaluated and their results + // concatenated. If the final concatenated result is empty and ``default_value`` is set, + // the ``default_value`` will be used. If ``default_value`` is not set and the result is + // empty, this descriptor will be skipped and not included in the rate limit call. + // + // When disabled (default): The descriptor_value is used as a literal string without any formatter + // parsing or substitution. + // + // For example, ``static_value`` will be used as is since there are no substitution fields. + // ``%REQ(:method)%`` will be replaced with the HTTP method, and + // ``%REQ(:method)%%REQ(:path)%`` will be replaced with the concatenation of the HTTP method and path. + // ``%CEL(request.headers['user-id'])%`` will use CEL to extract the user ID from request headers. + // + string descriptor_value = 1 [(validate.rules).string = {min_len: 1}]; + + // An optional value to use if the final concatenated ``descriptor_value`` result is empty. + // Only applicable when formatter parsing is enabled by the runtime feature flag + // ``envoy.reloadable_features.enable_formatter_for_ratelimit_action_descriptor_value`` (disabled by default). + string default_value = 5; + // 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 @@ -2270,7 +2457,7 @@ message RateLimit { 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 + // 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). @@ -2648,6 +2835,20 @@ message QueryParameterMatcher { } } +// Cookie matching inspects individual name/value pairs parsed from the ``Cookie`` header. +message CookieMatcher { + // Specifies the cookie name to evaluate. + string name = 1 [(validate.rules).string = {min_len: 1 max_bytes: 1024}]; + + // Match the cookie value using :ref:`StringMatcher + // ` semantics. + type.matcher.v3.StringMatcher string_match = 2 [(validate.rules).message = {required: true}]; + + // Invert the match result. If the cookie is not present, the match result is false, so + // ``invert_match`` will cause the matcher to succeed when the cookie is absent. + bool invert_match = 3; +} + // HTTP Internal Redirect :ref:`architecture overview `. // [#next-free-field: 6] message InternalRedirectPolicy { @@ -2713,6 +2914,5 @@ message FilterConfig { // initial route will not be added back to the filter chain because the filter chain is already // created and it is too late to change the chain. // - // This field only make sense for the downstream HTTP filters for now. bool disabled = 3; } diff --git a/xds-api/src/main/proto/envoy/config/trace/v3/zipkin.proto b/xds-api/src/main/proto/envoy/config/trace/v3/zipkin.proto index 7405c596ed5..2364983efc5 100644 --- a/xds-api/src/main/proto/envoy/config/trace/v3/zipkin.proto +++ b/xds-api/src/main/proto/envoy/config/trace/v3/zipkin.proto @@ -61,16 +61,22 @@ message ZipkinConfig { } // The cluster manager cluster that hosts the Zipkin collectors. - // Note: This field will be deprecated in future releases in favor of - // :ref:`collector_service `. - // Either this field or collector_service must be specified. + // + // .. note:: + // This field will be deprecated in future releases in favor of + // :ref:`collector_service `. + // + // Either this field or ``collector_service`` must be specified. string collector_cluster = 1; // The API endpoint of the Zipkin service where the spans will be sent. When // using a standard Zipkin installation. - // Note: This field will be deprecated in future releases in favor of - // :ref:`collector_service `. - // Required when using collector_cluster. + // + // .. note:: + // This field will be deprecated in future releases in favor of + // :ref:`collector_service `. + // + // Required when using ``collector_cluster``. string collector_endpoint = 2; // Determines whether a 128bit trace id will be used when creating a new @@ -86,8 +92,10 @@ 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. - // Note: This field will be deprecated in future releases in favor of - // :ref:`collector_service `. + // + // .. note:: + // This field will be deprecated in future releases in favor of + // :ref:`collector_service `. 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 diff --git a/xds-api/src/main/proto/envoy/data/tap/v3/transport.proto b/xds-api/src/main/proto/envoy/data/tap/v3/transport.proto index 8aef689782b..5f929bcf81d 100644 --- a/xds-api/src/main/proto/envoy/data/tap/v3/transport.proto +++ b/xds-api/src/main/proto/envoy/data/tap/v3/transport.proto @@ -20,7 +20,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // sequences on a socket. // Event in a socket trace. -// [#next-free-field: 6] +// [#next-free-field: 7] message SocketEvent { option (udpa.annotations.versioning).previous_message_type = "envoy.data.tap.v2alpha.SocketEvent"; @@ -69,6 +69,9 @@ message SocketEvent { // Connection information per event Connection connection = 5; + + // Data sequence number + uint64 seq_num = 6; } // Sequence of read/write events that constitute a buffered trace on a socket. diff --git a/xds-api/src/main/proto/envoy/extensions/access_loggers/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/access_loggers/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000000..c169fe28048 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/access_loggers/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,76 @@ +syntax = "proto3"; + +package envoy.extensions.access_loggers.dynamic_modules.v3; + +import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto"; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.access_loggers.dynamic_modules.v3"; +option java_outer_classname = "DynamicModulesProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/access_loggers/dynamic_modules/v3;dynamic_modulesv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Dynamic Modules Access Logger] +// [#extension: envoy.access_loggers.dynamic_modules] + +// Configuration for the Dynamic Modules Access Logger. This logger allows loading shared object +// files via ``dlopen`` to implement custom access logging behavior. +// +// A module can be loaded by multiple access loggers; the module is loaded only once and shared +// across multiple logger instances. +// +// The access logger receives completed request information including request/response headers, +// stream info (timing, upstream info, response codes), and the log context type. +message DynamicModuleAccessLog { + // Specifies the shared-object level configuration. This field is required. + envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1 + [(validate.rules).message = {required: true}]; + + // The name for this logger configuration. If not specified, defaults to an empty string. + // + // This can be used to distinguish between different logger implementations inside a dynamic + // module. For example, a module can have completely different logger implementations (e.g., + // file logger, gRPC logger, metrics logger). When Envoy receives this configuration, it passes + // the ``logger_name`` to the dynamic module's access logger config init function together with + // the ``logger_config``. That way a module can decide which in-module logger implementation to + // use based on the name at load time. + string logger_name = 2; + + // The configuration for the logger chosen by ``logger_name``. If not specified, an empty + // configuration is passed to the module. + // + // This is passed to the module's access logger initialization function. Together with the + // ``logger_name``, the module can decide which in-module logger implementation to use and + // fine-tune the behavior of the logger. + // + // For example, if a module has two logger implementations, one for file output and one for + // sending to an external service, ``logger_name`` is used to choose either file or external. + // The ``logger_config`` can be used to configure file paths, service endpoints, batching + // parameters, format strings, etc. + // + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly + // without the wrapper. + // + // .. code-block:: yaml + // + // # Passing a JSON struct configuration + // logger_config: + // "@type": "type.googleapis.com/google.protobuf.Struct" + // value: + // output_path: "/var/log/envoy/access.log" + // format: "json" + // buffer_size: 1000 + // + // # Passing a simple string configuration + // logger_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: "/var/log/envoy/access.log" + // + google.protobuf.Any logger_config = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/cel/v3/cel.proto b/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/cel/v3/cel.proto index 750ffd30d25..72251c6bfb0 100644 --- a/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/cel/v3/cel.proto +++ b/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/cel/v3/cel.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.access_loggers.filters.cel.v3; +import "envoy/config/core/v3/cel.proto"; + import "udpa/annotations/status.proto"; option java_package = "io.envoyproxy.envoy.extensions.access_loggers.filters.cel.v3"; @@ -25,4 +27,10 @@ message ExpressionFilter { // * ``response.code >= 400`` // * ``(connection.mtls && request.headers['x-log-mtls'] == 'true') || request.url_path.contains('v1beta3')`` string expression = 1; + + // CEL expression configuration that modifies the evaluation behavior of the ``expression`` field. + // If specified, string conversion, concatenation, and manipulation functions may be enabled + // for the filter expression. See :ref:`CelExpressionConfig ` + // for more details. + config.core.v3.CelExpressionConfig cel_config = 2; } diff --git a/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/process_ratelimit/v3/process_ratelimit.proto b/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/process_ratelimit/v3/process_ratelimit.proto new file mode 100644 index 00000000000..6b60a691d2f --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/access_loggers/filters/process_ratelimit/v3/process_ratelimit.proto @@ -0,0 +1,32 @@ +syntax = "proto3"; + +package envoy.extensions.access_loggers.filters.process_ratelimit.v3; + +import "envoy/config/core/v3/config_source.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.access_loggers.filters.process_ratelimit.v3"; +option java_outer_classname = "ProcessRatelimitProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/access_loggers/filters/process_ratelimit/v3;process_ratelimitv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: ProcessRateLimiter] +// [#extension: envoy.access_loggers.extension_filters.process_ratelimit] + +// Filters for rate limiting the access log emission using global token buckets per process and shared across all listeners. +message ProcessRateLimitFilter { + // The dynamic config for the token bucket. + DynamicTokenBucket dynamic_config = 1; +} + +message DynamicTokenBucket { + // the key used to find the token bucket in the singleton map. + string resource_name = 1 [(validate.rules).string = {min_len: 1}]; + + // The configuration source for the :ref:`token_bucket `. + // It should stay the same through the process lifetime. + config.core.v3.ConfigSource config_source = 2 [(validate.rules).message = {required: true}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/access_loggers/open_telemetry/v3/logs_service.proto b/xds-api/src/main/proto/envoy/extensions/access_loggers/open_telemetry/v3/logs_service.proto index 641276a64bd..ccb1ac479af 100644 --- a/xds-api/src/main/proto/envoy/extensions/access_loggers/open_telemetry/v3/logs_service.proto +++ b/xds-api/src/main/proto/envoy/extensions/access_loggers/open_telemetry/v3/logs_service.proto @@ -3,12 +3,18 @@ syntax = "proto3"; package envoy.extensions.access_loggers.open_telemetry.v3; import "envoy/config/core/v3/extension.proto"; +import "envoy/config/core/v3/grpc_service.proto"; +import "envoy/config/core/v3/http_service.proto"; import "envoy/extensions/access_loggers/grpc/v3/als.proto"; +import "envoy/type/tracing/v3/custom_tag.proto"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; import "opentelemetry/proto/common/v1/common.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; -import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.access_loggers.open_telemetry.v3"; option java_outer_classname = "LogsServiceProto"; @@ -16,17 +22,37 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/access_loggers/open_telemetry/v3;open_telemetryv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: OpenTelemetry (gRPC) Access Log] +// [#protodoc-title: OpenTelemetry Access Log] // Configuration for the built-in ``envoy.access_loggers.open_telemetry`` // :ref:`AccessLog `. This configuration will // populate `opentelemetry.proto.collector.v1.logs.ExportLogsServiceRequest.resource_logs `_. // In addition, the request start time is set in the dedicated field. // [#extension: envoy.access_loggers.open_telemetry] -// [#next-free-field: 8] +// [#next-free-field: 15] message OpenTelemetryAccessLogConfig { // [#comment:TODO(itamarkam): add 'filter_state_objects_to_log' to logs.] - grpc.v3.CommonGrpcAccessLogConfig common_config = 1 [(validate.rules).message = {required: true}]; + // Deprecated. Use ``grpc_service`` or ``http_service`` instead. + grpc.v3.CommonGrpcAccessLogConfig common_config = 1 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; + + // The upstream HTTP cluster that will receive OTLP logs via + // `OTLP/HTTP `_. + // Note: Only one of ``common_config``, ``grpc_service``, or ``http_service`` may be used. + // + // .. note:: + // + // The ``request_headers_to_add`` property in the OTLP HTTP exporter service + // does not support the :ref:`format specifier ` as used for + // :ref:`HTTP access logging `. + // The values configured are added as HTTP headers on the OTLP export request + // without any formatting applied. + config.core.v3.HttpService http_service = 8; + + // The upstream gRPC cluster that will receive OTLP logs. + // Note: Only one of ``common_config``, ``grpc_service``, or ``http_service`` may be used. + // This field is preferred over ``common_config.grpc_service``. + config.core.v3.GrpcService grpc_service = 9; // If specified, Envoy will not generate built-in resource labels // like ``log_name``, ``zone_name``, ``cluster_name``, ``node_name``. @@ -57,4 +83,19 @@ message OpenTelemetryAccessLogConfig { // See the formatters extensions documentation for details. // [#extension-category: envoy.formatter] repeated config.core.v3.TypedExtensionConfig formatters = 7; + + string log_name = 10; + + // The interval for flushing access logs to the transport. Default: 1 second. + google.protobuf.Duration buffer_flush_interval = 11; + + // Soft size limit in bytes for the access log buffer. When the buffer exceeds + // this limit, logs will be flushed. Default: 16KB. + google.protobuf.UInt32Value buffer_size_bytes = 12; + + // Additional filter state objects to log as attributes. + repeated string filter_state_objects_to_log = 13; + + // Custom tags to include as log attributes. + repeated type.tracing.v3.CustomTag custom_tags = 14; } diff --git a/xds-api/src/main/proto/envoy/extensions/access_loggers/stats/v3/stats.proto b/xds-api/src/main/proto/envoy/extensions/access_loggers/stats/v3/stats.proto new file mode 100644 index 00000000000..bcb1296c42c --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/access_loggers/stats/v3/stats.proto @@ -0,0 +1,102 @@ +syntax = "proto3"; + +package envoy.extensions.access_loggers.stats.v3; + +import "google/protobuf/wrappers.proto"; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.access_loggers.stats.v3"; +option java_outer_classname = "StatsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/access_loggers/stats/v3;statsv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Stats logger] +// Configuration for an access logger that emits custom Envoy stats according to its +// configuration. The stats can have tags and values derived from +// :ref:`command operators `. +// [#extension: envoy.access_loggers.stats] +// +// .. warning:: +// It is easy to configure and use this extension in ways that create very +// large numbers of stats in Envoy, which can cause excessive memory or CPU use +// leading to a denial of service in Envoy, or can overwhelm any configured +// stat sinks by sending too many unique metrics. + +message Config { + option (xds.annotations.v3.message_status).work_in_progress = true; + + // Defines a tag on a stat. + message Tag { + // The name of the tag. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // The value of the tag, using :ref:`command operators `. + string value_format = 2 [(validate.rules).string = {min_len: 1}]; + } + + // Defines the name and tags of a stat. + message Stat { + // The name of the stat. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // The tags for the stat. + repeated Tag tags = 2; + } + + // Configuration for a histogram stat. + message Histogram { + // The histogram units. The units are needed for some stat sinks. + enum Unit { + Unspecified = 0; + + Bytes = 1; + + Microseconds = 2; + + Milliseconds = 3; + + // Values are scaled to range 0-1.0, indicating 0%-100%. Values can be outside this range, + // but must be positive. Values extremely far out of this range may overflow. + Percent = 4; + } + + // The name and tags of this histogram. + Stat stat = 1 [(validate.rules).message = {required: true}]; + + // The units for this histogram. + Unit unit = 2 [(validate.rules).enum = {defined_only: true}]; + + // The format string for the value of this histogram, using :ref:`command operators `. + // This must evaluate to a positive number. + string value_format = 3 [(validate.rules).string = {min_len: 1 prefix: "%" suffix: "%"}]; + } + + // Configuration for a counter stat. + message Counter { + // The name and tags of this counter. + Stat stat = 1 [(validate.rules).message = {required: true}]; + + // The format string for the value to add to this counter, using :ref:`command operators `. + // One of ``value_format`` or ``value_fixed`` must be configured. + string value_format = 2 + [(validate.rules).string = {prefix: "%" suffix: "%" ignore_empty: true}]; + + // A fixed value to add to this counter. + // One of ``value_format`` or ``value_fixed`` must be configured. + google.protobuf.UInt64Value value_fixed = 3 [(validate.rules).uint64 = {gt: 0}]; + } + + // The stat prefix for the generated stats. + string stat_prefix = 1 [(validate.rules).string = {min_len: 1}]; + + // The histograms this logger will emit. + repeated Histogram histograms = 3; + + // The counters this logger will emit. + repeated Counter counters = 4; +} diff --git a/xds-api/src/main/proto/envoy/extensions/bootstrap/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/bootstrap/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000000..a0c406bd98f --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/bootstrap/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,74 @@ +syntax = "proto3"; + +package envoy.extensions.bootstrap.dynamic_modules.v3; + +import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto"; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.bootstrap.dynamic_modules.v3"; +option java_outer_classname = "DynamicModulesProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/bootstrap/dynamic_modules/v3;dynamic_modulesv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Dynamic Modules Bootstrap Extension] +// [#extension: envoy.bootstrap.dynamic_modules] + +// Configuration for the Dynamic Modules bootstrap extension. This extension allows loading shared +// object files that can be loaded via ``dlopen`` to extend Envoy's bootstrap behavior. +// +// A module can be loaded by multiple bootstrap extensions; the module is loaded only once and shared +// across multiple extensions. +// +// Bootstrap extensions run on the main thread and are initialized when Envoy starts. They can: +// +// * Perform initialization tasks when the server is initialized. +// * Perform per-worker thread initialization when worker threads start. +// * Access server-level resources like the cluster manager and dispatcher. +// +message DynamicModuleBootstrapExtension { + // Specifies the shared-object level configuration. + envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; + + // The name for this extension configuration. + // + // This can be used to distinguish between different extension implementations inside a dynamic + // module. For example, a module can have completely different extension implementations. When Envoy + // receives this configuration, it passes the ``extension_name`` to the dynamic module's bootstrap + // extension config init function together with the ``extension_config``. That way a module can + // decide which in-module extension implementation to use based on the name at load time. + // + // If not specified, defaults to an empty string. + string extension_name = 2; + + // The configuration for the extension chosen by ``extension_name``. + // + // This is passed to the module's bootstrap extension initialization function. Together with the + // ``extension_name``, the module can decide which in-module extension implementation to use and + // fine-tune the behavior of the extension. + // + // For example, if a module has two extension implementations, one for configuration loading and + // one for metric initialization, ``extension_name`` is used to choose the implementation. The + // ``extension_config`` can be used to configure the specific behavior of each implementation. + // + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly + // without the wrapper. + // + // .. code-block:: yaml + // + // # Passing a string value + // extension_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: hello + // + // # Passing raw bytes + // extension_config: + // "@type": "type.googleapis.com/google.protobuf.BytesValue" + // value: aGVsbG8= # echo -n "hello" | base64 + // + google.protobuf.Any extension_config = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto b/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto index fba8cdee84e..72994c07973 100644 --- a/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto +++ b/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto @@ -17,11 +17,22 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // This interface initiates reverse connections to upstream Envoys and provides // them as socket connections for downstream requests. message DownstreamReverseConnectionSocketInterface { + // HTTP handshake settings for initiator envoy initiated reverse tunnels. + message HttpHandshakeConfig { + // Request path used when issuing the HTTP reverse-connection handshake. Defaults to + // "/reverse_connections/request". + string request_path = 1; + } + // Stat prefix to be used for downstream reverse connection socket interface stats. string stat_prefix = 1; // Enable detailed per-host and per-cluster statistics. // When enabled, emits hidden statistics for individual hosts and clusters. - // Defaults to false. + // Defaults to ``false``. bool enable_detailed_stats = 2; + + // Optional HTTP handshake configuration. When unset, the initiator envoy uses the defaults + // provided by ``HttpHandshakeConfig``. + HttpHandshakeConfig http_handshake = 3; } diff --git a/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto b/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto index 2ba83ac88b8..d1d3b36a8b4 100644 --- a/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto +++ b/xds-api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.bootstrap.reverse_tunnel.upstream_socket_interface.v3; +import "envoy/config/core/v3/extension.proto"; + import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; @@ -29,4 +31,9 @@ message UpstreamReverseConnectionSocketInterface { // When enabled, emits hidden statistics for individual nodes and clusters. // Defaults to false. bool enable_detailed_stats = 3; + + // Optional configuration for a tunnel reporting extension. When provided, + // the socket interface instantiates a reporter via the configured factory. + // If unset, no reporting is done. + config.core.v3.TypedExtensionConfig reporter_config = 4; } diff --git a/xds-api/src/main/proto/envoy/extensions/clusters/composite/v3/cluster.proto b/xds-api/src/main/proto/envoy/extensions/clusters/composite/v3/cluster.proto new file mode 100644 index 00000000000..475f8d1cad9 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/clusters/composite/v3/cluster.proto @@ -0,0 +1,55 @@ +syntax = "proto3"; + +package envoy.extensions.clusters.composite.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.clusters.composite.v3"; +option java_outer_classname = "ClusterProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/clusters/composite/v3;compositev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Composite cluster configuration] + +// Configuration for the composite cluster. See the :ref:`architecture overview +// ` for more information. This cluster type enables retry-aware +// cluster selection, allowing different retry attempts to automatically target +// different upstream clusters. Unlike the standard aggregate cluster which uses +// health-based selection, the composite cluster uses the retry attempt count to +// deterministically select which sub-cluster to route to. +// +// When retry attempts exceed the number of configured clusters, requests will fail with no +// host available. +// +// Example configuration: +// +// .. code-block:: yaml +// +// name: composite_cluster +// connect_timeout: 0.25s +// lb_policy: CLUSTER_PROVIDED +// cluster_type: +// name: envoy.clusters.composite +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.clusters.composite.v3.ClusterConfig +// clusters: +// - name: primary_cluster +// - name: secondary_cluster +// - name: fallback_cluster +// +// [#extension: envoy.clusters.composite] +message ClusterConfig { + // Configuration for an individual cluster entry. + message ClusterEntry { + // Name of the cluster. This cluster must be defined elsewhere in the configuration. + string name = 1 [(validate.rules).string = {min_len: 1}]; + } + + // List of clusters to use for request routing. The first cluster is used for the + // initial request (attempt 1), the second cluster for the first retry (attempt 2), + // and so on. Must contain at least one cluster. When retry attempts exceed the number + // of configured clusters, requests will fail with no host available. + repeated ClusterEntry clusters = 1 [(validate.rules).repeated = {min_items: 1}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto b/xds-api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto index e51ade1318d..45ecf9b64ea 100644 --- a/xds-api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto +++ b/xds-api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto @@ -77,8 +77,10 @@ message InlineCredentialProvider { // to retrieve AWS credentials. message AssumeRoleWithWebIdentityCredentialProvider { // Data source for a web identity token that is provided by the identity provider to assume the role. - // When using this data source, even if a ``watched_directory`` is provided, the token file will only be re-read when the credentials - // returned from AssumeRoleWithWebIdentity expire. + // If a ``watched_directory`` is not provided, one will be automatically inferred from the directory of the token file. This is to ensure + // that if the token file is rotated, the new token will be picked up. This behaviour differs from the standard envoy data source behavior, which does not + // automatically watch the directory of a file data source. + // Even when file rotation occurs, current credentials will continue to be used until they expire, at which point new credentials will be retrieved using the new token. config.core.v3.DataSource web_identity_token_data_source = 1 [(udpa.annotations.sensitive) = true]; diff --git a/xds-api/src/main/proto/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto index 0971d501a2d..46d44802868 100644 --- a/xds-api/src/main/proto/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto +++ b/xds-api/src/main/proto/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto @@ -11,46 +11,59 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/dynamic_modules/v3;dynamic_modulesv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Dynamic Modules common configuration] +// [#protodoc-title: Dynamic Modules Common Configuration] -// Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via dlopen -// by various Envoy extension points. Currently, only HTTP filter (envoy.filters.http.dynamic_modules) is supported. +// Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via +// ``dlopen`` by various Envoy extension points. // -// How a module is loaded is determined by the extension point that uses it. For example, the HTTP filter -// loads the module with dlopen when Envoy receives a configuration that references the module at load time. -// If loading the module fails, the configuration will be rejected. +// How a module is loaded is determined by the extension point that uses it. For example, the HTTP +// filter loads the module when Envoy receives a configuration that references the module. If loading +// the module fails, the configuration will be rejected. // -// Whether or not the shared object is the same is determined by the file path as well as the file's inode depending -// on the platform. Notably, if the file path and the content of the file are the same, the shared object will be reused. +// A module is uniquely identified by its file path and the file's inode, depending on the platform. +// Notably, if the file path and the content of the file are the same, the shared object will be +// reused. // -// A module must be compatible with the ABI specified in :repo:`abi.h `. -// Currently, compatibility is only guaranteed by an exact version match between the Envoy -// codebase and the dynamic module SDKs. In the future, after the ABI is stabilized, we will revisit -// this restriction and hopefully provide a wider compatibility guarantee. Until then, Envoy -// checks the hash of the ABI header files to ensure that the dynamic modules are built against the -// same version of the ABI. +// A module must be compatible with the ABI specified in :repo:`abi.h +// `. Currently, compatibility is only guaranteed by an +// exact version match between the Envoy codebase and the dynamic module SDKs. In the future, after +// the ABI is stabilized, this restriction will be revisited. Until then, Envoy checks the hash of +// the ABI header files to ensure that the dynamic modules are built against the same version of the +// ABI. message DynamicModuleConfig { - // The name of the dynamic module. The client is expected to have some configuration indicating where to search for the module. - // In Envoy, the search path can only be configured via the environment variable ``ENVOY_DYNAMIC_MODULES_SEARCH_PATH``. - // The actual search path is ``${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so``. TODO: make the search path configurable via - // command line options. + // The name of the dynamic module. + // + // The client is expected to have some configuration indicating where to search for the module. In + // Envoy, the search path can only be configured via the environment variable + // ``ENVOY_DYNAMIC_MODULES_SEARCH_PATH``. The actual search path is + // ``${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so``. + // + // .. note:: + // There is some remaining work to make the search path configurable via command line options. string name = 1 [(validate.rules).string = {min_len: 1}]; - // Set true to prevent the module from being unloaded with dlclose. - // This is useful for modules that have global state that should not be unloaded. - // A module is closed when no more references to it exist in the process. For example, - // no HTTP filters are using the module (e.g. after configuration update). + // If true, prevents the module from being unloaded with ``dlclose``. + // + // This is useful for modules that have global state that should not be unloaded. A module is + // closed when no more references to it exist in the process. For example, no HTTP filters are + // using the module (e.g. after configuration update). + // + // Defaults to ``false``. bool do_not_close = 3; - // The dynamic module is loaded with ``RTLD_LOCAL`` flag to avoid symbol conflicts when multiple - // modules are loaded by default. Set this to true to load the module with ``RTLD_GLOBAL`` flag. - // This is useful for modules that need to share symbols with other dynamic libraries. For - // example, a module X may load another shared library Y that depends on some symbols defined - // in module X. In this case, module X must be loaded with ``RTLD_GLOBAL`` flag so that the - // symbols defined in module X are visible to library Y. + // If true, the dynamic module is loaded with the ``RTLD_GLOBAL`` flag. + // + // The dynamic module is loaded with the ``RTLD_LOCAL`` flag by default to avoid symbol conflicts + // when multiple modules are loaded. Set this to ``true`` to load the module with the + // ``RTLD_GLOBAL`` flag. This is useful for modules that need to share symbols with other dynamic + // libraries. For example, a module X may load another shared library Y that depends on some + // symbols defined in module X. In this case, module X must be loaded with the ``RTLD_GLOBAL`` + // flag so that the symbols defined in module X are visible to library Y. // // .. warning:: - // Use this option with caution as it may lead to symbol conflicts and undefined behavior - // if multiple modules define the same symbols and are loaded globally. + // Use this option with caution as it may lead to symbol conflicts and undefined behavior if + // multiple modules define the same symbols and are loaded globally. + // + // Defaults to ``false``. bool load_globally = 4; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/common/set_filter_state/v3/value.proto b/xds-api/src/main/proto/envoy/extensions/filters/common/set_filter_state/v3/value.proto index 6abd228daed..054529c546f 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/common/set_filter_state/v3/value.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/common/set_filter_state/v3/value.proto @@ -32,14 +32,55 @@ message FilterStateValue { oneof key { option (validate.required) = true; - // Filter state object key. The key is used to lookup the object factory, unless :ref:`factory_key - // ` is set. See - // :ref:`the well-known filter state keys ` for a list of valid object keys. + // The name under which the filter state object will be stored and can be retrieved. + // + // When using :ref:`well-known filter state keys ` (e.g., + // ``envoy.network.upstream_server_name``, ``envoy.tcp_proxy.cluster``), the object key serves + // dual purpose where it identifies both where the data is stored and which factory creates the + // object. In this case, :ref:`factory_key + // ` + // is not needed. + // + // When using a custom key name which is not from the well-known list, you must also specify + // :ref:`factory_key + // ` + // to indicate which factory should create the object from your value. + // + // Example using a well-known key where ``factory_key`` is not needed: + // + // .. code-block:: yaml + // + // object_key: envoy.tcp_proxy.cluster + // format_string: + // text_format_source: + // inline_string: "my-cluster" + // + // Example using a custom key which requires a ``factory_key``: + // + // .. code-block:: yaml + // + // object_key: my.custom.key + // factory_key: envoy.string + // format_string: + // text_format_source: + // inline_string: "my-value" + // string object_key = 1 [(validate.rules).string = {min_len: 1}]; } - // Optional filter object factory lookup key. See :ref:`the well-known filter state keys ` - // for a list of valid factory keys. + // Specifies which registered factory should be used to create the filter state object from the + // provided value. This field is required when :ref:`object_key + // ` + // is a custom name not found in the :ref:`well-known filter state keys `. + // + // Each well-known key has a factory registered with the same name (e.g., the key + // ``envoy.tcp_proxy.cluster`` has a factory also named ``envoy.tcp_proxy.cluster``). For custom keys, + // use one of the following generic factories: + // + // * ``envoy.string``: Creates a generic string object. Use this for arbitrary string values that + // will be accessed via ``StringAccessor``. + // + // If not specified, defaults to the value of ``object_key``. string factory_key = 6; oneof value { diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/aws_lambda/v3/aws_lambda.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/aws_lambda/v3/aws_lambda.proto index 6c683cc40d2..9200ae943dd 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/aws_lambda/v3/aws_lambda.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/aws_lambda/v3/aws_lambda.proto @@ -48,13 +48,15 @@ message Config { // this value. If not set or empty, the original host header value // will be used and no rewrite will happen. // - // Note: this rewrite affects both signing and host header forwarding. However, this - // option shouldn't be used with - // :ref:`HCM host rewrite ` given that the - // value set here would be used for signing whereas the value set in the HCM would be used - // for host header forwarding which is not the desired outcome. - // Changing the value of the host header can result in a different route to be selected - // if an HTTP filter after AWS lambda re-evaluates the route (clears route cache). + // .. note:: + // This rewrite affects both signing and host header forwarding. However, this + // option shouldn't be used with + // :ref:`HCM host rewrite ` given that the + // value set here would be used for signing whereas the value set in the HCM would be used + // for host header forwarding which is not the desired outcome. + // + // Changing the value of the host header can result in a different route to be selected + // if an HTTP filter after AWS lambda re-evaluates the route (clears route cache). string host_rewrite = 4; // Specifies the credentials profile to be used from the AWS credentials file. diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto index 610c8c7c654..64678be2051 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto @@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.filters.http.aws_request_signing] // Top level configuration for the AWS request signing filter. -// [#next-free-field: 9] +// [#next-free-field: 10] message AwsRequestSigning { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.aws_request_signing.v2alpha.AwsRequestSigning"; @@ -58,14 +58,14 @@ message AwsRequestSigning { // When signing_algorithm is set to ``AWS_SIGV4`` the region is a standard AWS `region `_ string for the service // hosting the HTTP endpoint. // - // Example: us-west-2 + // Example: ``us-west-2`` // // When signing_algorithm is set to ``AWS_SIGV4A`` the region is used as a region set. // // A region set is a comma separated list of AWS regions, such as ``us-east-1,us-east-2`` or wildcard ``*`` // or even region strings containing wildcards such as ``us-east-*`` // - // Example: '*' + // Example: ``'*'`` // // By configuring a region set, a SigV4A signed request can be sent to multiple regions, rather than being // valid for only a single region destination. @@ -75,11 +75,12 @@ message AwsRequestSigning { // this value. If not set or empty, the original host header value // will be used and no rewrite will happen. // - // Note: this rewrite affects both signing and host header forwarding. However, this - // option shouldn't be used with - // :ref:`HCM host rewrite ` given that the - // value set here would be used for signing whereas the value set in the HCM would be used - // for host header forwarding which is not the desired outcome. + // .. note:: + // This rewrite affects both signing and host header forwarding. However, this + // option shouldn't be used with + // :ref:`HCM host rewrite ` given that the + // value set here would be used for signing whereas the value set in the HCM would be used + // for host header forwarding which is not the desired outcome. string host_rewrite = 3; // Instead of buffering the request to calculate the payload hash, use the literal string ``UNSIGNED-PAYLOAD`` @@ -91,11 +92,15 @@ message AwsRequestSigning { // any patterns defined in the StringMatcher proto (e.g. exact string, prefix, regex, etc). // // Example: - // match_excluded_headers: - // - prefix: x-envoy - // - exact: foo - // - exact: bar - // When applied, all headers that start with "x-envoy" and headers "foo" and "bar" will not be signed. + // + // .. code-block:: yaml + // + // match_excluded_headers: + // - prefix: x-envoy + // - exact: foo + // - exact: bar + // + // When applied, all headers that start with ``x-envoy`` and headers ``foo`` and ``bar`` will not be signed. repeated type.matcher.v3.StringMatcher match_excluded_headers = 5; // Optional Signing algorithm specifier, either ``AWS_SIGV4`` or ``AWS_SIGV4A``, defaulting to ``AWS_SIGV4``. @@ -112,6 +117,23 @@ message AwsRequestSigning { // The credential provider for signing the request. This is optional and if not set, // it will be retrieved using the procedure described in :ref:`config_http_filters_aws_request_signing`. common.aws.v3.AwsCredentialProvider credential_provider = 8; + + // A list of request header string matchers that will be included during signing. The included header can be matched by + // any patterns defined in the StringMatcher proto (e.g. exact string, prefix, regex, etc). + // match_included_headers takes precedence over match_excluded_headers - if match_included_headers is set, only those headers will be signed and match_excluded_headers will be ignored. + // Required headers for signing such as ``host`` will always be signed regardless of this setting. The required headers are determined via ``CanonicalHeaders`` section in the AWS documentation `here `_. + // + // Example: + // + // .. code-block:: yaml + // + // match_included_headers: + // - prefix: x-envoy + // - exact: foo + // - exact: bar + // + // When applied, all headers that start with ``x-envoy`` and headers ``foo`` and ``bar`` will be signed and all other headers will be excluded from signing except required headers. + repeated type.matcher.v3.StringMatcher match_included_headers = 9; } message AwsRequestSigningPerRoute { diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto index c5f1b4fb1d2..1ab6c5eb1ef 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto @@ -31,6 +31,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // :ref:`ExecuteFilterAction `) // which filter configuration to create and delegate to. message Composite { + // Named filter chain definitions that can be referenced from + // :ref:`ExecuteFilterAction.filter_chain_name + // `. + // The filter chains are compiled at configuration time and can be referenced by name. + // This is useful when the same filter chain needs to be applied across many routes, + // as it avoids duplicating the filter chain configuration. + map named_filter_chains = 1; } // A list of filter configurations to be called in order. Note that this can be used as the type @@ -58,25 +65,36 @@ message DynamicConfig { // Composite match action (see :ref:`matching docs ` for more info on match actions). // This specifies the filter configuration of the filter that the composite filter should delegate filter interactions to. +// [#next-free-field: 6] message ExecuteFilterAction { // Filter specific configuration which depends on the filter being // instantiated. See the supported filters for further documentation. - // Only one of ``typed_config`` or ``dynamic_config`` can be set. - // Ignored if ``filter_chain`` is set. + // Only one of ``typed_config``, ``dynamic_config``, ``filter_chain``, or ``filter_chain_name`` + // can be set. // [#extension-category: envoy.filters.http] config.core.v3.TypedExtensionConfig typed_config = 1 [(udpa.annotations.field_migrate).oneof_promotion = "config_type"]; // Dynamic configuration of filter obtained via extension configuration discovery service. - // Only one of ``typed_config`` or ``dynamic_config`` can be set. - // Ignored if ``filter_chain`` is set. + // Only one of ``typed_config``, ``dynamic_config``, ``filter_chain``, or ``filter_chain_name`` + // can be set. DynamicConfig dynamic_config = 2 [(udpa.annotations.field_migrate).oneof_promotion = "config_type"]; // An inlined list of filter configurations. The specified filters will be executed in order. - // [#not-implemented-hide:] + // Only one of ``typed_config``, ``dynamic_config``, ``filter_chain``, or ``filter_chain_name`` + // can be set. FilterChainConfiguration filter_chain = 4; + // The name of a filter chain defined in + // :ref:`Composite.named_filter_chains + // `. + // At runtime, if the named filter chain is not found in the Composite filter's configuration, + // no filter will be applied for this match (the action is silently skipped). + // Only one of ``typed_config``, ``dynamic_config``, ``filter_chain``, or ``filter_chain_name`` + // can be set. + string filter_chain_name = 5; + // Probability of the action execution. If not specified, this is 100%. // This allows sampling behavior for the configured actions. // For example, if diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto index 2856a7f9b73..e4e88161a02 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto @@ -14,40 +14,47 @@ option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/dynamic_modules/v3;dynamic_modulesv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: HTTP filter for dynamic modules] +// [#protodoc-title: Dynamic Modules HTTP Filter] // [#extension: envoy.filters.http.dynamic_modules] -// Configuration of the HTTP filter for dynamic modules. This filter allows loading shared object files -// that can be loaded via dlopen by the HTTP filter. +// Configuration for the Dynamic Modules HTTP filter. This filter allows loading shared object files +// that can be loaded via ``dlopen`` to extend the HTTP filter chain. // -// A module can be loaded by multiple HTTP filters, hence the program can be structured in a way that -// the module is loaded only once and shared across multiple filters providing multiple functionalities. +// A module can be loaded by multiple HTTP filters; the module is loaded only once and shared across +// multiple filters. // -// A dynamic module HTTP filter can opt into being a terminal filter with no upstream by setting ``terminal_filter`` to -// true in the configuration. A terminal dynamic module can use ``send_`` ABI methods to send response headers, -// body and trailers to the downstream. +// A dynamic module HTTP filter can opt into being a terminal filter with no upstream by setting +// :ref:`terminal_filter +// ` +// to ``true``. A terminal dynamic module can use ``send_`` ABI methods to send response headers, +// body, and trailers to the downstream. message DynamicModuleFilter { // Specifies the shared-object level configuration. envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; - // The name for this filter configuration. This can be used to distinguish between different filter implementations - // inside a dynamic module. For example, a module can have completely different filter implementations. - // When Envoy receives this configuration, it passes the filter_name to the dynamic module's HTTP filter config init function - // together with the filter_config. - // That way a module can decide which in-module filter implementation to use based on the name at load time. + // The name for this filter configuration. + // + // This can be used to distinguish between different filter implementations inside a dynamic + // module. For example, a module can have completely different filter implementations. When Envoy + // receives this configuration, it passes the ``filter_name`` to the dynamic module's HTTP filter + // config init function together with the ``filter_config``. That way a module can decide which + // in-module filter implementation to use based on the name at load time. string filter_name = 2; - // The configuration for the filter chosen by filter_name. This is passed to the module's HTTP filter initialization function. - // Together with the filter_name, the module can decide which in-module filter implementation to use and + // The configuration for the filter chosen by ``filter_name``. + // + // This is passed to the module's HTTP filter initialization function. Together with the + // ``filter_name``, the module can decide which in-module filter implementation to use and // fine-tune the behavior of the filter. // - // For example, if a module has two filter implementations, one for logging and one for header manipulation, - // filter_name is used to choose either logging or header manipulation. The filter_config can be used to - // configure the logging level or the header manipulation behavior. + // For example, if a module has two filter implementations, one for logging and one for header + // manipulation, ``filter_name`` is used to choose either logging or header manipulation. The + // ``filter_config`` can be used to configure the logging level or the header manipulation + // behavior. // - // ``google.protobuf.Struct`` is serialized as JSON before - // passing it to the plugin. ``google.protobuf.BytesValue`` and - // ``google.protobuf.StringValue`` are passed directly without the wrapper. + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without + // the wrapper. // // .. code-block:: yaml // @@ -63,35 +70,42 @@ message DynamicModuleFilter { // google.protobuf.Any filter_config = 3; - // Set true if the dynamic module is a terminal filter to use without an upstream. + // If ``true``, the dynamic module is a terminal filter to use without an upstream. + // // The dynamic module is responsible for creating and sending the response to downstream. + // + // Defaults to ``false``. bool terminal_filter = 4; } -// Configuration of the HTTP per-route filter for dynamic modules. This filter allows loading shared object files -// that can be loaded via dlopen by the HTTP filter. +// Configuration of the HTTP per-route filter for dynamic modules. message DynamicModuleFilterPerRoute { // Specifies the shared-object level configuration. envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; - // The name for this filter configuration. This can be used to distinguish between different filter implementations - // inside a dynamic module. For example, a module can have completely different filter implementations. - // When Envoy receives this configuration, it passes the filter_name to the dynamic module's HTTP per-route filter config init function - // together with the filter_config. - // That way a module can decide which in-module filter implementation to use based on the name at load time. + // The name for this filter configuration. + // + // This can be used to distinguish between different filter implementations inside a dynamic + // module. For example, a module can have completely different filter implementations. When Envoy + // receives this configuration, it passes the ``per_route_config_name`` to the dynamic module's + // HTTP per-route filter config init function together with the ``filter_config``. That way a + // module can decide which in-module filter implementation to use based on the name at load time. string per_route_config_name = 2; - // The configuration for the filter chosen by filter_name. This is passed to the module's HTTP per-route filter initialization function. - // Together with the filter_name, the module can decide which in-module filter implementation to use and - // fine-tune the behavior of the filter on a specific route. + // The configuration for the filter chosen by ``per_route_config_name``. + // + // This is passed to the module's HTTP per-route filter initialization function. Together with + // the ``per_route_config_name``, the module can decide which in-module filter implementation to + // use and fine-tune the behavior of the filter on a specific route. // - // For example, if a module has two filter implementations, one for logging and one for header manipulation, - // filter_name is used to choose either logging or header manipulation. The filter_config can be used to - // configure the logging level or the header manipulation behavior. + // For example, if a module has two filter implementations, one for logging and one for header + // manipulation, ``per_route_config_name`` is used to choose either logging or header + // manipulation. The ``filter_config`` can be used to configure the logging level or the header + // manipulation behavior. // - // ``google.protobuf.Struct`` is serialized as JSON before - // passing it to the plugin. ``google.protobuf.BytesValue`` and - // ``google.protobuf.StringValue`` are passed directly without the wrapper. + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without + // the wrapper. // // .. code-block:: yaml // diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 2d2c2a7246b..7f70b70013b 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto @@ -30,7 +30,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // External Authorization :ref:`configuration overview `. // [#extension: envoy.filters.http.ext_authz] -// [#next-free-field: 31] +// [#next-free-field: 32] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v3.ExtAuthz"; @@ -55,15 +55,17 @@ message ExtAuthz { // Changes the filter's behavior on errors: // - // #. When set to ``true``, the filter will ``accept`` the client request even if communication with - // the authorization service has failed, or if the authorization service has returned an HTTP 5xx - // error. + // * When set to ``true``, the filter will ``accept`` the client request even if communication with + // the authorization service has failed, or if the authorization service has returned an HTTP 5xx + // error. // - // #. When set to ``false``, the filter will ``reject`` client requests and return ``Forbidden`` - // if communication with the authorization service has failed, or if the authorization service - // has returned an HTTP 5xx error. + // * When set to ``false``, the filter will ``reject`` client requests and return ``Forbidden`` + // if communication with the authorization service has failed, or if the authorization service + // has returned an HTTP 5xx error. // // Errors can always be tracked in the :ref:`stats `. + // + // Defaults to ``false``. bool failure_mode_allow = 2; // When ``failure_mode_allow`` and ``failure_mode_allow_header_add`` are both set to ``true``, @@ -78,25 +80,26 @@ message ExtAuthz { BufferSettings with_request_body = 5; // Clears the route cache in order to allow the external authorization service to correctly affect - // routing decisions. The filter clears all cached routes when: - // - // #. The field is set to ``true``. + // routing decisions. The filter clears all cached routes when all of the following holds: // - // #. The status returned from the authorization service is an HTTP 200 or gRPC 0. - // - // #. At least one ``authorization response header`` is added to the client request, or is used to - // alter another client request header. + // * This field is set to ``true``. + // * The status returned from the authorization service is an HTTP 200 or gRPC 0. + // * At least one ``authorization response header`` is added to the client request, or is used to + // alter another client request header. // + // Defaults to ``false``. bool clear_route_cache = 6; // Sets the HTTP status that is returned to the client when the authorization server returns an error - // or cannot be reached. The default status is HTTP 403 Forbidden. + // or cannot be reached. + // + // The default status is ``HTTP 403 Forbidden``. type.v3.HttpStatus status_on_error = 7; - // When this is set to ``true``, the filter will check the :ref:`ext_authz response + // When set to ``true``, the filter will check the :ref:`ext_authz response // ` for invalid header and - // query parameter mutations. If the side stream response is invalid, it will send a local reply - // to the downstream request with status HTTP 500 Internal Server Error. + // query parameter mutations. If the response is invalid, the filter will send a local reply + // to the downstream request with status ``HTTP 500 Internal Server Error``. // // .. note:: // Both ``headers_to_remove`` and ``query_parameters_to_remove`` are validated, but invalid elements in @@ -106,6 +109,8 @@ message ExtAuthz { // unexpected behavior. // // If you are using ext_authz with an untrusted ext_authz server, you should set this to ``true``. + // + // Defaults to ``false``. bool validate_mutations = 24; // Specifies a list of metadata namespaces whose values, if present, will be passed to the @@ -160,6 +165,24 @@ message ExtAuthz { // Specifies if the filter is enabled with metadata matcher. // If this field is not specified, the filter will be enabled for all requests. + // + // .. note:: + // + // This field is only evaluated if the filter is instantiated. If the filter is marked with + // ``disabled: true`` in the :ref:`HttpFilter + // ` + // configuration or in per-route configuration via :ref:`ExtAuthzPerRoute + // `, + // the filter will not be instantiated and this field will have no effect. + // + // .. tip:: + // + // For dynamic filter activation based on metadata (such as metadata set by a preceding + // filter), consider using :ref:`ExtensionWithMatcher + // ` instead. This + // provides a more flexible matching framework that can evaluate conditions before filter + // instantiation. See the :ref:`ext_authz filter documentation + // ` for examples. type.matcher.v3.MetadataMatcher filter_enabled_metadata = 14; // Specifies whether to deny the requests when the filter is disabled. @@ -204,7 +227,7 @@ message ExtAuthz { string bootstrap_metadata_labels_key = 15; // Check request to authorization server will include the client request headers that have a correspondent match - // in the :ref:`list `. If this option isn't specified, then + // in the list. If this option isn't specified, then // all client request headers are included in the check request to a gRPC authorization server, whereas no client request headers // (besides the ones allowed by default - see note below) are included in the check request to an HTTP authorization server. // This inconsistency between gRPC and HTTP servers is to maintain backwards compatibility with legacy behavior. @@ -266,19 +289,19 @@ message ExtAuthz { bool encode_raw_headers = 23; // Rules for what modifications an ext_authz server may make to the request headers before - // continuing decoding / forwarding upstream. + // continuing decoding or forwarding upstream. // - // If set to anything, enables header mutation checking against configured rules. Note that + // If set, enables header mutation checking against the configured rules. Note that // :ref:`HeaderMutationRules ` - // has defaults that change ext_authz behavior. Also note that if this field is set to anything, - // ext_authz can no longer append to :-prefixed headers. + // has defaults that change ext_authz behavior. Also note that if this field is set, + // ext_authz can no longer append to ``:``-prefixed headers. // - // If empty, header mutation rule checking is completely disabled. + // If unset, header mutation rule checking is completely disabled. // - // Regardless of what is configured here, ext_authz cannot remove :-prefixed headers. + // Regardless of what is configured here, ext_authz cannot remove ``:``-prefixed headers. // // This field and ``validate_mutations`` have different use cases. ``validate_mutations`` enables - // correctness checks for all header / query parameter mutations (e.g. for invalid characters). + // correctness checks for all header and query parameter mutations (for example, invalid characters). // This field allows the filter to reject mutations to specific headers. config.common.mutation_rules.v3.HeaderMutationRules decoder_header_mutation_rules = 26; @@ -302,8 +325,10 @@ message ExtAuthz { // key will be the same as the filter name. // // If using Envoy gRPC, emits latency, bytes sent / received, upstream info, and upstream cluster - // info. If not using Envoy gRPC, emits only latency. Note that stats are ONLY added to filter - // state if a check request is actually made to an ext_authz service. + // info. If not using Envoy gRPC, emits only latency. + // + // .. note:: + // Stats are ONLY added to filter state if a check request is actually made to an ext_authz service. // // If this is ``false`` the filter will not emit stats, but filter_metadata will still be respected if // it has a value. @@ -322,6 +347,18 @@ message ExtAuthz { // If this field is not set or is set to 0, no truncation will occur, and the entire // denied response body will be forwarded. uint32 max_denied_response_body_bytes = 30; + + // When set to ``true``, the filter will enforce the response header map's count and size limits + // by sending a local reply when those limits are violated. + // + // When set to ``false``, the filter will ignore the response header map's limits and add / set + // all response headers as specified by the external authorization service. + // + // Recommendation: enable if the external authorization service is not trusted. Otherwise, leave + // it ``false``. + // + // Defaults to ``false``. + bool enforce_response_header_limits = 31; } // Configuration for buffering the request data. @@ -331,13 +368,18 @@ message BufferSettings { // Sets the maximum size of a message body that the filter will hold in memory. Envoy will return // ``HTTP 413`` and will *not* initiate the authorization process when the buffer reaches the size - // set in this field. Note that this setting will have precedence over :ref:`failure_mode_allow - // `. + // set in this field. + // + // .. note:: + // This setting will have precedence over :ref:`failure_mode_allow + // `. uint32 max_request_bytes = 1 [(validate.rules).uint32 = {gt: 0}]; // When this field is ``true``, Envoy will buffer the message until ``max_request_bytes`` is reached. // The authorization request will be dispatched and no 413 HTTP error will be returned by the // filter. + // + // Defaults to ``false``. bool allow_partial_message = 2; // If ``true``, the body sent to the external authorization service is set as raw bytes and populates @@ -350,14 +392,18 @@ message BufferSettings { // `. In configurations that use // an :ref:`http_service `, this // has no effect. + // + // Defaults to ``false``. bool pack_as_bytes = 3; } // HttpService is used for raw HTTP communication between the filter and the authorization service. // When configured, the filter will parse the client request and use these attributes to call the // authorization server. Depending on the response, the filter may reject or accept the client -// request. Note that in any of these events, metadata can be added, removed or overridden by the -// filter: +// request. +// +// .. note:: +// In any of these events, metadata can be added, removed or overridden by the filter: // // On authorization request, a list of allowed request headers may be supplied. See // :ref:`allowed_headers @@ -412,7 +458,7 @@ message AuthorizationRequest { "envoy.config.filter.http.ext_authz.v2.AuthorizationRequest"; // Authorization request includes the client request headers that have a corresponding match - // in the :ref:`list `. + // in the list. // This field has been deprecated in favor of :ref:`allowed_headers // `. // @@ -432,8 +478,10 @@ message AuthorizationRequest { type.matcher.v3.ListStringMatcher allowed_headers = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // Sets a list of headers that will be included in the request to the authorization service. Note that - // client request headers with the same key will be overridden. + // Sets a list of headers that will be included in the request to the authorization service. + // + // .. note:: + // Client request headers with the same key will be overridden. repeated config.core.v3.HeaderValue headers_to_add = 2; } @@ -442,30 +490,37 @@ message AuthorizationResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.AuthorizationResponse"; - // When this :ref:`list ` is set, authorization + // When this list is set, authorization // response headers that have a correspondent match will be added to the original client request. - // Note that coexistent headers will be overridden. + // + // .. note:: + // Existing headers will be overridden. type.matcher.v3.ListStringMatcher allowed_upstream_headers = 1; - // When this :ref:`list ` is set, authorization + // When this list is set, authorization // response headers that have a correspondent match will be added to the original client request. - // Note that coexistent headers will be appended. + // + // .. note:: + // Existing headers will be appended. type.matcher.v3.ListStringMatcher allowed_upstream_headers_to_append = 3; - // When this :ref:`list ` is set, authorization - // response headers that have a correspondent match will be added to the client's response. Note - // that when this list is *not* set, all the authorization response headers, except ``Authority - // (Host)`` will be in the response to the client. When a header is included in this list, ``Path``, - // ``Status``, ``Content-Length``, ``WWWAuthenticate`` and ``Location`` are automatically added. + // When this list is set, authorization + // response headers that have a correspondent match will be added to the client's response. + // When a header is included in this list, ``Path``, ``Status``, ``Content-Length``, ``WWW-Authenticate`` and + // ``Location`` are automatically added. + // + // .. note:: + // When this list is *not* set, all the authorization response headers, except + // ``Authority (Host)``, will be in the response to the client. type.matcher.v3.ListStringMatcher allowed_client_headers = 2; - // When this :ref:`list ` is set, authorization + // When this list is set, authorization // response headers that have a correspondent match will be added to the client's response when // the authorization response itself is successful, i.e. not failed or denied. When this list is // *not* set, no additional headers will be added to the client's response on success. type.matcher.v3.ListStringMatcher allowed_client_headers_on_success = 4; - // When this :ref:`list ` is set, authorization + // When this list is set, authorization // response headers that have a correspondent match will be emitted as dynamic metadata to be consumed // by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter // that requires it: diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto index 0108434aec2..b07811d5235 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto @@ -60,8 +60,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // * Request body: If the body is present, the behavior depends on the // body send mode. In ``BUFFERED`` or ``BUFFERED_PARTIAL`` mode, the body is sent to the external // processor in a single message. In ``STREAMED`` or ``FULL_DUPLEX_STREAMED`` mode, the body will -// be split across multiple messages sent to the external processor. In ``NONE`` mode, the body -// will not be sent to the external processor. +// be split across multiple messages sent to the external processor. In ``GRPC`` mode, as each +// gRPC message arrives, it will be sent to the external processor (there will be exactly one +// gRPC message in each message sent to the external processor). In ``NONE`` mode, the body will +// not be sent to the external processor. // * Request trailers: Delivered if they are present and if the trailer mode is set // to ``SEND``. // * Response headers: Contains the headers from the HTTP response. Keep in mind @@ -209,9 +211,9 @@ message ExternalProcessor { // an error (subject to the processing mode) if the timer expires before a // matching response is received. There is no timeout when the filter is // running in observability mode or when the body send mode is - // ``FULL_DUPLEX_STREAMED``. Zero is a valid config which means the timer - // will be triggered immediately. If not configured, default is 200 - // milliseconds. + // ``FULL_DUPLEX_STREAMED`` or ``GRPC``. Zero is a valid config which means + // the timer will be triggered immediately. If not configured, default is + // 200 milliseconds. google.protobuf.Duration message_timeout = 7 [(validate.rules).duration = { lte {seconds: 3600} gte {} @@ -273,8 +275,8 @@ message ExternalProcessor { // without pausing on filter chain iteration. It is "Send and Go" mode that can be used // by external processor to observe the request's data and status. In this mode: // - // 1. Only ``STREAMED`` and ``NONE`` body processing modes are supported; for any other body - // processing mode, the body will not be sent. + // 1. Only ``STREAMED``, ``GRPC``, and ``NONE`` body processing modes are supported; for any + // other body processing mode, the body will not be sent. // // 2. External processor should not send back processing response, as any responses will be ignored. // This also means that @@ -391,14 +393,21 @@ message MetadataOptions { repeated string typed = 2; } - // Describes which typed or untyped dynamic metadata namespaces to forward to + // Describes which typed or untyped filter dynamic metadata namespaces to forward to // the external processing server. MetadataNamespaces forwarding_namespaces = 1; - // Describes which typed or untyped dynamic metadata namespaces to accept from + // Describes which typed or untyped filter dynamic metadata namespaces to accept from // the external processing server. Set to empty or leave unset to disallow writing // any received dynamic metadata. Receiving of typed metadata is not supported. MetadataNamespaces receiving_namespaces = 2; + + // Describes which cluster metadata namespaces to forward to + // the external processing server. + // .. note:: + // This is the least specific metadata. Should there be any namespace collision, + // cluster level metadata can be overridden by filter metadata. + MetadataNamespaces cluster_metadata_forwarding_namespaces = 3; } // The HeaderForwardingRules structure specifies what headers are diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto index 5ad32af519f..e2ec8946283 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto @@ -108,6 +108,25 @@ message ProcessingMode { // * The client will stream the body chunks in the responses from the server to the upstream/downstream as they arrive. FULL_DUPLEX_STREAMED = 4; + + // [#not-implemented-hide:] + // A mode for gRPC traffic. This is similar to ``FULL_DUPLEX_STREAMED``, + // except that instead of sending raw chunks of the HTTP/2 DATA frames, + // the ext_proc client will de-frame the individual gRPC messages inside + // the HTTP/2 DATA frames, and as each message is de-framed, it will be + // sent to the ext_proc server as a :ref:`request_body + // ` + // or :ref:`response_body + // `. + // The ext_proc server will stream back individual gRPC messages in the + // :ref:`StreamedBodyResponse ` + // field, but the number of messages sent by the ext_proc server + // does not need to equal the number of messages sent by the data + // plane. This allows the ext_proc server to change the number of + // messages sent on the stream. + // In this mode, the client will send body and trailers to the server as + // they arrive. + GRPC = 5; } // How to handle the request header. Default is "SEND". diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/geoip/v3/geoip.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/geoip/v3/geoip.proto index 4ef26a8245e..770354478f9 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/geoip/v3/geoip.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/geoip/v3/geoip.proto @@ -24,18 +24,44 @@ message Geoip { message XffConfig { // The number of additional ingress proxy hops from the right side of the // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header to trust when - // determining the origin client's IP address. The default is zero if this option - // is not specified. See the documentation for + // determining the origin client's IP address. See the documentation for // :ref:`config_http_conn_man_headers_x-forwarded-for` for more information. + // + // Defaults to ``0``. uint32 xff_num_trusted_hops = 1; } - // If set, the :ref:`xff_num_trusted_hops ` field will be used to determine - // trusted client address from ``x-forwarded-for`` header. - // Otherwise, the immediate downstream connection source address will be used. - // [#next-free-field: 2] + message CustomHeaderConfig { + // The name of the request header to extract the client IP address from. + // The header value must contain a valid IP address (IPv4 or IPv6). + // + // If the header is missing or contains an invalid IP address, the filter will fall back + // to using the immediate downstream connection source address. + string header_name = 1 [(validate.rules).string = {min_len: 1}]; + } + + // Configuration for extracting the client IP address from the + // ``x-forwarded-for`` header. If set, the + // :ref:`xff_num_trusted_hops ` + // field will be used to determine the trusted client address from the ``x-forwarded-for`` header. + // If not set, the immediate downstream connection source address will be used. + // + // Only one of ``xff_config`` or + // :ref:`custom_header_config ` + // can be set. XffConfig xff_config = 1; + // Configuration for extracting the client IP address from a custom request header. + // + // If set, the + // :ref:`header_name ` + // field will be used to extract the client IP address from the specified request header. + // + // Only one of ``custom_header_config`` or + // :ref:`xff_config ` + // can be set. + CustomHeaderConfig custom_header_config = 4; + // Geoip driver specific configuration which depends on the driver being instantiated. // See the geoip drivers for examples: // diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/jwt_authn/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/jwt_authn/v3/config.proto index 02ab21dfe6e..9a955bdd80e 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/jwt_authn/v3/config.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/jwt_authn/v3/config.proto @@ -77,17 +77,20 @@ message JwtProvider { // It is optional. If specified, it has to match the ``iss`` field in JWT, // otherwise the JWT ``iss`` field is not checked. // - // Note: ``JwtRequirement`` :ref:`allow_missing ` - // and :ref:`allow_missing_or_failed ` - // are implemented differently than other ``JwtRequirements``. Hence the usage of this field - // is different as follows if ``allow_missing`` or ``allow_missing_or_failed`` is used: + // .. note:: + // ``JwtRequirement`` :ref:`allow_missing ` + // and :ref:`allow_missing_or_failed ` + // are implemented differently than other ``JwtRequirements``. Hence the usage of this field + // is different as follows if ``allow_missing`` or ``allow_missing_or_failed`` is used: // - // * If a JWT has ``iss`` field, it needs to be specified by this field in one of ``JwtProviders``. - // * If a JWT doesn't have ``iss`` field, one of ``JwtProviders`` should fill this field empty. - // * Multiple ``JwtProviders`` should not have same value in this field. + // * If a JWT has ``iss`` field, it needs to be specified by this field in one of ``JwtProviders``. + // * If a JWT doesn't have ``iss`` field, one of ``JwtProviders`` should fill this field empty. + // * Multiple ``JwtProviders`` should not have same value in this field. // - // Example: https://securetoken.google.com - // Example: 1234567-compute@developer.gserviceaccount.com + // Examples: + // + // * https://securetoken.google.com + // * Example: 1234567-compute@developer.gserviceaccount.com // string issuer = 1; @@ -558,7 +561,7 @@ message ProviderWithAudiences { // - allow_missing: {} // - provider_name: provider-B // -// [#next-free-field: 7] +// [#next-free-field: 8] message JwtRequirement { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.jwt_authn.v2alpha.JwtRequirement"; @@ -589,9 +592,41 @@ message JwtRequirement { // to only verify JWTs and pass the verified payload to another filter. The // different is this mode will reject requests with invalid tokens. google.protobuf.Empty allow_missing = 6; + + // Extract JWT claims without performing signature validation. + // This mode will decode the JWT, extract claims, and forward them as + // configured (via claim_to_headers, forward_payload_header, etc.) but + // will NOT verify the JWT signature against JWKS. + // + // .. warning:: + // + // This mode does not verify JWT authenticity. Use only in scenarios where: + // + // - JWTs come from a trusted source (e.g., internal service mesh) + // - Signature verification is performed elsewhere in the request path + // - You are in a testing period and the token issuer doesn't support JWKS yet + // + // This mode will: + // + // * Decode the JWT header and payload + // * Extract claims and forward them as headers + // * Always return success (Status::Ok) regardless of JWT validity + // * Log when extraction occurs + // + // This mode will NOT: + // + // * Verify the JWT signature + // * Validate the (issuer) claim + // * Validate the (audience) claim + // * Check not-before time (nbf claim) + ExtractOnlyWithoutValidation extract_only_without_validation = 7; } } +message ExtractOnlyWithoutValidation { + // Reserved for future extensions (e.g., claim filtering, logging options) +} + // This message specifies a list of RequiredProvider. // Their results are OR-ed; if any one of them passes, the result is passed message JwtRequirementOrList { diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto index 7c873fc2f0f..5d2825e729f 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto @@ -2,23 +2,105 @@ syntax = "proto3"; package envoy.extensions.filters.http.mcp.v3; +import "google/protobuf/wrappers.proto"; + +import "xds/annotations/v3/status.proto"; + import "udpa/annotations/status.proto"; +import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.filters.http.mcp.v3"; option java_outer_classname = "McpProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/mcp/v3;mcpv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: MCP] // MCP filter :ref:`configuration overview `. // [#extension: envoy.filters.http.mcp] +// This filter will inspect and get attributes from MCP traffic. message Mcp { - // TODO: Add configuration fields + // Traffic handling mode for non-MCP traffic. + enum TrafficMode { + // Proxies the HTTP request and response without MCP spec check. + // This is the default mode. + PASS_THROUGH = 0; + + // Reject requests that are not following MCP spec. + // Valid MCP requests are: + // - POST requests with JSON-RPC 2.0 messages + // - GET requests for SSE streams (with Accept: text/event-stream) + REJECT_NO_MCP = 1; + } + + // Configures how the filter handles non-MCP traffic. + TrafficMode traffic_mode = 1 [(validate.rules).enum = {defined_only: true}]; + + // When set to true, the filter will clear the route cache after setting dynamic metadata. + // This allows the route to be re-selected based on the MCP metadata (e.g., method, params). + // Defaults to false. + bool clear_route_cache = 2; + + // Maximum size of the request body to buffer for JSON-RPC validation. + // If the request body exceeds this size, the request is rejected with ``413 Payload Too Large``. + // This limit applies to both ``REJECT_NO_MCP`` and ``PASS_THROUGH`` modes to prevent unbounded buffering. + // + // It defaults to 8KB (8192 bytes) and the maximum allowed value is 10MB (10485760 bytes). + // + // Setting it to 0 would disable the limit. It is not recommended to do so in production. + google.protobuf.UInt32Value max_request_body_size = 3 [(validate.rules).uint32 = {lte: 10485760}]; + + // Parser configuration, this provide the attribute extraction override. + ParserConfig parser_config = 4; } -// McpOverride for MCP filter +// Parser configuration with method-specific rules. +// This configuration allows overriding the default attribute extraction behavior for specific MCP methods. +message ParserConfig { + // A single attribute extraction rule. + message AttributeExtractionRule { + // JSON path to extract (e.g., "params.name", "params.uri"). + // The path is a dot-separated string representing the location of the field in the JSON payload. + // For example, "params.name" extracts the "name" field from the "params" object. + string path = 1 [(validate.rules).string = {min_len: 1}]; + } + + // Configuration for a specific MCP method. + message MethodConfig { + // Method name (e.g., "tools/call", "resources/read", "initialize"). + // This matches the "method" field in the JSON-RPC request. + string method = 1 [(validate.rules).string = {min_len: 1}]; + + // The group/category name to assign to this method (e.g., "tool", "lifecycle"). + // This will be emitted to dynamic metadata under the key specified by group_metadata_key. + // If empty, the built-in group classification is used. + string group = 2; + + // Attributes to extract for this method. + // If empty, only default attributes (jsonrpc, method) are extracted. + repeated AttributeExtractionRule extraction_rules = 3; + } + + // List of rules for classification and extraction. + // Rules are evaluated in order; the first match wins. + // If no rule matches, extraction defaults are used and group falls back to built-in classification. + // Built-in groups: lifecycle, tool, resource, prompt, notification, logging, sampling, completion, unknown. + repeated MethodConfig methods = 1; + + // The dynamic metadata key where the group name will be stored. + // If empty, group classification is disabled. + string group_metadata_key = 2; +} + +// Per-route override configuration for MCP filter message McpOverride { - // TODO: Add configuration fields + // Optional per-route traffic mode override + Mcp.TrafficMode traffic_mode = 1 [(validate.rules).enum = {defined_only: true}]; + + // Optional per-route max request body size override. + // When set, this overrides the global max_request_body_size for this route. + // It defaults to 8KB (8192 bytes) and the maximum allowed value is 10MB (10485760 bytes). + google.protobuf.UInt32Value max_request_body_size = 2 [(validate.rules).uint32 = {lte: 10485760}]; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/mcp_router/v3/mcp_router.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/mcp_router/v3/mcp_router.proto new file mode 100644 index 00000000000..1d32449931c --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/mcp_router/v3/mcp_router.proto @@ -0,0 +1,128 @@ +syntax = "proto3"; + +package envoy.extensions.filters.http.mcp_router.v3; + +import "envoy/type/metadata/v3/metadata.proto"; + +import "google/protobuf/duration.proto"; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.http.mcp_router.v3"; +option java_outer_classname = "McpRouterProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/mcp_router/v3;mcp_routerv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: MCP Multiplexer/Demultiplexer] +// [#extension: envoy.filters.http.mcp_router] + +// Configuration for the MCP Multiplexer/Demultiplexer. +// +// This extension aggregates capabilities, tools and resources of remote MCP servers and presents Envoy +// as a singe MCP server to the client. This allows a unified policy to be applied to multiple remote +// servers and abstracts multiple MCP servers as a single one. +// +// This filter must be a terminal filter in the filter chain and replaces the HTTP router filter. +// +// Not all route level policies are applicable to this filter. +// Specifically the following policies are ignored: +// * :ref:`route ` +// * :ref:`redirect ` +// * :ref:`direct_response ` +// + +// Extract identity from a request header. +message HeaderSource { + // Header name to extract (e.g., "x-user-identity"). + string name = 1 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME}]; +} + +// Extract identity from dynamic metadata (e.g., populated by JWT or ext_authz filter). +message DynamicMetadataSource { + // The metadata key to retrieve the value from. + type.metadata.v3.MetadataKey key = 1 [(validate.rules).message = {required: true}]; +} + +// Defines how the identity (user/principal) is extracted from the request. +// Exactly one of ``header`` or ``dynamic_metadata`` must be set. +message IdentityExtractor { + // Extract identity from a request header. + HeaderSource header = 1; + + // Extract identity from dynamic metadata. + DynamicMetadataSource dynamic_metadata = 2; +} + +// Specifies how to handle requests where the identity is missing or mismatched. +message ValidationPolicy { + enum Mode { + // Not specified. Defaults to DISABLED behavior. + MODE_UNSPECIFIED = 0; + + // Bind identity on Initialize if present, but do not validate subsequent requests. + // If extraction fails, the session proceeds anonymously. + DISABLED = 1; + + // Reject the request (403) if the identity cannot be extracted + // or if the session identity does not match the request identity. + ENFORCE = 2; + } + + Mode mode = 1 [(validate.rules).enum = {defined_only: true}]; +} + +// Session identity configuration. +message SessionIdentity { + // Defines how the identity (user/principal) is extracted from the request. + IdentityExtractor identity = 1 [(validate.rules).message = {required: true}]; + + // Specifies how to handle requests where the subject is missing or invalid. + // Defaults to DISABLED. + ValidationPolicy validation = 2; +} + +message McpRouter { + // Specification of the MCP server. + message McpBackend { + // Unique name for this backend. Used for: + // - Tool name prefixing (e.g., "time__get_current_time") + // - Session ID composition + // - Logging and error messages. + // Default will be the cluster name if not specified. + string name = 1; + + // Backend target specification. + McpCluster mcp_cluster = 2; + } + + // Cluster-based backend configuration. + message McpCluster { + // Cluster name to route requests to. + string cluster = 1 [(validate.rules).string = {min_len: 1}]; + + // Path to use for MCP requests. Defaults to "/mcp". + string path = 2; + + // Request timeout. + // If not set, uses cluster's timeout configuration. + google.protobuf.Duration timeout = 3; + + // Indicates that during forwarding, the host header will be swapped with + // this value. + string host_rewrite_literal = 4; + } + + // A list of remote MCP servers. MCP router aggregates capabilities, tools and resources from remote MCP servers + // and presents itself as single MCP server to the client. All remote MCP servers are sent the same capabilities + // that the client presented to Envoy. + repeated McpBackend servers = 1; + + // If set, extracts a request "subject" and binds it into the MCP session. + // If not set, sessions are created without identity binding. + SessionIdentity session_identity = 2; +} diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto index 2354f2b924b..285578fd7a6 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto @@ -37,6 +37,29 @@ message CookieConfig { // The value used for the SameSite cookie attribute. SameSite same_site = 1 [(validate.rules).enum = {defined_only: true}]; + + // The path attribute for the cookie. + // + // This controls the scope of the cookie and is useful for path-based routing scenarios + // where different logical boundaries or applications may operate with different OAuth2 clients. + // The CSRF cookie (nonce cookie) can be configured with a different path than session cookies + // to support flows where the callback URL is on a different path. + // + // If not specified, defaults to ``/``. + string path = 2 [(validate.rules).string = {pattern: "^$|^/[^\\x00-\\x1f\\x7f \",;<>\\\\]*$"}]; + + // If true, the ``Partitioned`` attribute will be set on the cookie. + // + // Modern browsers (Firefox, Chrome with third-party cookie deprecation) warn or block + // "foreign" cookies unless they carry the ``Partitioned`` attribute alongside ``SameSite=None; Secure``. + // When Envoy is used in a gateway/IdP flow that sets OAuth/OIDC cookies for a parent domain + // (e.g., ``Domain=.example.com``) while running on a different host, those cookies are + // considered third-party and will be rejected without ``Partitioned``. + // + // See `CHIPS `_ for more information. + // + // Default is false. + bool partitioned = 3; } // [#next-free-field: 8] @@ -121,7 +144,8 @@ message OAuth2Credentials { // The domain to set the cookie on. If not set, the cookie will default to the host of the request, not including the subdomains. // This is useful when token cookies need to be shared across multiple subdomains. - string cookie_domain = 5; + string cookie_domain = 5 + [(validate.rules).string = {pattern: "^$|^[^\\x00-\\x1f\\x7f \",;<>\\\\]+$"}]; } // OAuth config diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto index b41e0a416c5..8143a044744 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto @@ -4,7 +4,6 @@ package envoy.extensions.filters.http.proto_api_scrubber.v3; import "envoy/config/core/v3/base.proto"; -import "xds/annotations/v3/status.proto"; import "xds/type/matcher/v3/matcher.proto"; import "udpa/annotations/status.proto"; @@ -14,10 +13,8 @@ option java_outer_classname = "ConfigProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/proto_api_scrubber/v3;proto_api_scrubberv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Proto API Scrubber] -// [#not-implemented-hide:] Implementation in progress. // [#extension: envoy.filters.http.proto_api_scrubber] // ProtoApiScrubber filter supports filtering of the request and @@ -25,10 +22,7 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // The field restrictions and actions can be defined using unified matcher API. // The filter evaluates the configured restriction for each field // to produce the filtered output using the configured actions. -// This filter currently supports only field level restrictions. -// Restriction support for other proto elements (eg, message -// level restriction, method level restriction, etc.) are planned to be -// implemented in future. The design doc for this filter is available +// The design doc for this filter is available // `here `_ message ProtoApiScrubberConfig { @@ -62,28 +56,54 @@ message Restrictions { // Key - Fully qualified method name e.g., ``endpoints.examples.bookstore.BookStore/GetShelf``. // Value - Method restrictions. map method_restrictions = 1; + + // Specifies the message restrictions. + // Key - Fully qualified message name e.g., ``endpoints.examples.bookstore.Book``. + // Value - Message restrictions. + map message_restrictions = 2; } // Contains the method restrictions which include the field level restrictions // for the request and response fields. message MethodRestrictions { // Restrictions that apply to request fields of the method. - // Key - field mask like path of the field eg, foo.bar.baz + // Key - field mask like path of the field e.g., foo.bar.baz // Value - Restrictions map containing the mapping from restriction name to // the restriction values. map request_field_restrictions = 1; // Restrictions that apply to response fields of the method. - // Key - field mask like path of the field eg, foo.bar.baz + // Key - field mask like path of the field e.g., foo.bar.baz // Value - Restrictions map containing the mapping from restriction name to // the restriction values. map response_field_restrictions = 2; + + // Optional restriction that applies to the entire method. If present, this + // rule takes precedence for the method itself over field-level or + // message-level rules. The 'matcher' within RestrictionConfig will determine + // if the method is denied/scrubbed. If the matcher evaluates to true: + // + // - The request is **denied**, and further processing is stopped. + // - The implementation should generate an immediate error response + // (e.g., an HTTP 403 Forbidden status) and send it to the client. + RestrictionConfig method_restriction = 3; +} + +// Contains message-level restrictions. +message MessageRestrictions { + // The core restriction to apply to this message type. + // The 'matcher' within RestrictionConfig will determine if the message is + // scrubbed/denied/allowed. + RestrictionConfig config = 1; + + // Restrictions that apply to specific fields within this message type. + // Key - field mask (e.g. "social_security_number"). + // Value - The restriction configuration for that field. + map field_restrictions = 2; } // The restriction configuration. message RestrictionConfig { // Matcher tree for matching requests and responses with the configured restrictions. - // NOTE: Currently, only CEL expressions are supported for matching. Support for more - // matchers will be added incrementally overtime. xds.type.matcher.v3.Matcher matcher = 1; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto index a6f3c7eff44..1beb39c5883 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto @@ -2,8 +2,6 @@ syntax = "proto3"; package envoy.extensions.filters.http.proto_api_scrubber.v3; -import "xds/annotations/v3/status.proto"; - import "udpa/annotations/status.proto"; option java_package = "io.envoyproxy.envoy.extensions.filters.http.proto_api_scrubber.v3"; @@ -11,7 +9,6 @@ option java_outer_classname = "MatcherActionsProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/proto_api_scrubber/v3;proto_api_scrubberv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Proto API Scrubber Matcher Actions] diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_message_extraction/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_message_extraction/v3/config.proto index dc51f9d1141..07067717070 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/proto_message_extraction/v3/config.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/proto_message_extraction/v3/config.proto @@ -259,6 +259,11 @@ message MethodExtraction { // It should be only annotated on Message type fields so if the field isn't // empty, an empty Struct will be extracted. EXTRACT_REDACT = 2; + + // Extract a repeated top-level field and record its number of entries in + // the extraction result. Can be applied to at most one field in the + // response, and cannot be applied to any fields in the request. + EXTRACT_REPEATED_CARDINALITY = 3; } // The mapping of field path to its ExtractDirective for request messages diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto index 6efd47ac58b..a37efe157db 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/rbac/v3/rbac.proto @@ -4,7 +4,6 @@ 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"; @@ -64,10 +63,8 @@ message RBAC { // 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 - ]; + xds.type.matcher.v3.Matcher shadow_matcher = 5 + [(udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier"]; // If specified, shadow rules will emit stats with the given prefix. // This is useful for distinguishing metrics when multiple RBAC filters use shadow rules. diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto index d3996a96798..7da658bcb33 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/router/v3/router.proto @@ -23,7 +23,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Router :ref:`configuration overview `. // [#extension: envoy.filters.http.router] -// [#next-free-field: 10] +// [#next-free-field: 11] message Router { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.router.v2.Router"; @@ -134,4 +134,10 @@ message Router { // upstream HTTP 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; + + // If set to true, Envoy will reject ``CONNECT`` requests that send data before + // receiving a ``200`` response from the upstream. This early data behavior + // is common for latency reduction but can cause issues with some upstreams. + // Defaults to false to allow early data and be compatible with common behavior. + google.protobuf.BoolValue reject_connect_request_early_data = 10; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/http/transform/v3/transform.proto b/xds-api/src/main/proto/envoy/extensions/filters/http/transform/v3/transform.proto new file mode 100644 index 00000000000..f971a31df5e --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/http/transform/v3/transform.proto @@ -0,0 +1,99 @@ +syntax = "proto3"; + +package envoy.extensions.filters.http.transform.v3; + +import "envoy/config/common/mutation_rules/v3/mutation_rules.proto"; +import "envoy/config/core/v3/substitution_format_string.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.http.transform.v3"; +option java_outer_classname = "TransformProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/transform/v3;transformv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Transform filter configuration] +// Transform filter :ref:`configuration overview ` to perform +// HTTP header and body transformations. +// [#extension: envoy.filters.http.transform] + +// Configuration for the transform filter. The filter may buffer the request/response until the +// entire body is received, and then mutate the headers and body according to the contents +// of the request/response. The request and response transformations are independent and could +// be configured separately. +// Only JSON body transformation is supported for now. +message TransformConfig { + // Configuration for transforming request. + // + // .. note:: + // + // If set then the entire request headers and body will always be buffered on a JSON request + // even if only headers are transformed. + Transformation request_transformation = 1; + + // Configuration for transforming response. + // + // .. note:: + // + // If set then the entire response headers and body will always be buffered on a JSON response + // even if only headers are transformed. + Transformation response_transformation = 2; + + // If true and the request headers are transformed, Envoy will re-evaluate the target + // cluster in the same route. Please ensure the cluster specifier in the route supports + // dynamic evaluation or this flag will have no effect, e.g. + // :ref:`matcher cluster specifier + // `. + // + // Only one of ``clear_cluster_cache`` and ``clear_route_cache`` can be true. + bool clear_cluster_cache = 3; + + // If true and the request headers are transformed, Envoy will clear the route cache for + // the current request and force re-evaluation of the route. This has performance penalty and + // should only be used when the route match criteria depends on the transformed headers. + // + // Only one of ``clear_cluster_cache`` and ``clear_route_cache`` can be true. + bool clear_route_cache = 4; +} + +message Transformation { + // The header mutations to perform. + // The :ref:`substitution format specifier ` could be applied here. + // In addition to the commonly used format specifiers, this filter introduces additional format specifiers: + // + // * ``%REQUEST_BODY(KEY*)%``: the request body. And ``Key`` KEY is an optional + // lookup key in the namespace with the option of specifying nested keys separated by ':'. + // * ``%RESPONSE_BODY(KEY*)%``: the response body. And ``Key`` KEY is an optional + // lookup key in the namespace with the option of specifying nested keys separated by ':'. + repeated config.common.mutation_rules.v3.HeaderMutation headers_mutations = 1; + + // The body transformation configuration. If not set, no body transformation will be performed. + BodyTransformation body_transformation = 2; +} + +message BodyTransformation { + enum TransformAction { + // Merge the transformed body with the original body. This is the default action. + MERGE = 0; + + // Replace the original body with the transformed body. + REPLACE = 1; + } + + // Body transformation configuration. The substitution format string is used as the template + // to generate the transformed new body content. + // The :ref:`substitution format specifier ` could be applied here. + // And except the commonly used format specifiers, the additional format specifiers + // ``%REQUEST_BODY(KEY*)%`` and ``%RESPONSE_BODY(KEY*)%`` could also be used here. + config.core.v3.SubstitutionFormatString body_format = 1 + [(validate.rules).message = {required: true}]; + + // The action to perform for new body content and original body content. + // For example, if ``MERGE`` is used, then the new body content generated from the ``body_format`` + // will be merged into the original body content. + // + // Default is ``MERGE``. + TransformAction action = 2; +} diff --git a/xds-api/src/main/proto/envoy/extensions/filters/listener/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/filters/listener/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000000..f2a4eca7dba --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/listener/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,73 @@ +syntax = "proto3"; + +package envoy.extensions.filters.listener.dynamic_modules.v3; + +import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto"; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.listener.dynamic_modules.v3"; +option java_outer_classname = "DynamicModulesProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/listener/dynamic_modules/v3;dynamic_modulesv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Listener filter for dynamic modules] +// [#extension: envoy.filters.listener.dynamic_modules] + +// Configuration of the listener filter for dynamic modules. This filter allows loading shared object +// files that can be loaded via dlopen by the listener filter. +// +// A module can be loaded by multiple listener filters, hence the program can be structured in a way +// that the module is loaded only once and shared across multiple filters providing multiple +// functionalities. +// +// Unlike network filters which operate on established TCP connections, listener filters +// work with raw accepted sockets BEFORE a Connection object is created. The filter can: +// +// * Inspect initial bytes to detect protocols (TLS, HTTP, PostgreSQL, etc.). +// * Set socket properties (SNI, ALPN, transport protocol, fingerprints). +// * Modify connection addresses (original destination restoration). +// * Set dynamic metadata and filter state for downstream filters. +// * Rate limit incoming connections. +// +message DynamicModuleListenerFilter { + // Specifies the shared-object level configuration. + envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; + + // The name for this filter configuration. This can be used to distinguish between different + // filter implementations inside a dynamic module. For example, a module can have completely + // different filter implementations (TLS inspector, rate limiter, proxy protocol parser). + // When Envoy receives this configuration, it passes the ``filter_name`` to the dynamic module's + // listener filter config init function together with the ``filter_config``. That way a module + // can decide which in-module filter implementation to use based on the name at load time. + string filter_name = 2; + + // The configuration for the filter chosen by ``filter_name``. This is passed to the module's + // listener filter initialization function. Together with the ``filter_name``, the module can + // decide which in-module filter implementation to use and fine-tune the behavior of the filter. + // + // For example, if a module has two filter implementations, one for TLS inspection and one for + // rate limiting, ``filter_name`` is used to choose either TLS or rate limiting. The ``filter_config`` + // can be used to configure the TLS inspection options or the rate limiting parameters. + // + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly + // without the wrapper. + // + // .. code-block:: yaml + // + // # Passing a string value + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: hello + // + // # Passing raw bytes + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.BytesValue" + // value: aGVsbG8= # echo -n "hello" | base64 + // + google.protobuf.Any filter_config = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto b/xds-api/src/main/proto/envoy/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto index cc96c4822e2..b90d08dc05f 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto @@ -18,11 +18,20 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // PROXY protocol listener filter. // [#extension: envoy.filters.listener.proxy_protocol] -// [#next-free-field: 6] +// [#next-free-field: 7] message ProxyProtocol { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.listener.proxy_protocol.v2.ProxyProtocol"; + // Controls where TLV values are stored when rules match. + enum TlvLocation { + // Store TLV values in dynamic metadata. + DYNAMIC_METADATA = 0; + + // Store TLV values in filter state as a single map-like object. + FILTER_STATE = 1; + } + message KeyValuePair { // The namespace — if this is empty, the filter's namespace will be used. string metadata_namespace = 1; @@ -92,4 +101,7 @@ message ProxyProtocol { // See the :ref:`filter's statistics documentation ` for // more information. string stat_prefix = 5; + + // Controls where TLV values are stored when rules match. Defaults to DYNAMIC_METADATA. + TlvLocation tlv_location = 6; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto b/xds-api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto index b4fe6d72f99..365af523a94 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto @@ -18,6 +18,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Allows detecting whether the transport appears to be TLS or plaintext. // [#extension: envoy.filters.listener.tls_inspector] +// [#next-free-field: 6] message TlsInspector { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.listener.tls_inspector.v2.TlsInspector"; @@ -48,4 +49,11 @@ message TlsInspector { // counter to be incremented if the ClientHello message is over implementation defined limit // (currently 16Kb). bool close_connection_on_client_hello_parsing_errors = 4; + + // The maximum size in bytes of the ClientHello that the tls_inspector will + // process. If the ClientHello is larger than this size, the tls_inspector + // will stop processing and indicate failure. If not defined, defaults to + // 16KiB. + google.protobuf.UInt32Value max_client_hello_size = 5 + [(validate.rules).uint32 = {lte: 16384 gt: 255}]; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000000..808acc6ce67 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,79 @@ +syntax = "proto3"; + +package envoy.extensions.filters.network.dynamic_modules.v3; + +import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto"; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.network.dynamic_modules.v3"; +option java_outer_classname = "DynamicModulesProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/dynamic_modules/v3;dynamic_modulesv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Dynamic Modules Network Filter] +// [#extension: envoy.filters.network.dynamic_modules] + +// Configuration for the Dynamic Modules network filter. This filter allows loading shared object +// files that can be loaded via ``dlopen`` to extend the network filter chain. +// +// A module can be loaded by multiple network filters; the module is loaded only once and shared +// across multiple filters. +// +// Unlike HTTP filters which operate on structured headers, body, and trailers, network filters work +// with raw TCP byte streams. The filter can: +// +// * Inspect, modify, or inject data into the downstream connection. +// * Access connection-level information such as addresses and TLS status. +// * Control connection lifecycle (e.g., close the connection). +message DynamicModuleNetworkFilter { + // Specifies the shared-object level configuration. + envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; + + // The name for this filter configuration. + // + // This can be used to distinguish between different filter implementations inside a dynamic + // module. For example, a module can have completely different filter implementations. When Envoy + // receives this configuration, it passes the ``filter_name`` to the dynamic module's network + // filter config init function together with the ``filter_config``. That way a module can decide + // which in-module filter implementation to use based on the name at load time. + string filter_name = 2; + + // The configuration for the filter chosen by ``filter_name``. + // + // This is passed to the module's network filter initialization function. Together with the + // ``filter_name``, the module can decide which in-module filter implementation to use and + // fine-tune the behavior of the filter. + // + // For example, if a module has two filter implementations, one for echo and one for rate + // limiting, ``filter_name`` is used to choose either echo or rate limiting. The + // ``filter_config`` can be used to configure the echo behavior or the rate limiting parameters. + // + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly + // without the wrapper. + // + // .. code-block:: yaml + // + // # Passing a string value + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: hello + // + // # Passing raw bytes + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.BytesValue" + // value: aGVsbG8= # echo -n "hello" | base64 + // + google.protobuf.Any filter_config = 3; + + // If ``true``, the dynamic module is a terminal filter to use without an upstream connection. + // + // The dynamic module is responsible for creating and sending the response to downstream. + // + // Defaults to ``false``. + bool terminal_filter = 4; +} diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto index fb447f69062..64668a76f53 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto @@ -25,7 +25,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // gRPC Authorization API defined by // :ref:`CheckRequest `. // A failed check will cause this filter to close the TCP connection. -// [#next-free-field: 10] +// [#next-free-field: 12] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.ext_authz.v2.ExtAuthz"; @@ -76,4 +76,28 @@ message ExtAuthz { // // Defaults to ``false``. bool send_tls_alert_on_denial = 9; + + // Specifies a list of metadata namespaces whose values, if present, will be passed to the + // ext_authz service. The :ref:`filter_metadata ` + // is passed as an opaque ``protobuf::Struct``. + // + // For example, if the ``proxy_protocol`` listener filter is used and populates TLV metadata, + // then the following will pass that metadata to the authorization server for making decisions + // based on proxy protocol information. + // + // .. code-block:: yaml + // + // metadata_context_namespaces: + // - envoy.filters.listener.proxy_protocol + // + repeated string metadata_context_namespaces = 10; + + // Specifies a list of metadata namespaces whose values, if present, will be passed to the + // ext_authz service. :ref:`typed_filter_metadata ` + // is passed as a ``protobuf::Any``. + // + // This works similarly to ``metadata_context_namespaces`` but allows Envoy and the ext_authz server to share + // the protobuf message definition in order to perform safe parsing. + // + repeated string typed_metadata_context_namespaces = 11; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/geoip/v3/geoip.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/geoip/v3/geoip.proto new file mode 100644 index 00000000000..c5138f0516e --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/geoip/v3/geoip.proto @@ -0,0 +1,62 @@ +syntax = "proto3"; + +package envoy.extensions.filters.network.geoip.v3; + +import "envoy/config/core/v3/extension.proto"; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.network.geoip.v3"; +option java_outer_classname = "GeoipProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/geoip/v3;geoipv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: Geoip] +// Geoip :ref:`configuration overview `. +// [#extension: envoy.filters.network.geoip] + +// The network geolocation filter performs IP geolocation lookups on incoming connections +// and stores the results in the connection's filter state under the well-known key +// ``envoy.geoip``. The stored data is a ``GeoipInfo`` object that supports +// serialization for access logging and field-level access. +// +// See :ref:`well known filter state ` for details on accessing +// the geolocation data. +message Geoip { + // The prefix to use when emitting statistics. This is useful when there are multiple + // listeners configured with geoip filters, allowing stats to be grouped per listener. + // For example, with ``stat_prefix: "listener_1."``, stats would be emitted as + // ``listener_1.geoip.total``. + string stat_prefix = 1; + + // Geoip driver specific configuration which depends on the driver being instantiated. + // [#extension-category: envoy.geoip_providers] + config.core.v3.TypedExtensionConfig provider = 2 [(validate.rules).message = {required: true}]; + + // Configuration for dynamically extracting the client IP address used for geolocation lookups. + // + // This field accepts the same :ref:`format specifiers ` as used for + // :ref:`HTTP access logging ` to extract the client IP. + // The formatted result must be a valid IPv4 or IPv6 address string. For example: + // + // * ``%FILTER_STATE(my.custom.client.ip:PLAIN)%`` - Read from filter state populated by a preceding filter. + // * ``%DYNAMIC_METADATA(namespace:key)%`` - Read from dynamic metadata. + // * ``%REQ(X-Forwarded-For)%`` - Extract from request header (if applicable in context). + // + // If not specified, defaults to the downstream connection's remote address. + // If specified but the result is empty, ``-``, or not a valid IP address, the filter + // falls back to the downstream connection's remote address. + // + // Example reading from filter state: + // + // .. code-block:: yaml + // + // client_ip: "%FILTER_STATE(my.custom.client.ip:PLAIN)%" + // + string client_ip = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index 730e065e6c4..9d8cf8bf4fd 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -20,6 +20,8 @@ import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; +import "xds/type/matcher/v3/matcher.proto"; + import "envoy/annotations/deprecation.proto"; import "udpa/annotations/migrate.proto"; import "udpa/annotations/security.proto"; @@ -37,7 +39,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: 60] +// [#next-free-field: 61] message HttpConnectionManager { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"; @@ -139,11 +141,13 @@ message HttpConnectionManager { UNESCAPE_AND_FORWARD = 4; } - // [#next-free-field: 11] + // [#next-free-field: 13] message Tracing { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing"; + // This OperationName makes no sense and is unnecessary in the current tracing API. + // [#not-implemented-hide:] enum OperationName { // The HTTP listener is used for ingress/incoming requests. INGRESS = 0; @@ -217,6 +221,28 @@ message HttpConnectionManager { // // The default value is false for now for backward compatibility. google.protobuf.BoolValue spawn_upstream_span = 10; + + // The operation name of the span which will be used for tracing. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // This field will take precedence over and make following settings ineffective: + // + // * :ref:`route decorator ` and + // * :ref:`x-envoy-decorator-operation ` + // header will be ignored. + string operation = 11; + + // The operation name of the upstream span which will be used for tracing. + // This only takes effect when ``spawn_upstream_span`` is set to true and the upstream + // span is created. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + string upstream_operation = 12; } message InternalAddressConfig { @@ -263,6 +289,15 @@ message HttpConnectionManager { bool uri = 5; } + // The configuration for forwarding client cert details. + message ForwardClientCertConfig { + // How to handle the XFCC header. + ForwardClientCertDetails forward_client_cert_details = 1; + + // How to set the current client cert details. + SetCurrentClientCertDetails set_current_client_cert_details = 2; + } + // The configuration for HTTP upgrades. // For each upgrade type desired, an UpgradeConfig must be added. // @@ -784,6 +819,53 @@ message HttpConnectionManager { // value. SetCurrentClientCertDetails set_current_client_cert_details = 17; + // The matcher for forwarding client cert details. This allows per-request configuration + // of forward client cert behavior based on request properties. If a matcher is configured + // and matches a request, the matched action's forward client cert config will be used. + // If the matcher is not configured or doesn't match, the static + // :ref:`forward_client_cert_details + // ` + // and + // :ref:`set_current_client_cert_details + // ` + // config will be used as fallback. + // + // Example: If the x-forwarded-client-cert header contains "trusted-client", use APPEND_FORWARD, + // otherwise use SANITIZE_SET: + // + // .. code-block:: yaml + // + // forward_client_cert_matcher: + // matcher_list: + // matchers: + // - predicate: + // single_predicate: + // input: + // name: envoy.matching.inputs.request_headers + // typed_config: + // "@type": type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput + // header_name: "x-forwarded-client-cert" + // value_match: + // string_match: + // contains: "trusted-client" + // on_match: + // action: + // name: forward_client_cert + // typed_config: + // "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ForwardClientCertConfig + // forward_client_cert_details: APPEND_FORWARD + // set_current_client_cert_details: + // uri: true + // on_no_match: + // action: + // name: forward_client_cert + // typed_config: + // "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ForwardClientCertConfig + // forward_client_cert_details: SANITIZE_SET + // set_current_client_cert_details: + // uri: true + xds.type.matcher.v3.Matcher forward_client_cert_matcher = 60; + // If proxy_100_continue is true, Envoy will proxy incoming "Expect: // 100-continue" headers upstream, and forward "100 Continue" responses // downstream. If this is false or not set, Envoy will instead strip the diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/rbac/v3/rbac.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/rbac/v3/rbac.proto index 9032a65924e..a65bbabc582 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/rbac/v3/rbac.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/rbac/v3/rbac.proto @@ -6,7 +6,6 @@ import "envoy/config/rbac/v3/rbac.proto"; import "google/protobuf/duration.proto"; -import "xds/annotations/v3/status.proto"; import "xds/type/matcher/v3/matcher.proto"; import "udpa/annotations/migrate.proto"; @@ -55,10 +54,8 @@ message RBAC { // not match any matcher will be denied. // If absent, no enforcing RBAC matcher will be applied. // If present and empty, deny all connections. - xds.type.matcher.v3.Matcher matcher = 6 [ - (udpa.annotations.field_migrate).oneof_promotion = "rules_specifier", - (xds.annotations.v3.field_status).work_in_progress = true - ]; + xds.type.matcher.v3.Matcher matcher = 6 + [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"]; // Shadow rules are not enforced by the filter but will emit stats and logs // and can be used for rule testing. @@ -70,10 +67,8 @@ message RBAC { // The match tree to use for emitting stats and logs which can be used for rule testing for // incoming connections. // If absent, no shadow matcher will be applied. - xds.type.matcher.v3.Matcher shadow_matcher = 7 [ - (udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier", - (xds.annotations.v3.field_status).work_in_progress = true - ]; + xds.type.matcher.v3.Matcher shadow_matcher = 7 + [(udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier"]; // 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-api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto index 40cc2858dfb..f24ee63904e 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.network.redis_proxy.v3; +import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/grpc_service.proto"; import "envoy/extensions/common/aws/v3/credential_provider.proto"; @@ -380,6 +381,19 @@ message RedisProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.redis_proxy.v2.RedisProtocolOptions"; + message Credential { + // The address to which this username and password applies. + config.core.v3.Address address = 1; + + // Upstream server password as defined by the ``requirepass`` directive + // ``_ in the server's configuration file. + config.core.v3.DataSource auth_password = 2 [(udpa.annotations.sensitive) = true]; + + // Upstream server username as defined by the ``user`` directive + // ``_ in the server's configuration file. + config.core.v3.DataSource auth_username = 3 [(udpa.annotations.sensitive) = true]; + } + // Upstream server password as defined by the ``requirepass`` directive // ``_ in the server's configuration file. // If ``aws_iam`` is set, this field is ignored. @@ -393,6 +407,13 @@ message RedisProtocolOptions { // The cluster level configuration for AWS IAM authentication AwsIam aws_iam = 3; + + // If specified, these credentials are used when connecting to upstream endpoints. Which + // credential is used is determined by matching the resolved ``address`` field here with each + // endpoint's resolved ``address`` field. The first entry for a given ``address`` here takes precedence. + // If no entry in ``credentials`` matches, then the ``auth_password`` and ``auth_username`` fields + // are used as defaults. + repeated Credential credentials = 4; } // [#next-free-field: 6] diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto index 28bcfe2c93e..98e9b722f5e 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto @@ -83,7 +83,7 @@ message Validation { // Configuration for the reverse tunnel network filter. // This filter handles reverse tunnel connection acceptance and rejection by processing // HTTP requests where required identification values are provided via HTTP headers. -// [#next-free-field: 6] +// [#next-free-field: 7] message ReverseTunnel { // Ping interval for health checks on established reverse tunnel connections. // If not specified, defaults to ``2 seconds``. @@ -113,4 +113,10 @@ message ReverseTunnel { // ``x-envoy-reverse-tunnel-cluster-id`` headers against expected values extracted // using format strings. Requests that fail validation are rejected with HTTP ``403 Forbidden``. Validation validation = 5; + + // Required cluster name for validating reverse tunnel connection initiations. + // When set, the filter validates that the upstream cluster of the initiator envoy matches this name + // via ``x-envoy-reverse-tunnel-upstream-cluster-name`` header. Connections with mismatched or missing + // cluster names are rejected with HTTP ``400 Bad Request``. When empty, no cluster name validation is performed. + string required_cluster_name = 6 [(validate.rules).string = {max_len: 255 ignore_empty: true}]; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto index 084f516e72f..f4be26f3857 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto @@ -24,4 +24,11 @@ message Config { // A sequence of the filter state values to apply in the specified order // when a new connection is received. repeated common.set_filter_state.v3.FilterStateValue on_new_connection = 1; + + // A sequence of the filter state values to apply in the specified order + // when the downstream TLS handshake is complete. + // + // For non-TLS downstream connections (where there is no TLS handshake), this + // list is applied when a new connection is received. + repeated common.set_filter_state.v3.FilterStateValue on_downstream_tls_handshake = 2; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto b/xds-api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto index ad47303d1f8..ff2156861f3 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto @@ -29,7 +29,35 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // TCP Proxy :ref:`configuration overview `. // [#extension: envoy.filters.network.tcp_proxy] -// [#next-free-field: 21] +// Specifies when the TCP proxy establishes the upstream connection. +enum UpstreamConnectMode { + // Establish the upstream connection immediately when the downstream connection is accepted. + // This is the default behavior and provides the lowest latency. + IMMEDIATE = 0; + + // Wait for initial data from the downstream connection before establishing the upstream connection. + // This allows preceding filters to inspect the initial data (e.g., extracting SNI from TLS ClientHello) + // before the upstream connection is established. + // + // This mode requires ``max_early_data_bytes`` to be set. + // + // .. warning:: + // This mode is not suitable for server-first protocols (e.g., SMTP, MySQL, POP3) where the + // server sends the initial greeting. For such protocols, use ``IMMEDIATE`` mode. + ON_DOWNSTREAM_DATA = 1; + + // Wait for the downstream TLS handshake to complete before establishing the upstream connection. + // This allows access to the full TLS connection information, including client certificates + // and negotiated parameters, which can be used for routing decisions or passed as metadata + // to the upstream. + // + // .. note:: + // This mode is only effective when the downstream connection uses TLS. For non-TLS + // connections, it behaves the same as ``IMMEDIATE``. + ON_DOWNSTREAM_TLS_HANDSHAKE = 2; +} + +// [#next-free-field: 23] message TcpProxy { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.tcp_proxy.v2.TcpProxy"; @@ -310,4 +338,30 @@ message TcpProxy { // :ref:`core.v3.ProxyProtocolConfig.pass_through_tlvs ` // for details. repeated config.core.v3.TlvEntry proxy_protocol_tlvs = 19; + + // Specifies when to establish the upstream connection. + // + // When not specified, defaults to ``IMMEDIATE`` for backward compatibility. + // + // .. attention:: + // Server-first protocols (e.g., SMTP, MySQL, POP3) require ``IMMEDIATE`` mode. + UpstreamConnectMode upstream_connect_mode = 21 [(validate.rules).enum = {defined_only: true}]; + + // Maximum bytes of early data to buffer from the downstream connection before + // the upstream connection is established. + // + // If not set, the TCP proxy will read-disable the downstream connection until the + // upstream connection is established (legacy behavior). + // + // If set, enables ``receive_before_connect`` mode where the filter allows the filter + // chain to read downstream data before the upstream connection exists. The data is + // buffered and forwarded once the upstream connection is ready. When the buffer exceeds + // this limit, the downstream connection is read-disabled to prevent excessive memory usage. + // + // This field is required when ``upstream_connect_mode`` is ``ON_DOWNSTREAM_DATA``. + // + // .. note:: + // Use this carefully with server-first protocols. The upstream may send data before + // receiving anything from downstream, which could fill the early data buffer. + google.protobuf.UInt32Value max_early_data_bytes = 22 [(validate.rules).uint32 = {lte: 1048576}]; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto b/xds-api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto index 322dabd24d6..621a0ffce60 100644 --- a/xds-api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto +++ b/xds-api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.udp.dns_filter.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"; @@ -111,4 +112,15 @@ message DnsFilterConfig { // 2. Otherwise, uses the default c-ares DNS resolver. // ClientContextConfig client_config = 3; + + // Configuration for :ref:`access logs ` + // emitted by the DNS filter for each DNS query received. + // Supports custom format commands for DNS-specific attributes: + // - ``QUERY_NAME``: The DNS query name being resolved + // - ``QUERY_TYPE``: The DNS query type (A, AAAA, SRV, etc.) + // - ``QUERY_CLASS``: The DNS query class + // - ``ANSWER_COUNT``: Number of answers in the response + // - ``RESPONSE_CODE``: DNS response code + // - ``PARSE_STATUS``: Whether the query was successfully parsed + repeated config.accesslog.v3.AccessLog access_log = 4; } diff --git a/xds-api/src/main/proto/envoy/extensions/filters/udp/dynamic_modules/v3/dynamic_modules.proto b/xds-api/src/main/proto/envoy/extensions/filters/udp/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000000..7f0defc717b --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/filters/udp/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,65 @@ +syntax = "proto3"; + +package envoy.extensions.filters.udp.dynamic_modules.v3; + +import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto"; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.udp.dynamic_modules.v3"; +option java_outer_classname = "DynamicModulesProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/udp/dynamic_modules/v3;dynamic_modulesv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Dynamic Modules UDP Listener Filter] +// [#extension: envoy.filters.udp_listener.dynamic_modules] + +// Configuration for the Dynamic Modules UDP listener filter. This filter allows loading shared object +// files that can be loaded via ``dlopen`` to extend the UDP listener filter chain. +// +// A module can be loaded by multiple UDP listener filters; the module is loaded only once and shared +// across multiple filters. +message DynamicModuleUdpListenerFilter { + // Specifies the shared-object level configuration. + envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; + + // The name for this filter configuration. + // + // This can be used to distinguish between different filter implementations inside a dynamic + // module. For example, a module can have completely different filter implementations. When Envoy + // receives this configuration, it passes the ``filter_name`` to the dynamic module's UDP listener + // filter config init function together with the ``filter_config``. That way a module can decide + // which in-module filter implementation to use based on the name at load time. + string filter_name = 2; + + // The configuration for the filter chosen by ``filter_name``. + // + // This is passed to the module's UDP listener filter initialization function. Together with the + // ``filter_name``, the module can decide which in-module filter implementation to use and + // fine-tune the behavior of the filter. + // + // For example, if a module has two filter implementations, one for echo and one for rate + // limiting, ``filter_name`` is used to choose either echo or rate limiting. The + // ``filter_config`` can be used to configure the echo behavior or the rate limiting parameters. + // + // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module. + // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly + // without the wrapper. + // + // .. code-block:: yaml + // + // # Passing a string value + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: hello + // + // # Passing raw bytes + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.BytesValue" + // value: aGVsbG8= # echo -n "hello" | base64 + // + google.protobuf.Any filter_config = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/formatter/metadata/v3/metadata.proto b/xds-api/src/main/proto/envoy/extensions/formatter/metadata/v3/metadata.proto index 816a6be2389..ccde766ee25 100644 --- a/xds-api/src/main/proto/envoy/extensions/formatter/metadata/v3/metadata.proto +++ b/xds-api/src/main/proto/envoy/extensions/formatter/metadata/v3/metadata.proto @@ -22,6 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // * ROUTE // * UPSTREAM_HOST // * LISTENER +// * LISTENER_FILTER_CHAIN // * VIRTUAL_HOST // // See :ref:`here ` for more information on access log configuration. diff --git a/xds-api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto b/xds-api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto index d4ccf4ebca2..778b2ca27c9 100644 --- a/xds-api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto +++ b/xds-api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto @@ -17,9 +17,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Common configuration shared across geolocation providers. message CommonGeoipProviderConfig { - // The set of geolocation headers to add to the request. If any of the configured headers is present - // in the incoming request, it will be overridden by the :ref:`GeoIP filter `. + // The set of geolocation headers to add to request. If any of the configured headers is present + // in the incoming request, it will be overridden by the :ref:`HTTP GeoIP filter `. // [#next-free-field: 13] + // + // .. attention:: + // This field is deprecated in favor of :ref:`geo_field_keys + // `. message GeolocationHeadersToAdd { // If set, the header will be used to populate the country ISO code associated with the IP address. string country = 1 @@ -80,6 +84,69 @@ message CommonGeoipProviderConfig { [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; } - // Configuration for geolocation headers to add to the request. - GeolocationHeadersToAdd geo_headers_to_add = 1 [(validate.rules).message = {required: true}]; + // The set of geolocation field keys to use for storing lookup results. + // These keys define how the geolocation lookup results will be stored. The actual storage + // mechanism depends on the filter using the provider: + // + // - The :ref:`HTTP GeoIP filter ` stores results as HTTP request headers. + // - The :ref:`Network GeoIP filter ` stores results in the + // connection's filter state under the well-known key ``envoy.geoip``. + // + // [#next-free-field: 12] + message GeolocationFieldKeys { + // If set, the key will be used to populate the country ISO code associated with the IP address. + string country = 1; + + // If set, the key will be used to populate the city associated with the IP address. + string city = 2; + + // If set, the key will be used to populate the region ISO code associated with the IP address. + // The least specific subdivision will be selected as the region value. + string region = 3; + + // If set, the key will be used to populate the ASN associated with the IP address. + string asn = 4; + + // If set, the IP address will be checked if it belongs to any type of anonymization network + // (e.g., VPN, public proxy). The result will be stored with this key. Value will be set to + // either ``true`` or ``false`` depending on the check result. + string anon = 5; + + // If set, the IP address will be checked if it belongs to a VPN and the result will be stored + // with this key. Value will be set to either ``true`` or ``false`` depending on the check result. + string anon_vpn = 6; + + // If set, the IP address will be checked if it belongs to a hosting provider and the result + // will be stored with this key. Value will be set to either ``true`` or ``false`` depending on + // the check result. + string anon_hosting = 7; + + // If set, the IP address will be checked if it belongs to a TOR exit node and the result will + // be stored with this key. Value will be set to either ``true`` or ``false`` depending on the + // check result. + string anon_tor = 8; + + // If set, the IP address will be checked if it belongs to a public proxy and the result will + // be stored with this key. Value will be set to either ``true`` or ``false`` depending on the + // check result. + string anon_proxy = 9; + + // If set, the key will be used to populate the ISP associated with the IP address. + string isp = 10; + + // If set, the IP address will be checked if it belongs to the ISP named iCloud Private Relay + // and the result will be stored with this key. Value will be set to either ``true`` or ``false`` + // depending on the check result. + string apple_private_relay = 11; + } + + // Configuration for geolocation headers to add to HTTP requests. + // This field is deprecated in favor of ``geo_field_keys``. If both are set, ``geo_field_keys`` + // takes precedence. + GeolocationHeadersToAdd geo_headers_to_add = 1 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; + + // Configuration for geolocation field keys. + // At least one of ``geo_headers_to_add`` or ``geo_field_keys`` must be set. + GeolocationFieldKeys geo_field_keys = 3; } diff --git a/xds-api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto b/xds-api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto index c1d7a2480eb..91e00c1dded 100644 --- a/xds-api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto +++ b/xds-api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto @@ -25,9 +25,10 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // * :ref:`isp_db_path ` // * :ref:`asn_db_path ` // * :ref:`anon_db_path ` +// * :ref:`country_db_path ` // [#extension: envoy.geoip_providers.maxmind] -// [#next-free-field: 6] +// [#next-free-field: 7] message MaxMindConfig { // Full file path to the MaxMind city database, e.g., ``/etc/GeoLite2-City.mmdb``. // Database file is expected to have ``.mmdb`` extension. @@ -48,6 +49,13 @@ message MaxMindConfig { // ``isp_db`` instead. string isp_db_path = 5 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; + // Full file path to the MaxMind Country database, e.g., ``/etc/GeoLite2-Country.mmdb``. + // Database file is expected to have ``.mmdb`` extension. + // + // If ``country_db_path`` is not specified, country information will be fetched from + // ``city_db`` if ``city_db`` is configured. + string country_db_path = 6 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; + // Common provider configuration that specifies which geolocation headers will be populated with geolocation data. common.v3.CommonGeoipProviderConfig common_provider_config = 4 [(validate.rules).message = {required: true}]; diff --git a/xds-api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto b/xds-api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto index 699dc357dde..2093797cc6f 100644 --- a/xds-api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto +++ b/xds-api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto @@ -68,4 +68,13 @@ message MappedAttributeBuilder { // interpretable by CEL. This allows for the re-mapping of attributes, which is not supported // by the native attribute building logic. map mapped_request_attributes = 1; + + // Similar to ``mapped_request_attributes``, but for response attributes. The + // response nomenclature here just indicates that the attributes, whatever they may be, are sent + // with a response headers, body, or trailers ext_proc call. + // If a value contains a request key, e.g., ``request.host``, then the attribute would + // just be sent along in the response. This is useful if a given ext_proc extension is only + // enabled for response handling, e.g., ``RESPONSE_HEADERS`` but the backend wants to access request + // metadata. + map mapped_response_attributes = 2; } diff --git a/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto b/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto index 7b8a1781673..e6c3bfaf5fd 100644 --- a/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto +++ b/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto @@ -31,4 +31,11 @@ message Generic { // If not set, filter will default to: ``Authorization`` string header = 2 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; + + // The prefix to prepend to the credential value before injecting it into the header. + // This is useful for adding a scheme such as ``Bearer `` or ``Basic `` to the credential. + // For example, if the credential is ``xyz123`` and the prefix is ``Bearer ``, the + // final header value will be ``Bearer xyz123``. + // If not set, the raw credential value will be injected without any prefix. + string header_value_prefix = 3; } diff --git a/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/oauth2/v3/oauth2.proto b/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/oauth2/v3/oauth2.proto index 0190dc4757f..9b013cdb9fb 100644 --- a/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/oauth2/v3/oauth2.proto +++ b/xds-api/src/main/proto/envoy/extensions/http/injected_credentials/oauth2/v3/oauth2.proto @@ -26,6 +26,7 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // proxied requests. // Currently, only the Client Credentials Grant flow is supported. // The access token will be injected into the request headers using the ``Authorization`` header as a bearer token. +// [#next-free-field: 6] message OAuth2 { enum AuthType { // The ``client_id`` and ``client_secret`` will be sent using HTTP Basic authentication scheme. @@ -53,6 +54,17 @@ message OAuth2 { AuthType auth_type = 3; } + // Optional additional parameters to include in the token endpoint request body. + // These parameters will be URL-encoded and added to the request body along with the standard OAuth2 parameters. + // Refer to your authorization server's documentation for supported parameters. + message EndpointParameter { + // Parameter name. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // Parameter value. + string value = 2; + } + // Endpoint on the authorization server to retrieve the access token from. // Refer to [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) for details. config.core.v3.HttpUri token_endpoint = 1 [(validate.rules).message = {required: true}]; @@ -73,4 +85,8 @@ message OAuth2 { // The interval must be at least 1 second. google.protobuf.Duration token_fetch_retry_interval = 4 [(validate.rules).duration = {gte {seconds: 1}}]; + + // Optional list of additional parameters to send to the token endpoint. + // These parameters will be URL-encoded and included in the token request body. + repeated EndpointParameter endpoint_params = 5; } diff --git a/xds-api/src/main/proto/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto b/xds-api/src/main/proto/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto index d1dd5f098ee..dcc594fc8cf 100644 --- a/xds-api/src/main/proto/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto +++ b/xds-api/src/main/proto/envoy/extensions/http/original_ip_detection/xff/v3/xff.proto @@ -37,10 +37,40 @@ message XffConfig { // When the remote IP address matches a trusted CIDR and the // :ref:`config_http_conn_man_headers_x-forwarded-for` header was sent, each entry // in the ``x-forwarded-for`` header is evaluated from right to left and the first - // public non-trusted address is used as the original client address. If all + // non-trusted address is used as the original client address. If all // addresses in ``x-forwarded-for`` are within the trusted list, the first (leftmost) // entry is used. // + // .. warning:: + // + // Starting with Envoy v1.33.0, private IP address ranges are **not** automatically skipped + // when determining the original client address. We'll return the first address that is not + // in the ``xff_trusted_cidrs`` list, even if it is a private IP address. + // + // If you want to skip private IP addresses, explicitly add them to the ``xff_trusted_cidrs`` + // list. For example: + // + // .. code-block:: yaml + // + // xff_trusted_cidrs: + // cidrs: + // - address_prefix: "10.0.0.0" + // prefix_len: 8 + // - address_prefix: "172.16.0.0" + // prefix_len: 12 + // - address_prefix: "192.168.0.0" + // prefix_len: 16 + // - address_prefix: "127.0.0.0" + // prefix_len: 8 + // - address_prefix: "fc00::" + // prefix_len: 7 + // - address_prefix: "::1" + // prefix_len: 128 + // + // See :ref:`internal_address_config + // ` + // for more information about the v1.33.0 behavior change. + // // This is typically used when requests are proxied by a // `CDN `_. // diff --git a/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index abaaf4ea828..c55d30b89e0 100644 --- a/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -87,6 +87,5 @@ message ClientSideWeightedRoundRobin { // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. - // [#not-implemented-hide:] common.v3.SlowStartConfig slow_start_config = 8; } diff --git a/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/random_subsetting/v3/random_subsetting.proto b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/random_subsetting/v3/random_subsetting.proto new file mode 100644 index 00000000000..ce616be14e0 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/random_subsetting/v3/random_subsetting.proto @@ -0,0 +1,46 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.random_subsetting.v3; + +import "envoy/config/cluster/v3/cluster.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.random_subsetting.v3"; +option java_outer_classname = "RandomSubsettingProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/random_subsetting/v3;random_subsettingv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Random Subsetting Load Balancing Policy] +// [#not-implemented-hide:] +// [#extension: envoy.load_balancing_policies.random_subsetting] +// [#next-free-field: 3] + +// Configuration for the Random Subsetting Load Balancing Policy +// +// This policy selects a subset of endpoints and passes them to the child LB policy. +// It maintains 2 important properties: +// 1. The policy tries to distribute connections among servers as equally as possible. The higher +// ``(N_clients*subset_size)/N_servers`` ratio is, the closer the resulting server connection +// distribution is to uniform. +// 2. The policy minimizes the amount of connection churn generated during server scale-ups by +// using rendezvous hashing +// +// See the :ref:`load balancing architecture +// overview` for more information. +// +// [#not-implemented-hide:] +message RandomSubsetting { + // subset_size indicates how many backends every client will be connected to. + // The value must be greater than 0. + google.protobuf.UInt32Value subset_size = 1 [(validate.rules).uint32 = {gt: 0}]; + + // The config for the child policy. + // The value is required. + config.cluster.v3.LoadBalancingPolicy child_policy = 2 + [(validate.rules).message = {required: true}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto index ab8367a401a..e2e4ade8236 100644 --- a/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto +++ b/xds-api/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto @@ -14,7 +14,7 @@ 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:] +// [#extension: envoy.load_balancing_policies.wrr_locality] // Configuration for the wrr_locality LB policy. See the :ref:`load balancing architecture overview // ` for more information. diff --git a/xds-api/src/main/proto/envoy/extensions/local_address_selectors/filter_state_override/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/local_address_selectors/filter_state_override/v3/config.proto new file mode 100644 index 00000000000..86dc67b965f --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/local_address_selectors/filter_state_override/v3/config.proto @@ -0,0 +1,22 @@ +syntax = "proto3"; + +package envoy.extensions.local_address_selectors.filter_state_override.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.local_address_selectors.filter_state_override.v3"; +option java_outer_classname = "ConfigProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/local_address_selectors/filter_state_override/v3;filter_state_overridev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Linux Network Namespace Local Address Selector] +// [#extension: envoy.upstream.local_address_selector.filter_state_override] + +// Overrides the upstream bind address Linux network namespace using a filter +// state object with the key ``envoy.network.upstream_bind_override.network_namespace`` +// passed from the downstream. The override applies over the :ref:`default +// address selector +// ` +message Config { +} diff --git a/xds-api/src/main/proto/envoy/extensions/matching/common_inputs/transport_socket/v3/transport_socket_inputs.proto b/xds-api/src/main/proto/envoy/extensions/matching/common_inputs/transport_socket/v3/transport_socket_inputs.proto new file mode 100644 index 00000000000..9ddc1abcd3e --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/matching/common_inputs/transport_socket/v3/transport_socket_inputs.proto @@ -0,0 +1,124 @@ +syntax = "proto3"; + +package envoy.extensions.matching.common_inputs.transport_socket.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.matching.common_inputs.transport_socket.v3"; +option java_outer_classname = "TransportSocketInputsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/matching/common_inputs/transport_socket/v3;transport_socketv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Transport Socket Matching Inputs] + +// Specifies that matching should be performed by the endpoint metadata. +// This input extracts metadata from the selected endpoint for transport socket selection. +// The metadata is extracted using a filter and path specification similar to +// :ref:`DynamicMetadataInput `. +// +// Example: Extract a metadata value for transport socket matching. +// +// .. code-block:: yaml +// +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.EndpointMetadataInput +// filter: "envoy.transport_socket_match" +// path: +// - key: "socket_type" +// +// This configuration extracts the value at path ``["envoy.transport_socket_match"]["socket_type"]`` +// from the endpoint metadata for use in transport socket selection. +// +// [#extension: envoy.matching.inputs.endpoint_metadata] +message EndpointMetadataInput { + // Specifies the segment in a path to retrieve value from Metadata. + // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that + // if the segment key refers to a list, it has to be the last segment in a path. + message PathSegment { + oneof segment { + option (validate.required) = true; + + // If specified, use the key to retrieve the value in a Struct. + string key = 1 [(validate.rules).string = {min_len: 1}]; + } + } + + // The filter name to retrieve the Struct from the endpoint metadata. + // If not specified, defaults to ``envoy.lb`` which is commonly used for load balancing metadata. + string filter = 1; + + // The path to retrieve the Value from the Struct. + repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; +} + +// Specifies that matching should be performed by the locality metadata. +// This input extracts metadata from the endpoint's locality for transport socket selection. +// The metadata is extracted using a filter and path specification similar to +// :ref:`DynamicMetadataInput `. +// +// Example: Extract a metadata value from locality for transport socket matching. +// +// .. code-block:: yaml +// +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.LocalityMetadataInput +// filter: "envoy.transport_socket_match" +// path: +// - key: "region" +// +// This configuration extracts the value at path ``["envoy.transport_socket_match"]["region"]`` +// from the locality metadata for use in transport socket selection. +// +// [#extension: envoy.matching.inputs.locality_metadata] +message LocalityMetadataInput { + // Specifies the segment in a path to retrieve value from Metadata. + // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that + // if the segment key refers to a list, it has to be the last segment in a path. + message PathSegment { + oneof segment { + option (validate.required) = true; + + // If specified, use the key to retrieve the value in a Struct. + string key = 1 [(validate.rules).string = {min_len: 1}]; + } + } + + // The filter name to retrieve the Struct from the locality metadata. + // If not specified, defaults to ``envoy.lb`` which is commonly used for load balancing metadata. + string filter = 1; + + // The path to retrieve the Value from the Struct. + repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; +} + +// Specifies that matching should be performed by filter state. +// This input extracts a value from filter state that was explicitly shared from the +// downstream connection to the upstream connection via ``TransportSocketOptions``. +// This enables flexible downstream-connection-based transport socket selection, +// such as matching on network namespace or any custom filter state data. +// +// Example: Match on network namespace stored in filter state. +// +// .. code-block:: yaml +// +// typed_config: +// "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.FilterStateInput +// key: "envoy.network.namespace" +// +// [#extension: envoy.matching.inputs.transport_socket_filter_state] +message FilterStateInput { + // The key of the filter state object to retrieve. + // The object must implement serializeAsString() to be used for matching. + string key = 1 [(validate.rules).string = {min_len: 1}]; +} + +// Configuration for the transport socket name action. +// This action sets the name of the transport socket to use when the matcher matches. +// [#extension: envoy.matching.action.transport_socket.name] +message TransportSocketNameAction { + // The name of the transport socket to use. + // This name must reference a named transport socket in the cluster's transport_socket_matches. + string name = 1 [(validate.rules).string = {min_len: 1}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto b/xds-api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto index b060bce969b..d05d073da4e 100644 --- a/xds-api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto +++ b/xds-api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto @@ -21,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.network.dns_resolver.cares] // Configuration for c-ares DNS resolver. -// [#next-free-field: 11] +// [#next-free-field: 12] message CaresDnsResolverConfig { // A list of DNS resolver addresses. // :ref:`use_resolvers_as_fallback ` @@ -99,4 +99,18 @@ message CaresDnsResolverConfig { // // If not specified, no periodic refresh will be performed. google.protobuf.Duration max_udp_channel_duration = 10 [(validate.rules).duration = {gte {}}]; + + // If true, reinitialize the c-ares channel when a DNS query fails with ``ARES_ETIMEOUT``. + // + // This can help recover from rare cases where the UDP sockets held by the c-ares + // channel become unusable after timeouts, causing subsequent queries to fail or + // Envoy to keep serving stale DNS results. When enabled, a timeout-triggered + // reinitialization attempts to restore healthy state quickly. In environments + // where timeouts are caused by intermittent network issues, enabling this may + // increase channel churn; consider using + // :ref:`max_udp_channel_duration ` + // for periodic refresh instead. + // + // Default is false. + bool reinit_channel_on_timeout = 11; } diff --git a/xds-api/src/main/proto/envoy/extensions/quic/client_writer_factory/v3/default_client_writer.proto b/xds-api/src/main/proto/envoy/extensions/quic/client_writer_factory/v3/default_client_writer.proto new file mode 100644 index 00000000000..c43160e58b7 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/quic/client_writer_factory/v3/default_client_writer.proto @@ -0,0 +1,18 @@ +syntax = "proto3"; + +package envoy.extensions.quic.client_writer_factory.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.quic.client_writer_factory.v3"; +option java_outer_classname = "DefaultClientWriterProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/quic/client_writer_factory/v3;client_writer_factoryv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Default QUIC Client Packet Writer] +// [#extension: envoy.quic.packet_writer.default] + +// The default QUIC packet writer used for QUIC upstream connections which is platform independent. +message DefaultClientWriter { +} diff --git a/xds-api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto b/xds-api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto index cd71bc31c18..9b29b01650c 100644 --- a/xds-api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto +++ b/xds-api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto @@ -37,6 +37,10 @@ message SinkConfig { repeated opentelemetry.proto.common.v1.KeyValue static_metric_labels = 3; } + // DropAction is an action that, when matched, will prevent the stat from being converted to an OTLP metric and flushed. + message DropAction { + } + oneof protocol_specifier { option (validate.required) = true; @@ -72,7 +76,10 @@ message SinkConfig { string prefix = 6; // The custom conversion from a stat to a metric. Currently, the only supported input is - // ``envoy.extensions.matching.common_inputs.stats.v3.StatFullNameMatchInput`` and the only support action is - // ``envoy.extensions.stat_sinks.open_telemetry.v3.SinkConfig.ConversionAction``. + // ``envoy.extensions.matching.common_inputs.stats.v3.StatFullNameMatchInput``. + // The supported actions are + // - ``envoy.extensions.stat_sinks.open_telemetry.v3.SinkConfig.DropAction``. + // - ``envoy.extensions.stat_sinks.open_telemetry.v3.SinkConfig.ConversionAction``. + // If stats are not matched, they will be directly converted to OTLP metrics as usual. xds.type.matcher.v3.Matcher custom_metric_conversions = 8; } diff --git a/xds-api/src/main/proto/envoy/extensions/transport_sockets/quic/v3/quic_transport.proto b/xds-api/src/main/proto/envoy/extensions/transport_sockets/quic/v3/quic_transport.proto index 585da764807..9756ff5a0f1 100644 --- a/xds-api/src/main/proto/envoy/extensions/transport_sockets/quic/v3/quic_transport.proto +++ b/xds-api/src/main/proto/envoy/extensions/transport_sockets/quic/v3/quic_transport.proto @@ -16,7 +16,8 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/tra option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: quic transport] -// [#comment:#extension: envoy.transport_sockets.quic] +// [#extension: envoy.transport_sockets.quic] +// The QUIC configurations below provide the transport socket configuration for downstream/upstream QUIC. // Configuration for Downstream QUIC transport socket. This provides Google's implementation of Google QUIC and IETF QUIC to Envoy. message QuicDownstreamTransport { diff --git a/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/sni/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/sni/v3/config.proto new file mode 100644 index 00000000000..e39abd2a962 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/sni/v3/config.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +package envoy.extensions.transport_sockets.tls.cert_mappers.sni.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.cert_mappers.sni.v3"; +option java_outer_classname = "ConfigProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/transport_sockets/tls/cert_mappers/sni/v3;sniv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: SNI certificate mapper] +// [#extension: envoy.tls.certificate_mappers.sni] + +// Uses the SNI value from the TLS client hello as the secret resource name. +message SNI { + // The value to use as the secret name when SNI is empty or absent. + string default_value = 1 [(validate.rules).string = {min_len: 1}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/static_name/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/static_name/v3/config.proto new file mode 100644 index 00000000000..0fbd87f46f2 --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_mappers/static_name/v3/config.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +package envoy.extensions.transport_sockets.tls.cert_mappers.static_name.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.cert_mappers.static_name.v3"; +option java_outer_classname = "ConfigProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/transport_sockets/tls/cert_mappers/static_name/v3;static_namev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Static secret certificate mapper] +// [#extension: envoy.tls.certificate_mappers.static_name] + +// A mapping to a fixed secret name for all certificates. +message StaticName { + // The name for the secret to use for all connections. + string name = 1 [(validate.rules).string = {min_len: 1}]; +} diff --git a/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_selectors/on_demand_secret/v3/config.proto b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_selectors/on_demand_secret/v3/config.proto new file mode 100644 index 00000000000..97d26e8a13e --- /dev/null +++ b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/cert_selectors/on_demand_secret/v3/config.proto @@ -0,0 +1,42 @@ +syntax = "proto3"; + +package envoy.extensions.transport_sockets.tls.cert_selectors.on_demand_secret.v3; + +import "envoy/config/core/v3/config_source.proto"; +import "envoy/config/core/v3/extension.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.cert_selectors.on_demand_secret.v3"; +option java_outer_classname = "ConfigProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/transport_sockets/tls/cert_selectors/on_demand_secret/v3;on_demand_secretv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: On-demand secret certificate selector] +// [#extension: envoy.tls.certificate_selectors.on_demand_secret] + +// Fetches the secret on-demand while allowing the parent cluster or listener to accept connections +// without warming. During the handshake, a secret name is derived from the peer hello message, an +// SDS resource request starts, and the handshake is paused. Once an SDS response is received with a +// resource, the handshake is resumed with the provided certificate. If the SDS server indicates the +// resource removal, the handshake is failed, and the SDS subscription to the resource is stopped. +// +// Similar to the regular SDS, the certificate is configured using the outer common TLS context, +// e.g. by setting the FIPS compliance policy on the loaded certificate. +message Config { + // Defines the configuration source of the secrets. + config.core.v3.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; + + // Extension point to specify a function to compute the secret name. The extension is called + // during the TLS handshake after receiving the "CLIENT HELLO" message from the client. + // [#extension-category: envoy.tls.certificate_mappers] + config.core.v3.TypedExtensionConfig certificate_mapper = 2 + [(validate.rules).message = {required: true}]; + + // A list of secret resource names to start fetching on configuration load (prior to receiving any + // requests). The parent resource initializes immediately without waiting for the fetch to + // complete. + repeated string prefetch_secret_names = 3; +} diff --git a/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto index b292b18c45d..d656c66b5d0 100644 --- a/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto +++ b/xds-api/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto @@ -300,6 +300,7 @@ message CommonTlsContext { // Select TLS certificate based on TLS client hello. // If empty, defaults to native TLS certificate selection behavior: // DNS SANs or Subject Common Name in TLS certificates is extracted as server name pattern to match SNI. + // [#extension-category: envoy.tls.certificate_selectors] config.core.v3.TypedExtensionConfig custom_tls_certificate_selector = 16; // Certificate provider for fetching TLS certificates. diff --git a/xds-api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto b/xds-api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto index 517f532f1d9..03f0158ed17 100644 --- a/xds-api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto +++ b/xds-api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto @@ -5,6 +5,7 @@ package envoy.extensions.upstreams.http.v3; import "envoy/config/common/matcher/v3/matcher.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/protocol.proto"; +import "envoy/config/route/v3/route_components.proto"; import "envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"; import "udpa/annotations/status.proto"; @@ -60,7 +61,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // http2_protocol_options: // max_concurrent_streams: 100 // .... [further cluster config] -// [#next-free-field: 9] +// [#next-free-field: 12] message HttpProtocolOptions { // If this is used, the cluster will only operate on one of the possible upstream protocols. // Note that HTTP/2 or above should generally be used for upstream gRPC clusters. @@ -185,4 +186,38 @@ message HttpProtocolOptions { // Defines http specific outlier detection parameters. OutlierDetection outlier_detection = 8; + + // Specifies a list of HTTP-level mirroring policies for requests routed to this cluster. + // Cluster-level policies override route-level policies when they both are configured. + // + // .. note:: + // + // Mirroring will not be triggered if the :ref:`primary cluster + // ` does not exist. + repeated config.route.v3.RouteAction.RequestMirrorPolicy request_mirror_policies = 9; + + // Specifies a list of hash policies for consistent hashing load balancing (e.g., Ring Hash or + // Maglev) for requests routed to this cluster. When configured, cluster-level policies override + // route-level policies. When not configured, route-level policies (if any) will be used. + // + // This enables consistent routing to the same upstream host for all requests to a cluster, + // which is particularly useful for stateful services like caching, session management, or + // sticky routing requirements. + // + // .. note:: + // + // Hash policies are only effective when the cluster is configured with a hash-based load + // balancing policy (e.g., :ref:`RING_HASH ` + // or :ref:`MAGLEV `). + repeated config.route.v3.RouteAction.HashPolicy hash_policy = 10; + + // Specifies the retry policy for requests routed to this cluster. When configured, + // cluster-level retry policy overrides route-level retry policy. When not configured, + // route-level retry policy (if any) will be used. + // + // .. note:: + // + // Cluster-level retry policy will override route-level retry policy entirely. Policies are + // not merged. + config.route.v3.RetryPolicy retry_policy = 11; } diff --git a/xds-api/src/main/proto/envoy/service/auth/v3/external_auth.proto b/xds-api/src/main/proto/envoy/service/auth/v3/external_auth.proto index 1f3ed5787d8..520a4ff4f31 100644 --- a/xds-api/src/main/proto/envoy/service/auth/v3/external_auth.proto +++ b/xds-api/src/main/proto/envoy/service/auth/v3/external_auth.proto @@ -114,6 +114,7 @@ message OkHttpResponse { } // Intended for gRPC and Network Authorization servers ``only``. +// [#next-free-field: 6] message CheckResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.service.auth.v2.CheckResponse"; @@ -132,6 +133,18 @@ message CheckResponse { // Supplies http attributes for an ok response. OkHttpResponse ok_response = 3; + + // Supplies http attributes for an error response. This is used when the authorization + // service encounters an internal error and wants to return custom headers and body to the + // downstream client. When ``error_response`` is set, the ext_authz filter increments the + // ``ext_authz_error`` stat and respects the :ref:`failure_mode_allow + // ` + // configuration. The HTTP status code, headers, and body are taken from the + // :ref:`DeniedHttpResponse ` message. + // If the status field is not set, Envoy sends the status code configured via + // :ref:`status_on_error `, + // which defaults to ``403 Forbidden``. + DeniedHttpResponse error_response = 5; } // Optional response metadata that will be emitted as dynamic metadata to be consumed by the next diff --git a/xds-api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto b/xds-api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto index 406c5c195a2..1c033c08d26 100644 --- a/xds-api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto +++ b/xds-api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto @@ -164,7 +164,7 @@ message ProcessingRequest { // the server must send back exactly one ProcessingResponse message. // * If it is set to ``FULL_DUPLEX_STREAMED``, the server must follow the API defined // for this mode to send the ProcessingResponse messages. -// [#next-free-field: 11] +// [#next-free-field: 13] message ProcessingResponse { // The response type that is sent by the server. oneof response { @@ -202,6 +202,20 @@ message ProcessingResponse { // this will either ship the reply directly to the downstream codec, // or reset the stream. ImmediateResponse immediate_response = 7; + + // The server sends back this message to initiate or continue local response streaming. + // The server must initiate local response streaming with the ``headers_response`` in response to a ProcessingRequest + // with the ``request_headers`` only. + // The server may follow up with multiple messages containing ``body_response``. The server must indicate + // end of stream by setting ``end_of_stream`` to ``true`` in the ``headers_response`` + // or ``body_response`` message or by sending a ``trailers_response`` message. + // The client may send a ``request_body`` or ``request_trailers`` to the server depending on configuration. + // The streaming local response can only be sent when the ``request_header_mode`` in the filter + // :ref:`processing_mode ` + // is set to ``SEND``. The ext_proc server should not send StreamedImmediateResponse if it did not observe request headers, + // as it will result in the race with the upstream server response and reset of the client request. + // Presently only the FULL_DUPLEX_STREAMED or NONE body modes are supported. + StreamedImmediateResponse streamed_immediate_response = 11; } // Optional metadata that will be emitted as dynamic metadata to be consumed by @@ -224,6 +238,19 @@ message ProcessingResponse { // is set to true. envoy.extensions.filters.http.ext_proc.v3.ProcessingMode mode_override = 9; + // [#not-implemented-hide:] + // Used only in ``FULL_DUPLEX_STREAMED`` and ``GRPC`` body send modes. + // Instructs the data plane to stop sending body data and to send a + // half-close on the ext_proc stream. The ext_proc server should then echo + // back all subsequent body contents as-is until it sees the client's + // half-close, at which point the ext_proc server can terminate the stream + // with an OK status. This provides a safe way for the ext_proc server + // to indicate that it does not need to see the rest of the stream; + // without this, the ext_proc server could not terminate the stream + // early, because it would wind up dropping any body contents that the + // client had already sent before it saw the ext_proc stream termination. + bool request_drain = 12; + // When ext_proc server receives a request message, in case it needs more // time to process the message, it sends back a ProcessingResponse message // with a new timeout value. When the data plane receives this response @@ -268,11 +295,27 @@ message HttpHeaders { message HttpBody { // The contents of the body in the HTTP request/response. Note that in // streaming mode multiple ``HttpBody`` messages may be sent. + // + // In ``GRPC`` body send mode, a separate ``HttpBody`` message will be + // sent for each message in the gRPC stream. bytes body = 1; // If ``true``, this will be the last ``HttpBody`` message that will be sent and no // trailers will be sent for the current request/response. bool end_of_stream = 2; + + // This field is used in ``GRPC`` body send mode when ``end_of_stream`` is + // true and ``body`` is empty. Those values would normally indicate an + // empty message on the stream with the end-of-stream bit set. + // However, if the half-close happens after the last message on the + // stream was already sent, then this field will be true to indicate an + // end-of-stream with *no* message (as opposed to an empty message). + bool end_of_stream_without_message = 3; + + // This field is used in ``GRPC`` body send mode to indicate whether + // the message is compressed. This will never be set to true by gRPC + // but may be set to true by a proxy like Envoy. + bool grpc_message_compressed = 4; } // This message is sent to the external server when the HTTP request and @@ -309,6 +352,23 @@ message TrailersResponse { HeaderMutation header_mutation = 1; } +// This message is sent by the external server to the data plane after ``HttpHeaders`` +// to initiate local response streaming. The server may follow up with multiple messages containing ``body_response``. +// The server must indicate end of stream by setting ``end_of_stream`` to ``true`` in the ``headers_response`` +// or ``body_response`` message or by sending a ``trailers_response`` message. +message StreamedImmediateResponse { + oneof response { + // Response headers to be sent downstream. The ":status" header must be set. + HttpHeaders headers_response = 1; + + // Response body to be sent downstream. + StreamedBodyResponse body_response = 2; + + // Response trailers to be sent downstream. + config.core.v3.HeaderMap trailers_response = 3; + } +} + // This message contains common fields between header and body responses. // [#next-free-field: 6] message CommonResponse { @@ -331,6 +391,8 @@ message CommonResponse { // // In other words, this response makes it possible to turn an HTTP GET // into a POST, PUT, or PATCH. + // + // Not supported if the body send mode is ``GRPC``. CONTINUE_AND_REPLACE = 1; } @@ -415,15 +477,34 @@ message HeaderMutation { repeated string remove_headers = 2; } -// The body response message corresponding to FULL_DUPLEX_STREAMED body mode. +// The body response message corresponding to ``FULL_DUPLEX_STREAMED`` or ``GRPC`` body modes. message StreamedBodyResponse { - // The body response chunk that will be passed to the upstream/downstream by the data plane. + // In ``FULL_DUPLEX_STREAMED`` body send mode, contains the body response chunk that will be + // passed to the upstream/downstream by the data plane. In ``GRPC`` body send mode, contains + // a serialized gRPC message to be passed to the upstream/downstream by the data plane. bytes body = 1; // The server sets this flag to true if it has received a body request with // :ref:`end_of_stream ` set to true, // and this is the last chunk of body responses. + // Note that in ``GRPC`` body send mode, this allows the ext_proc + // server to tell the data plane to send a half close after a client + // message, which will result in discarding any other messages sent by + // the client application. bool end_of_stream = 2; + + // This field is used in ``GRPC`` body send mode when ``end_of_stream`` is + // true and ``body`` is empty. Those values would normally indicate an + // empty message on the stream with the end-of-stream bit set. + // However, if the half-close happens after the last message on the + // stream was already sent, then this field will be true to indicate an + // end-of-stream with *no* message (as opposed to an empty message). + bool end_of_stream_without_message = 3; + + // This field is used in ``GRPC`` body send mode to indicate whether + // the message is compressed. This will never be set to true by gRPC + // but may be set to true by a proxy like Envoy. + bool grpc_message_compressed = 4; } // This message specifies the body mutation the server sends to the data plane. @@ -433,19 +514,19 @@ message BodyMutation { // The entire body to replace. // Should only be used when the corresponding ``BodySendMode`` in the // :ref:`processing_mode ` - // is not set to ``FULL_DUPLEX_STREAMED``. + // is not set to ``FULL_DUPLEX_STREAMED`` or ``GRPC``. bytes body = 1; // Clear the corresponding body chunk. // Should only be used when the corresponding ``BodySendMode`` in the // :ref:`processing_mode ` - // is not set to ``FULL_DUPLEX_STREAMED``. + // is not set to ``FULL_DUPLEX_STREAMED`` or ``GRPC``. // Clear the corresponding body chunk. bool clear_body = 2; // Must be used when the corresponding ``BodySendMode`` in the // :ref:`processing_mode ` - // is set to ``FULL_DUPLEX_STREAMED``. + // is set to ``FULL_DUPLEX_STREAMED`` or ``GRPC``. StreamedBodyResponse streamed_response = 3 [(xds.annotations.v3.field_status).work_in_progress = true]; } diff --git a/xds-api/src/main/proto/envoy/type/tracing/v3/custom_tag.proto b/xds-api/src/main/proto/envoy/type/tracing/v3/custom_tag.proto index feb57e8eb66..cdb42a43507 100644 --- a/xds-api/src/main/proto/envoy/type/tracing/v3/custom_tag.proto +++ b/xds-api/src/main/proto/envoy/type/tracing/v3/custom_tag.proto @@ -17,7 +17,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Custom Tag] // Describes custom tags for the active span. -// [#next-free-field: 6] +// [#next-free-field: 7] message CustomTag { option (udpa.annotations.versioning).previous_message_type = "envoy.type.tracing.v2.CustomTag"; @@ -98,5 +98,12 @@ message CustomTag { // A custom tag to obtain tag value from the metadata. Metadata metadata = 5; + + // Custom tag value. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + string value = 6; } } diff --git a/xds-api/src/main/proto/opentelemetry/proto/common/v1/common.proto b/xds-api/src/main/proto/opentelemetry/proto/common/v1/common.proto index 57c9f86e006..7f9ffab3707 100644 --- a/xds-api/src/main/proto/opentelemetry/proto/common/v1/common.proto +++ b/xds-api/src/main/proto/opentelemetry/proto/common/v1/common.proto @@ -22,7 +22,7 @@ option java_package = "io.opentelemetry.proto.common.v1"; option java_outer_classname = "CommonProto"; option go_package = "go.opentelemetry.io/proto/otlp/common/v1"; -// AnyValue is used to represent any type of attribute value. AnyValue may contain a +// Represents any type of attribute value. AnyValue may contain a // primitive value such as a string or integer or it may contain an arbitrary nested // object containing arrays, key-value lists and primitives. message AnyValue { @@ -54,29 +54,43 @@ message ArrayValue { message KeyValueList { // A collection of key/value pairs of key-value pairs. The list may be empty (may // contain 0 elements). + // // The keys MUST be unique (it is not allowed to have more than one // value with the same key). + // The behavior of software that receives duplicated keys can be unpredictable. repeated KeyValue values = 1; } -// KeyValue is a key-value pair that is used to store Span attributes, Link +// Represents a key-value pair that is used to store Span attributes, Link // attributes, etc. message KeyValue { + // The key name of the pair. string key = 1; + + // The value of the pair. AnyValue value = 2; } // InstrumentationScope is a message representing the instrumentation scope information // such as the fully qualified name and version. message InstrumentationScope { + // A name denoting the Instrumentation scope. // An empty instrumentation scope name means the name is unknown. string name = 1; + + // Defines the version of the instrumentation scope. + // An empty instrumentation scope version means the version is unknown. string version = 2; // Additional attributes that describe the scope. [Optional]. // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). + // The behavior of software that receives duplicated keys can be unpredictable. repeated KeyValue attributes = 3; + + // The number of attributes that were discarded. Attributes + // can be discarded because their keys are too long or because there are too many + // attributes. If this value is 0, then no attributes were dropped. uint32 dropped_attributes_count = 4; } diff --git a/xds-api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto b/xds-api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto index 8915e3c16b6..a6fab4ee750 100644 --- a/xds-api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto +++ b/xds-api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto @@ -96,7 +96,8 @@ message ScopeMetrics { // is recorded in. Notably, the last part of the URL path is the version number of the // schema: http[s]://server[:port]/path/. To learn more about Schema URL see // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url - // This schema_url applies to all metrics in the "metrics" field. + // This schema_url applies to the data in the "scope" field and all metrics in the + // "metrics" field. string schema_url = 3; } @@ -187,13 +188,13 @@ message ScopeMetrics { message Metric { reserved 4, 6, 8; - // name of the metric. + // The name of the metric. string name = 1; - // description of the metric, which can be used in documentation. + // A description of the metric, which can be used in documentation. string description = 2; - // unit in which the metric value is reported. Follows the format + // The unit in which the metric value is reported. Follows the format // described by https://unitsofmeasure.org/ucum.html. string unit = 3; @@ -215,6 +216,7 @@ message Metric { // for lossless roundtrip translation to / from another data model. // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue metadata = 12; } @@ -228,25 +230,31 @@ message Metric { // AggregationTemporality is not included. Consequently, this also means // "StartTimeUnixNano" is ignored for all data points. message Gauge { + // The time series data points. + // Note: Multiple time series may be included (same timestamp, different attributes). repeated NumberDataPoint data_points = 1; } // Sum represents the type of a scalar metric that is calculated as a sum of all // reported measurements over a time interval. message Sum { + // The time series data points. + // Note: Multiple time series may be included (same timestamp, different attributes). repeated NumberDataPoint data_points = 1; // aggregation_temporality describes if the aggregator reports delta changes // since last report time, or cumulative changes since a fixed start time. AggregationTemporality aggregation_temporality = 2; - // If "true" means that the sum is monotonic. + // Represents whether the sum is monotonic. bool is_monotonic = 3; } // Histogram represents the type of a metric that is calculated by aggregating // as a Histogram of all reported measurements over a time interval. message Histogram { + // The time series data points. + // Note: Multiple time series may be included (same timestamp, different attributes). repeated HistogramDataPoint data_points = 1; // aggregation_temporality describes if the aggregator reports delta changes @@ -257,6 +265,8 @@ message Histogram { // ExponentialHistogram represents the type of a metric that is calculated by aggregating // as a ExponentialHistogram of all reported double measurements over a time interval. message ExponentialHistogram { + // The time series data points. + // Note: Multiple time series may be included (same timestamp, different attributes). repeated ExponentialHistogramDataPoint data_points = 1; // aggregation_temporality describes if the aggregator reports delta changes @@ -274,6 +284,8 @@ message ExponentialHistogram { // because the count and sum fields of a SummaryDataPoint are assumed to be // cumulative values. message Summary { + // The time series data points. + // Note: Multiple time series may be included (same timestamp, different attributes). repeated SummaryDataPoint data_points = 1; } @@ -377,16 +389,7 @@ message NumberDataPoint { // where this point belongs. The list may be empty (may contain 0 elements). // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 7; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -435,16 +438,7 @@ message HistogramDataPoint { // where this point belongs. The list may be empty (may contain 0 elements). // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 9; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -529,16 +523,7 @@ message ExponentialHistogramDataPoint { // where this point belongs. The list may be empty (may contain 0 elements). // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 1; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -554,12 +539,12 @@ message ExponentialHistogramDataPoint { // 1970. fixed64 time_unix_nano = 3; - // count is the number of values in the population. Must be + // The number of values in the population. Must be // non-negative. This value must be equal to the sum of the "bucket_counts" // values in the positive and negative Buckets plus the "zero_count" field. fixed64 count = 4; - // sum of the values in the population. If count is zero then this field + // The sum of the values in the population. If count is zero then this field // must be zero. // // Note: Sum should only be filled out when measuring non-negative discrete @@ -586,7 +571,7 @@ message ExponentialHistogramDataPoint { // values depend on the range of the data. sint32 scale = 6; - // zero_count is the count of values that are either exactly zero or + // The count of values that are either exactly zero or // within the region considered zero by the instrumentation at the // tolerated degree of precision. This bucket stores values that // cannot be expressed using the standard exponential formula as @@ -605,12 +590,12 @@ message ExponentialHistogramDataPoint { // Buckets are a set of bucket counts, encoded in a contiguous array // of counts. message Buckets { - // Offset is the bucket index of the first entry in the bucket_counts array. + // The bucket index of the first entry in the bucket_counts array. // // Note: This uses a varint encoding as a simple form of compression. sint32 offset = 1; - // bucket_counts is an array of count values, where bucket_counts[i] carries + // An array of count values, where bucket_counts[i] carries // the count of the bucket at index (offset+i). bucket_counts[i] is the count // of values greater than base^(offset+i) and less than or equal to // base^(offset+i+1). @@ -630,10 +615,10 @@ message ExponentialHistogramDataPoint { // measurements that were used to form the data point repeated Exemplar exemplars = 11; - // min is the minimum value over (start_time, end_time]. + // The minimum value over (start_time, end_time]. optional double min = 12; - // max is the maximum value over (start_time, end_time]. + // The maximum value over (start_time, end_time]. optional double max = 13; // ZeroThreshold may be optionally set to convey the width of the zero @@ -655,16 +640,7 @@ message SummaryDataPoint { // where this point belongs. The list may be empty (may contain 0 elements). // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 7; // StartTimeUnixNano is optional but strongly encouraged, see the diff --git a/xds-api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto b/xds-api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto index dc101770dc3..a6af56d7a21 100644 --- a/xds-api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto +++ b/xds-api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto @@ -97,51 +97,81 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // // ProfilesDictionary represents the profiles data shared across the -// entire message being sent. +// entire message being sent. The following applies to all fields in this +// message: +// +// - A dictionary is an array of dictionary items. Users of the dictionary +// compactly reference the items using the index within the array. +// +// - A dictionary MUST have a zero value encoded as the first element. This +// allows for _index fields pointing into the dictionary to use a 0 pointer +// value to indicate 'null' / 'not set'. Unless otherwise defined, a 'zero +// value' message value is one with all default field values, so as to +// minimize wire encoded size. +// +// - There SHOULD NOT be dupes in a dictionary. The identity of dictionary +// items is based on their value, recursively as needed. If a particular +// implementation does emit duplicated items, it MUST NOT attempt to give them +// meaning based on the index or order. A profile processor may remove +// duplicate items and this MUST NOT have any observable effects for +// consumers. +// +// - There SHOULD NOT be orphaned (unreferenced) items in a dictionary. A +// profile processor may remove ("garbage-collect") orphaned items and this +// MUST NOT have any observable effects for consumers. // -// Note that all fields in this message MUST have a zero value encoded as the first element. -// This allows for _index fields pointing into the dictionary to use a 0 pointer value -// to indicate 'null' / 'not set'. Unless otherwise defined, a 'zero value' message value -// is one with all default field values, so as to minimize wire encoded size. message ProfilesDictionary { // Mappings from address ranges to the image/binary/library mapped // into that address range referenced by locations via Location.mapping_index. + // + // mapping_table[0] must always be zero value (Mapping{}) and present. repeated Mapping mapping_table = 1; // Locations referenced by samples via Stack.location_indices. + // + // location_table[0] must always be zero value (Location{}) and present. repeated Location location_table = 2; // Functions referenced by locations via Line.function_index. + // + // function_table[0] must always be zero value (Function{}) and present. repeated Function function_table = 3; // Links referenced by samples via Sample.link_index. + // + // link_table[0] must always be zero value (Link{}) and present. repeated Link link_table = 4; // A common table for strings referenced by various messages. - // string_table[0] must always be "". + // + // string_table[0] must always be "" and present. repeated string string_table = 5; - // A common table for attributes referenced by various messages. - // It is a collection of key/value pairs. Note, global attributes - // like server name can be set using the resource API. Examples of attributes: + // A common table for attributes referenced by the Profile, Sample, Mapping + // and Location messages below through attribute_indices field. Each entry is + // a key/value pair with an optional unit. Since this is a dictionary table, + // multiple entries with the same key may be present, unlike direct attribute + // tables like Resource.attributes. The referencing attribute_indices fields, + // though, do maintain the key uniqueness requirement. // + // It's recommended to use attributes for variables with bounded cardinality, + // such as categorical variables + // (https://en.wikipedia.org/wiki/Categorical_variable). Using an attribute of + // a floating point type (e.g., CPU time) in a sample can quickly make every + // attribute value unique, defeating the purpose of the dictionary and + // impractically increasing the profile size. + // + // Examples of attributes: // "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" - // "/http/server_latency": 300 // "abc.com/myattribute": true - // "abc.com/score": 10.239 + // "allocation_size": 128 bytes // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // attribute_table[0] must always be zero value (KeyValueAndUnit{}) and present. repeated KeyValueAndUnit attribute_table = 6; // Stacks referenced by samples via Sample.stack_index. + // + // stack_table[0] must always be zero value (Stack{}) and present. repeated Stack stack_table = 7; } @@ -206,7 +236,8 @@ message ScopeProfiles { // is recorded in. Notably, the last part of the URL path is the version number of the // schema: http[s]://server[:port]/path/. To learn more about Schema URL see // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url - // This schema_url applies to all profiles in the "profiles" field. + // This schema_url applies to the data in the "scope" field and all profiles in the + // "profiles" field. string schema_url = 3; } @@ -248,7 +279,7 @@ message Profile { // ["allocated_objects","count"] or ["allocated_space","bytes"], ValueType sample_type = 1; // The set of samples recorded in this profile. - repeated Sample sample = 2; + repeated Sample samples = 2; // The following fields 3-12 are informational, do not affect // interpretation of results. @@ -262,12 +293,6 @@ message Profile { ValueType period_type = 5; // The number of events between sampled occurrences. int64 period = 6; - // Free-form text associated with the profile. The text is displayed as is - // to the user by the tools that read profiles (e.g. by pprof). This field - // should not be used to store any machine-readable information, it is only - // for human-friendly content. The profile must stay functional if this field - // is cleaned. - repeated int32 comment_strindices = 7; // Indices into ProfilesDictionary.string_table. // A globally unique identifier for a profile. The ID is a 16-byte array. An ID with // all zeroes is considered invalid. It may be used for deduplication and signal @@ -275,26 +300,39 @@ message Profile { // in this field as not equal, even if they represented the same object at an earlier // time. // This field is optional; an ID may be assigned to an ID-less profile in a later step. - bytes profile_id = 8; + bytes profile_id = 7; - // dropped_attributes_count is the number of attributes that were discarded. Attributes + // The number of attributes that were discarded. Attributes // can be discarded because their keys are too long or because there are too many // attributes. If this value is 0, then no attributes were dropped. - uint32 dropped_attributes_count = 9; - - // Specifies format of the original payload. Common values are defined in semantic conventions. [required if original_payload is present] - string original_payload_format = 10; + uint32 dropped_attributes_count = 8; - // Original payload can be stored in this field. This can be useful for users who want to get the original payload. - // Formats such as JFR are highly extensible and can contain more information than what is defined in this spec. - // Inclusion of original payload should be configurable by the user. Default behavior should be to not include the original payload. - // If the original payload is in pprof format, it SHOULD not be included in this field. - // The field is optional, however if it is present then equivalent converted data should be populated in other fields - // of this message as far as is practicable. - bytes original_payload = 11; + // The original payload format. See also original_payload. Optional, but the + // format and the bytes must be set or unset together. + // + // The allowed values for the format string are defined by the OpenTelemetry + // specification. Some examples are "jfr", "pprof", "linux_perf". + // + // The original payload may be optionally provided when the conversion to the + // OLTP format was done from a different format with some loss of the fidelity + // and the receiver may want to store the original payload to allow future + // lossless export or reinterpretation. Some examples of the original format + // are JFR (Java Flight Recorder), pprof, Linux perf. + // + // Even when the original payload is in a format that is semantically close to + // OTLP, such as pprof, a conversion may still be lossy in some cases (e.g. if + // the pprof file contains custom extensions or conventions). + // + // The original payload can be large in size, so including the original + // payload should be configurable by the profiler or collector options. The + // default behavior should be to not include the original payload. + string original_payload_format = 9; + // The original payload bytes. See also original_payload_format. Optional, but + // format and the bytes must be set or unset together. + bytes original_payload = 10; // References to attributes in attribute_table. [optional] - repeated int32 attribute_indices = 12; + repeated int32 attribute_indices = 11; } // A pointer from a profile Sample to a trace Span. @@ -308,80 +346,13 @@ message Link { bytes span_id = 2; } -// Specifies the method of aggregating metric values, either DELTA (change since last report) -// or CUMULATIVE (total since a fixed start time). -enum AggregationTemporality { - /* UNSPECIFIED is the default AggregationTemporality, it MUST not be used. */ - AGGREGATION_TEMPORALITY_UNSPECIFIED = 0; - - /** DELTA is an AggregationTemporality for a profiler which reports - changes since last report time. Successive metrics contain aggregation of - values from continuous and non-overlapping intervals. - - The values for a DELTA metric are based only on the time interval - associated with one measurement cycle. There is no dependency on - previous measurements like is the case for CUMULATIVE metrics. - - For example, consider a system measuring the number of requests that - it receives and reports the sum of these requests every second as a - DELTA metric: - - 1. The system starts receiving at time=t_0. - 2. A request is received, the system measures 1 request. - 3. A request is received, the system measures 1 request. - 4. A request is received, the system measures 1 request. - 5. The 1 second collection cycle ends. A metric is exported for the - number of requests received over the interval of time t_0 to - t_0+1 with a value of 3. - 6. A request is received, the system measures 1 request. - 7. A request is received, the system measures 1 request. - 8. The 1 second collection cycle ends. A metric is exported for the - number of requests received over the interval of time t_0+1 to - t_0+2 with a value of 2. */ - AGGREGATION_TEMPORALITY_DELTA = 1; - - /** CUMULATIVE is an AggregationTemporality for a profiler which - reports changes since a fixed start time. This means that current values - of a CUMULATIVE metric depend on all previous measurements since the - start time. Because of this, the sender is required to retain this state - in some form. If this state is lost or invalidated, the CUMULATIVE metric - values MUST be reset and a new fixed start time following the last - reported measurement time sent MUST be used. - - For example, consider a system measuring the number of requests that - it receives and reports the sum of these requests every second as a - CUMULATIVE metric: - - 1. The system starts receiving at time=t_0. - 2. A request is received, the system measures 1 request. - 3. A request is received, the system measures 1 request. - 4. A request is received, the system measures 1 request. - 5. The 1 second collection cycle ends. A metric is exported for the - number of requests received over the interval of time t_0 to - t_0+1 with a value of 3. - 6. A request is received, the system measures 1 request. - 7. A request is received, the system measures 1 request. - 8. The 1 second collection cycle ends. A metric is exported for the - number of requests received over the interval of time t_0 to - t_0+2 with a value of 5. - 9. The system experiences a fault and loses state. - 10. The system recovers and resumes receiving at time=t_1. - 11. A request is received, the system measures 1 request. - 12. The 1 second collection cycle ends. A metric is exported for the - number of requests received over the interval of time t_1 to - t_1+1 with a value of 1. - - Note: Even though, when reporting changes since last report time, using - CUMULATIVE is valid, it is not recommended. */ - AGGREGATION_TEMPORALITY_CUMULATIVE = 2; -} - -// ValueType describes the type and units of a value, with an optional aggregation temporality. +// ValueType describes the type and units of a value. message ValueType { - int32 type_strindex = 1; // Index into ProfilesDictionary.string_table. - int32 unit_strindex = 2; // Index into ProfilesDictionary.string_table. + // Index into ProfilesDictionary.string_table. + int32 type_strindex = 1; - AggregationTemporality aggregation_temporality = 3; + // Index into ProfilesDictionary.string_table. + int32 unit_strindex = 2; } // Each Sample records values encountered in some program context. The program @@ -464,9 +435,9 @@ message Location { // preceding entries were inlined. // // E.g., if memcpy() is inlined into printf: - // line[0].function_name == "memcpy" - // line[1].function_name == "printf" - repeated Line line = 3; + // lines[0].function_name == "memcpy" + // lines[1].function_name == "printf" + repeated Line lines = 3; // References to attributes in ProfilesDictionary.attribute_table. [optional] repeated int32 attribute_indices = 4; } @@ -484,7 +455,7 @@ message Line { // Describes a function, including its human-readable name, system name, // source file, and starting line number in the source. message Function { - // Function name. Empty string if not available. + // The function name. Empty string if not available. int32 name_strindex = 1; // Function name, as identified by the system. For instance, // it can be a C++ mangled name. Empty string if not available. @@ -499,7 +470,11 @@ message Function { // for profiles than opentelemetry.proto.common.v1.KeyValue // Specifically, uses the string table for keys and allows optional unit information. message KeyValueAndUnit { + // The index into the string table for the attribute's key. int32 key_strindex = 1; + // The value of the attribute. opentelemetry.proto.common.v1.AnyValue value = 2; - int32 unit_strindex = 3; // zero indicates implicit (by semconv) or non-defined unit. + // The index into the string table for the attribute's unit. + // zero indicates implicit (by semconv) or non-defined unit. + int32 unit_strindex = 3; } diff --git a/xds-api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto b/xds-api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto index 8affbe3326d..42c5913cfae 100644 --- a/xds-api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto +++ b/xds-api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto @@ -29,19 +29,10 @@ message Resource { // Set of attributes that describe the resource. // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 1; - // dropped_attributes_count is the number of dropped attributes. If the value is 0, then + // The number of dropped attributes. If the value is 0, then // no attributes were dropped. uint32 dropped_attributes_count = 2; diff --git a/xds-api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto b/xds-api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto index fec6f9e3a9d..8a992c148c6 100644 --- a/xds-api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto +++ b/xds-api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto @@ -78,7 +78,8 @@ message ScopeSpans { // is recorded in. Notably, the last part of the URL path is the version number of the // schema: http[s]://server[:port]/path/. To learn more about Schema URL see // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url - // This schema_url applies to all spans and span events in the "spans" field. + // This schema_url applies to the data in the "scope" field and all spans and span + // events in the "spans" field. string schema_url = 3; } @@ -182,7 +183,7 @@ message Span { // and `SERVER` (callee) to identify queueing latency associated with the span. SpanKind kind = 6; - // start_time_unix_nano is the start time of the span. On the client side, this is the time + // The start time of the span. On the client side, this is the time // kept by the local machine where the span execution starts. On the server side, this // is the time when the server's application handler starts running. // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. @@ -190,7 +191,7 @@ message Span { // This field is semantically required and it is expected that end_time >= start_time. fixed64 start_time_unix_nano = 7; - // end_time_unix_nano is the end time of the span. On the client side, this is the time + // The end time of the span. On the client side, this is the time // kept by the local machine where the span execution ends. On the server side, this // is the time when the server application handler stops running. // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. @@ -198,7 +199,7 @@ message Span { // This field is semantically required and it is expected that end_time >= start_time. fixed64 end_time_unix_nano = 8; - // attributes is a collection of key/value pairs. Note, global attributes + // A collection of key/value pairs. Note, global attributes // like server name can be set using the resource API. Examples of attributes: // // "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" @@ -208,19 +209,10 @@ message Span { // // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 9; - // dropped_attributes_count is the number of attributes that were discarded. Attributes + // The number of attributes that were discarded. Attributes // can be discarded because their keys are too long or because there are too many // attributes. If this value is 0, then no attributes were dropped. uint32 dropped_attributes_count = 10; @@ -228,37 +220,28 @@ message Span { // Event is a time-stamped annotation of the span, consisting of user-supplied // text description and key-value pairs. message Event { - // time_unix_nano is the time the event occurred. + // The time the event occurred. fixed64 time_unix_nano = 1; - // name of the event. + // The name of the event. // This field is semantically required to be set to non-empty string. string name = 2; - // attributes is a collection of attribute key/value pairs on the event. + // A collection of attribute key/value pairs on the event. // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 3; - // dropped_attributes_count is the number of dropped attributes. If the value is 0, + // The number of dropped attributes. If the value is 0, // then no attributes were dropped. uint32 dropped_attributes_count = 4; } - // events is a collection of Event items. + // A collection of Event items. repeated Event events = 11; - // dropped_events_count is the number of dropped events. If the value is 0, then no + // The number of dropped events. If the value is 0, then no // events were dropped. uint32 dropped_events_count = 12; @@ -277,22 +260,13 @@ message Span { // The trace_state associated with the link. string trace_state = 3; - // attributes is a collection of attribute key/value pairs on the link. + // A collection of attribute key/value pairs on the link. // Attribute keys MUST be unique (it is not allowed to have more than one // attribute with the same key). - // - // The attribute values SHOULD NOT contain empty values. - // The attribute values SHOULD NOT contain bytes values. - // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values, - // double values. - // The attribute values SHOULD NOT contain kvlist values. - // The behavior of software that receives attributes containing such values can be unpredictable. - // These restrictions can change in a minor release. - // The restrictions take origin from the OpenTelemetry specification: - // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute. + // The behavior of software that receives duplicated keys can be unpredictable. repeated opentelemetry.proto.common.v1.KeyValue attributes = 4; - // dropped_attributes_count is the number of dropped attributes. If the value is 0, + // The number of dropped attributes. If the value is 0, // then no attributes were dropped. uint32 dropped_attributes_count = 5; @@ -316,11 +290,11 @@ message Span { fixed32 flags = 6; } - // links is a collection of Links, which are references from this span to a span + // A collection of Links, which are references from this span to a span // in the same or different trace. repeated Link links = 13; - // dropped_links_count is the number of dropped links after the maximum size was + // The number of dropped links after the maximum size was // enforced. If this value is 0, then no links were dropped. uint32 dropped_links_count = 14; diff --git a/xds-api/tools/API_SHAS b/xds-api/tools/API_SHAS index a98b7e2e1e6..4ae2ef4fa80 100644 --- a/xds-api/tools/API_SHAS +++ b/xds-api/tools/API_SHAS @@ -1,12 +1,12 @@ # Update the versions here and run update-api.sh # envoy (source: SHA from https://github.com/envoyproxy/envoy) -ENVOY_SHA="bad8280de85c25b147a90c1d9b8a8c67a13e7134" +ENVOY_SHA="5ef4e4cea57f63e7e2970b9c1ad696278db927d6" -# dependencies (source: https://github.com/envoyproxy/envoy/blob/bad8280de85c25b147a90c1d9b8a8c67a13e7134/api/bazel/repository_locations.bzl) +# dependencies (source: https://github.com/envoyproxy/envoy/blob/5ef4e4cea57f63e7e2970b9c1ad696278db927d6/api/bazel/repository_locations.bzl) GOOGLEAPIS_SHA="fd52b5754b2b268bc3a22a10f29844f206abb327" # 2024-09-16 -PGV_VERSION="1.0.4" # 2024-01-17 +PGV_VERSION="1.3.0" # 2025-12-04 PROMETHEUS_SHA="0.6.2" # 2025-04-11 -OPENTELEMETRY_VERSION="1.8.0" # 2025-09-02 -CEL_VERSION="0.24.0" # 2025-05-09 -XDS_SHA="2ac532fd44436293585084f8d94c6bdb17835af0" # 2025-05-01 +OPENTELEMETRY_VERSION="1.9.0" # 2025-10-31 +CEL_VERSION="0.25.1" # 2025-11-10 +XDS_SHA="8bfbf64dc13ee1a570be4fbdcfccbdd8532463f0" # 2025-11-10 diff --git a/xds-api/tools/envoy_release b/xds-api/tools/envoy_release index 4570b175220..094f172cf13 100644 --- a/xds-api/tools/envoy_release +++ b/xds-api/tools/envoy_release @@ -1 +1 @@ -v1.36.4 +v1.37.1