From 93e7edc380909df7014167db058e452a6ddc5968 Mon Sep 17 00:00:00 2001 From: envoy-bot Date: Wed, 15 Oct 2025 10:07:01 +0000 Subject: [PATCH] [protobuf] Update protobuf definitions to v1.36.0 Signed-off-by: envoy-bot --- .../conformance/proto3/test_all_types.proto | 2 +- .../cel/expr/conformance/test/suite.proto | 39 +- api/src/main/proto/cel/expr/eval.proto | 26 +- .../main/proto/envoy/admin/v3/clusters.proto | 16 +- .../envoy/config/bootstrap/v3/bootstrap.proto | 14 +- .../envoy/config/cluster/v3/cluster.proto | 17 +- .../config/common/matcher/v3/matcher.proto | 21 +- .../mutation_rules/v3/mutation_rules.proto | 10 + .../proto/envoy/config/core/v3/address.proto | 12 +- .../proto/envoy/config/core/v3/base.proto | 8 +- .../envoy/config/core/v3/config_source.proto | 5 +- .../envoy/config/core/v3/grpc_service.proto | 23 +- .../envoy/config/core/v3/health_check.proto | 6 +- .../proto/envoy/config/core/v3/protocol.proto | 69 ++-- .../envoy/config/core/v3/proxy_protocol.proto | 25 +- .../envoy/config/endpoint/v3/endpoint.proto | 5 +- .../config/endpoint/v3/load_report.proto | 6 +- .../config/grpc_credential/v3/aws_iam.proto | 46 --- .../envoy/config/listener/v3/listener.proto | 28 +- .../listener/v3/listener_components.proto | 2 +- .../proto/envoy/config/metrics/v3/stats.proto | 4 +- .../envoy/config/overload/v3/overload.proto | 22 +- .../proto/envoy/config/rbac/v3/rbac.proto | 63 ++-- .../config/route/v3/route_components.proto | 294 +++++++++++---- .../proto/envoy/config/tap/v3/common.proto | 7 + .../envoy/config/trace/v3/opentelemetry.proto | 9 +- .../proto/envoy/config/trace/v3/zipkin.proto | 85 ++++- .../envoy/data/core/v3/tlv_metadata.proto | 3 +- .../main/proto/envoy/data/tap/v3/http.proto | 3 + .../proto/envoy/data/tap/v3/transport.proto | 8 + ..._reverse_connection_socket_interface.proto | 27 ++ ..._reverse_connection_socket_interface.proto | 32 ++ .../clusters/aggregate/v3/cluster.proto | 17 + .../v3/reverse_connection.proto | 49 +++ .../common/aws/v3/credential_provider.proto | 106 ++++++ .../http/api_key_auth/v3/api_key_auth.proto | 27 +- .../v3/aws_request_signing.proto | 2 +- .../filters/http/cache_v2/v3/cache.proto | 108 ++++++ .../filters/http/composite/v3/composite.proto | 18 + .../http/compressor/v3/compressor.proto | 113 ++++-- .../v3/credential_injector.proto | 3 - .../v3/dynamic_forward_proxy.proto | 36 +- .../dynamic_modules/v3/dynamic_modules.proto | 48 +++ .../filters/http/ext_authz/v3/ext_authz.proto | 191 ++++++---- .../filters/http/ext_proc/v3/ext_proc.proto | 185 ++++++---- .../http/ext_proc/v3/processing_mode.proto | 15 +- .../v3/transcoder.proto | 69 +++- .../grpc_json_transcoder/v3/transcoder.proto | 7 +- .../header_mutation/v3/header_mutation.proto | 8 + .../v3/header_to_metadata.proto | 37 +- .../local_ratelimit/v3/local_rate_limit.proto | 14 + .../extensions/filters/http/lua/v3/lua.proto | 17 +- .../extensions/filters/http/mcp/v3/mcp.proto | 24 ++ .../filters/http/oauth2/v3/oauth.proto | 27 +- .../filters/http/on_demand/v3/on_demand.proto | 3 +- .../http/proto_api_scrubber/v3/config.proto | 89 +++++ .../v3/matcher_actions.proto | 21 ++ .../http/ratelimit/v3/rate_limit.proto | 46 ++- .../v3/stateful_session.proto | 9 + .../extensions/filters/http/tap/v3/tap.proto | 3 + .../v3/thrift_to_metadata.proto | 10 +- .../tls_inspector/v3/tls_inspector.proto | 20 +- .../network/ext_authz/v3/ext_authz.proto | 10 +- .../network/ext_proc/v3/ext_proc.proto | 36 +- .../v3/http_connection_manager.proto | 156 ++++---- .../network/redis_proxy/v3/redis_proxy.proto | 32 ++ .../reverse_tunnel/v3/reverse_tunnel.proto | 116 ++++++ .../network/tcp_proxy/v3/tcp_proxy.proto | 166 +++++---- .../udp/dns_filter/v3/dns_filter.proto | 9 +- .../extensions/formatter/cel/v3/cel.proto | 17 + .../geoip_providers/common/v3/common.proto | 34 +- .../geoip_providers/maxmind/v3/maxmind.proto | 30 +- .../v3/access_token_credentials.proto | 19 + .../v3/file_based_metadata_credentials.proto | 31 ++ .../google_compute_engine_credentials.proto | 17 + .../v3/google_iam_credentials.proto | 22 ++ .../v3/google_refresh_token_credentials.proto | 19 + ...rvice_account_jwt_access_credentials.proto | 24 ++ .../v3/sts_service_credentials.proto | 57 +++ .../v3/google_default_credentials.proto | 17 + .../insecure/v3/insecure_credentials.proto | 17 + .../local/v3/local_credentials.proto | 17 + .../tls/v3/tls_credentials.proto | 27 ++ .../xds/v3/xds_credentials.proto | 21 ++ .../health_checkers/redis/v3/redis.proto | 5 + .../v3/file_system_http_cache.proto | 131 +++++++ .../simple_http_cache/v3/config.proto | 20 + .../v3/mapped_attribute_builder.proto | 71 ++++ .../envoy_default/v3/header_validator.proto | 146 ++++++-- .../generic/v3/generic.proto | 3 - .../envelope/v3/envelope.proto | 52 +++ .../v3/client_side_weighted_round_robin.proto | 16 +- .../common/v3/common.proto | 46 ++- .../override_host/v3/override_host.proto | 79 ++++ .../network/v3/network_inputs.proto | 14 + .../common_inputs/stats/v3/stats.proto | 17 + .../cares/v3/cares_dns_resolver.proto | 55 ++- .../v3/getaddrinfo_dns_resolver.proto | 9 +- .../quic_lb/v3/quic_lb.proto | 27 +- ...ixed_server_preferred_address_config.proto | 25 +- .../cgroup_memory/v3/cgroup_memory.proto | 22 ++ .../matcher/v3/matcher.proto | 75 ++++ .../open_telemetry/v3/open_telemetry.proto | 27 +- .../samplers/v3/parent_based_sampler.proto | 31 ++ .../v3/trace_id_ratio_based_sampler.proto | 30 ++ .../transport_sockets/tap/v3/tap.proto | 3 + .../http/v3/http_protocol_options.proto | 13 +- .../proto/envoy/extensions/wasm/v3/wasm.proto | 37 +- .../service/discovery/v3/discovery.proto | 170 +++++---- .../ext_proc/v3/external_processor.proto | 68 ++-- .../extension/v3/config_discovery.proto | 20 +- .../v3/network_external_processor.proto | 16 +- .../proto/envoy/type/http/v3/cookie.proto | 16 + .../envoy/type/matcher/v3/metadata.proto | 32 +- .../proto/envoy/type/matcher/v3/string.proto | 22 +- .../proto/envoy/type/matcher/v3/value.proto | 2 +- .../main/proto/envoy/type/matcher/value.proto | 2 +- .../envoy/type/metadata/v3/metadata.proto | 32 +- .../collector/logs/v1/logs_service.proto | 2 - .../metrics/v1/metrics_service.proto | 2 - .../v1development/profiles_service.proto | 5 +- .../collector/trace/v1/trace_service.proto | 2 - .../proto/common/v1/common.proto | 34 ++ .../opentelemetry/proto/logs/v1/logs.proto | 2 - .../proto/metrics/v1/metrics.proto | 57 ++- .../profiles/v1development/profiles.proto | 342 ++++++++++-------- .../proto/resource/v1/resource.proto | 17 + .../opentelemetry/proto/trace/v1/trace.proto | 32 +- .../main/proto/xds/type/matcher/v3/cel.proto | 2 +- .../proto/xds/type/matcher/v3/matcher.proto | 8 + api/src/main/proto/xds/type/v3/cel.proto | 7 + .../controlplane/server/EnvoyContainer.java | 2 +- tools/API_SHAS | 12 +- tools/envoy_release | 2 +- 134 files changed, 3923 insertions(+), 1092 deletions(-) delete mode 100644 api/src/main/proto/envoy/config/grpc_credential/v3/aws_iam.proto create mode 100644 api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto create mode 100644 api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto create mode 100644 api/src/main/proto/envoy/extensions/clusters/reverse_connection/v3/reverse_connection.proto create mode 100644 api/src/main/proto/envoy/extensions/filters/http/cache_v2/v3/cache.proto create mode 100644 api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto create mode 100644 api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto create mode 100644 api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto create mode 100644 api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/access_token/v3/access_token_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/file_based_metadata/v3/file_based_metadata_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_compute_engine/v3/google_compute_engine_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_iam/v3/google_iam_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_refresh_token/v3/google_refresh_token_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/service_account_jwt_access/v3/service_account_jwt_access_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/call_credentials/sts_service/v3/sts_service_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/google_default/v3/google_default_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/insecure/v3/insecure_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/local/v3/local_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/tls/v3/tls_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/xds/v3/xds_credentials.proto create mode 100644 api/src/main/proto/envoy/extensions/http/cache_v2/file_system_http_cache/v3/file_system_http_cache.proto create mode 100644 api/src/main/proto/envoy/extensions/http/cache_v2/simple_http_cache/v3/config.proto create mode 100644 api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto create mode 100644 api/src/main/proto/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto create mode 100644 api/src/main/proto/envoy/extensions/load_balancing_policies/override_host/v3/override_host.proto create mode 100644 api/src/main/proto/envoy/extensions/matching/common_inputs/stats/v3/stats.proto create mode 100644 api/src/main/proto/envoy/extensions/resource_monitors/cgroup_memory/v3/cgroup_memory.proto create mode 100644 api/src/main/proto/envoy/extensions/router/cluster_specifiers/matcher/v3/matcher.proto create mode 100644 api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/parent_based_sampler.proto create mode 100644 api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/trace_id_ratio_based_sampler.proto diff --git a/api/src/main/proto/cel/expr/conformance/proto3/test_all_types.proto b/api/src/main/proto/cel/expr/conformance/proto3/test_all_types.proto index 8ddc472b2..c4b59fee7 100644 --- a/api/src/main/proto/cel/expr/conformance/proto3/test_all_types.proto +++ b/api/src/main/proto/cel/expr/conformance/proto3/test_all_types.proto @@ -63,7 +63,7 @@ message TestAllTypes { string single_string = 14; bytes single_bytes = 15; optional bool optional_bool = 16; - optional bool optional_string = 17; + optional string optional_string = 17; // Collides with 'in' operator. bool in = 18; diff --git a/api/src/main/proto/cel/expr/conformance/test/suite.proto b/api/src/main/proto/cel/expr/conformance/test/suite.proto index d6789bd9e..f9feab4a8 100644 --- a/api/src/main/proto/cel/expr/conformance/test/suite.proto +++ b/api/src/main/proto/cel/expr/conformance/test/suite.proto @@ -79,49 +79,44 @@ message TestCase { // environments. cel.expr.conformance.Environment env = 4; - // Input for the test case - TestInput input = 5; + // A map representing a variable binding where the key is the name of the + // input variable. + map input = 5; + + // Input in the form of a context proto for the test case. + // Note: Only one of `input_bindings` and `input_context` can be provided. Providing + // both should result in an error. + InputContext input_context = 6; // Expected result of the test case. - TestOutput output = 6; + TestOutput output = 7; // If specified validates that the deduced type at check time matches // If the result kind is not set and this field is set, the test is considered // "check-only". - cel.expr.Type deduced_type = 7; + cel.expr.Type deduced_type = 8; // Bypass the type-checking and only attempt to evaluate the parsed // expression. - bool disable_check = 8; + bool disable_check = 9; } -// Input for the test case -message TestInput { - // The type of input for the test case - oneof input_kind { - // A set of variable bindings to be used for evaluating a checked - // expression. - Bindings bindings = 1; - +// Input context proto for the test case +message InputContext { + // The type of input context for the test case + oneof input_context_kind { // A context message represents an input kind in the form of a proto // message whose type is defined at runtime. - google.protobuf.Any context_message = 2; + google.protobuf.Any context_message = 1; // A context expression representing a context proto variable. The // fields of the input proto.Messages are used as top-level variables within // an Activation. The expression is evaluated using the cel environment // configured for the test suite. - string context_expr = 3; + string context_expr = 2; } } -// The bindings of input variables for the test case. -message Bindings { - // A map representing a variable binding where the key is the name of the - // input variable. - map values = 1; -} - // The input value for a variable binding message InputValue { // The type of input value that can be used for a variable binding diff --git a/api/src/main/proto/cel/expr/eval.proto b/api/src/main/proto/cel/expr/eval.proto index 3f76f5761..8ad86988a 100644 --- a/api/src/main/proto/cel/expr/eval.proto +++ b/api/src/main/proto/cel/expr/eval.proto @@ -16,8 +16,8 @@ syntax = "proto3"; package cel.expr; +import "google/protobuf/any.proto"; import "cel/expr/value.proto"; -import "google/rpc/status.proto"; option cc_enable_arenas = true; option go_package = "cel.dev/expr"; @@ -104,9 +104,31 @@ message ExprValue { // // The errors included depend on the context. See `ExprValue.error`. message ErrorSet { - repeated google.rpc.Status errors = 1; + // Errors that could come up during evaluation phase. + repeated Status errors = 1; } + // Each `Status` message contains three pieces of data: error code, error message, + // and error details. + // + // You can find out more about this error model and how to work with it in the + // [API Design Guide](https://cloud.google.com/apis/design/errors). + // + // Status value is intended to be wire and field compatible with `google.rpc.Status`. + message Status { + // The status code, which should be an enum value of [google.rpc.Code][]. + int32 code = 1; + + // A developer-facing error message, which should be in English. Any + // user-facing error message should be localized and sent in the + // [Status.details][] field, or localized by the client. + string message = 2; + + // A list of messages that carry the error details. There is a common set of + // message types for APIs to use. + repeated google.protobuf.Any details = 3; + } + // A set of expressions for which the value is unknown. // // The unknowns included depend on the context. See `ExprValue.unknown`. diff --git a/api/src/main/proto/envoy/admin/v3/clusters.proto b/api/src/main/proto/envoy/admin/v3/clusters.proto index 9fab60d9a..4efc4c0ac 100644 --- a/api/src/main/proto/envoy/admin/v3/clusters.proto +++ b/api/src/main/proto/envoy/admin/v3/clusters.proto @@ -143,8 +143,8 @@ message HostStatus { // // .. note:: // - // The message will be missing if the host didn’t receive enough traffic to compute a success rate, or if the - // cluster didn’t have enough hosts to perform outlier ejection based on success rate. + // The message will be missing if the host didn't receive enough traffic to compute a success rate, or if the + // cluster didn't have enough hosts to perform outlier ejection based on success rate. // type.v3.Percent local_origin_success_rate = 8; @@ -171,18 +171,22 @@ message HostHealthStatus { // health checking. bool pending_dynamic_removal = 5; - // The host has not yet been health checked. + // The host is awaiting first health check. bool pending_active_hc = 6; // The host should be excluded from panic, spillover, etc. calculations because it was explicitly // taken out of rotation via protocol signal and is not meant to be routed to. bool excluded_via_immediate_hc_fail = 7; - // The host failed active HC due to timeout. + // The host failed active health check due to timeout. bool active_hc_timeout = 8; - // Health status as reported by EDS. Note: only HEALTHY and UNHEALTHY are currently supported - // here. + // Health status as reported by EDS. + // + // .. note:: + // + // Currently, only ``HEALTHY`` and ``UNHEALTHY`` are supported. + // // [#comment:TODO(mrice32): pipe through remaining EDS health status possibilities.] config.core.v3.HealthStatus eds_health_status = 3; } diff --git a/api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto b/api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto index 94868f134..28b1eba66 100644 --- a/api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto +++ b/api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto @@ -41,7 +41,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` for more detail. // Bootstrap :ref:`configuration overview `. -// [#next-free-field: 42] +// [#next-free-field: 43] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Bootstrap"; @@ -57,9 +57,7 @@ message Bootstrap { // If a network based configuration source is specified for :ref:`cds_config // `, it's necessary // to have some initial cluster definitions available to allow Envoy to know - // how to speak to the management server. These cluster definitions may not - // use :ref:`EDS ` (i.e. they should be static - // IP or DNS-based). + // how to speak to the management server. repeated cluster.v3.Cluster clusters = 2; // These static secrets can be used by :ref:`SdsSecretConfig @@ -232,6 +230,14 @@ message Bootstrap { bool stats_flush_on_admin = 29 [(validate.rules).bool = {const: true}]; } + oneof stats_eviction { + // Optional duration to perform metric eviction. At every interval, during the stats flush + // the unused metrics are removed from the worker caches and the used metrics + // are marked as unused. Must be a multiple of the ``stats_flush_interval``. + google.protobuf.Duration stats_eviction_interval = 42 + [(validate.rules).duration = {gte {nanos: 1000000}}]; + } + // Optional watchdog configuration. // This is for a single watchdog configuration for the entire system. // Deprecated in favor of ``watchdogs`` which has finer granularity. diff --git a/api/src/main/proto/envoy/config/cluster/v3/cluster.proto b/api/src/main/proto/envoy/config/cluster/v3/cluster.proto index 51180b1e8..c5112458a 100644 --- a/api/src/main/proto/envoy/config/cluster/v3/cluster.proto +++ b/api/src/main/proto/envoy/config/cluster/v3/cluster.proto @@ -652,9 +652,10 @@ message Cluster { // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge // window to 0. // - // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is - // because merging those updates isn't currently safe. See - // https://github.com/envoyproxy/envoy/pull/3941. + // .. note:: + // Merging does not apply to cluster membership changes (e.g.: adds/removes); this is + // because merging those updates isn't currently safe. See + // https://github.com/envoyproxy/envoy/pull/3941. google.protobuf.Duration update_merge_window = 4; // If set to true, Envoy will :ref:`exclude ` new hosts @@ -816,12 +817,14 @@ message Cluster { string name = 1 [(validate.rules).string = {min_len: 1}]; // An optional alternative to the cluster name to be used for observability. This name is used - // emitting stats for the cluster and access logging the cluster name. This will appear as + // for emitting stats for the cluster and access logging the cluster name. This will appear as // additional information in configuration dumps of a cluster's current status as // :ref:`observability_name ` - // and as an additional tag "upstream_cluster.name" while tracing. Note: Any ``:`` in the name - // will be converted to ``_`` when emitting statistics. This should not be confused with - // :ref:`Router Filter Header `. + // and as an additional tag "upstream_cluster.name" while tracing. + // + // .. note:: + // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be confused with + // :ref:`Router Filter Header `. string alt_stat_name = 28 [(udpa.annotations.field_migrate).rename = "observability_name"]; oneof cluster_discovery_type { diff --git a/api/src/main/proto/envoy/config/common/matcher/v3/matcher.proto b/api/src/main/proto/envoy/config/common/matcher/v3/matcher.proto index 49a146d73..9b189d1aa 100644 --- a/api/src/main/proto/envoy/config/common/matcher/v3/matcher.proto +++ b/api/src/main/proto/envoy/config/common/matcher/v3/matcher.proto @@ -41,6 +41,17 @@ message Matcher { // Protocol-specific action to take. core.v3.TypedExtensionConfig action = 2; } + + // If true, the action will be taken but the caller will behave as if no + // match was found. This applies both to actions directly encoded in the + // action field and to actions returned from a nested matcher tree in the + // matcher field. A subsequent matcher on_no_match action will be used + // instead. + // + // This field is not supported in all contexts in which the matcher API is + // used. If this field is set in a context in which it's not supported, + // the resource will be rejected. + bool keep_matching = 3; } // A linear list of field matchers. @@ -84,7 +95,7 @@ message Matcher { // A list of predicates to be AND-ed together. PredicateList and_matcher = 3; - // The invert of a predicate + // The inverse of a predicate Predicate not_matcher = 4; } } @@ -137,8 +148,8 @@ message Matcher { MatcherTree matcher_tree = 2; } - // Optional OnMatch to use if the matcher failed. - // If specified, the OnMatch is used, and the matcher is considered + // Optional ``OnMatch`` to use if the matcher failed. + // If specified, the ``OnMatch`` is used, and the matcher is considered // to have matched. // If not specified, the matcher is considered not to have matched. OnMatch on_no_match = 3; @@ -204,9 +215,9 @@ message HttpHeadersMatch { // // .. attention:: // -// Searching for patterns in HTTP body is potentially cpu intensive. For each specified pattern, http body is scanned byte by byte to find a match. +// Searching for patterns in HTTP body is potentially CPU-intensive. For each specified pattern, HTTP body is scanned byte by byte to find a match. // If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified -// to scan only part of the http body. +// to scan only part of the HTTP body. message HttpGenericBodyMatch { message GenericTextMatch { oneof rule { diff --git a/api/src/main/proto/envoy/config/common/mutation_rules/v3/mutation_rules.proto b/api/src/main/proto/envoy/config/common/mutation_rules/v3/mutation_rules.proto index d129ef1eb..c015db214 100644 --- a/api/src/main/proto/envoy/config/common/mutation_rules/v3/mutation_rules.proto +++ b/api/src/main/proto/envoy/config/common/mutation_rules/v3/mutation_rules.proto @@ -4,6 +4,7 @@ package envoy.config.common.mutation_rules.v3; import "envoy/config/core/v3/base.proto"; import "envoy/type/matcher/v3/regex.proto"; +import "envoy/type/matcher/v3/string.proto"; import "google/protobuf/wrappers.proto"; @@ -90,6 +91,12 @@ message HeaderMutationRules { // The HeaderMutation structure specifies an action that may be taken on HTTP // headers. message HeaderMutation { + message RemoveOnMatch { + // A string matcher that will be applied to the header key. If the header key + // matches, the header will be removed. + type.matcher.v3.StringMatcher key_matcher = 1 [(validate.rules).message = {required: true}]; + } + oneof action { option (validate.required) = true; @@ -99,5 +106,8 @@ message HeaderMutation { // Append new header by the specified HeaderValueOption. core.v3.HeaderValueOption append = 2; + + // Remove the header if the key matches the specified string matcher. + RemoveOnMatch remove_on_match = 3; } } diff --git a/api/src/main/proto/envoy/config/core/v3/address.proto b/api/src/main/proto/envoy/config/core/v3/address.proto index 38d74ef28..238494a09 100644 --- a/api/src/main/proto/envoy/config/core/v3/address.proto +++ b/api/src/main/proto/envoy/config/core/v3/address.proto @@ -98,9 +98,15 @@ message SocketAddress { // IPv6 space as ``::FFFF:``. bool ipv4_compat = 6; - // The Linux network namespace to bind the socket to. If this is set, Envoy will - // create the socket in the specified network namespace. Only supported on Linux. - // [#not-implemented-hide:] + // Filepath that specifies the Linux network namespace this socket will be created in (see ``man 7 + // network_namespaces``). If this field is set, Envoy will create the socket in the specified + // network namespace. + // + // .. note:: + // Setting this parameter requires Envoy to run with the ``CAP_NET_ADMIN`` capability. + // + // .. attention:: + // Network namespaces are only configurable on Linux. Otherwise, this field has no effect. string network_namespace_filepath = 7; } diff --git a/api/src/main/proto/envoy/config/core/v3/base.proto b/api/src/main/proto/envoy/config/core/v3/base.proto index 48ff5e7ee..978f365d5 100644 --- a/api/src/main/proto/envoy/config/core/v3/base.proto +++ b/api/src/main/proto/envoy/config/core/v3/base.proto @@ -266,7 +266,7 @@ message RuntimeUInt32 { uint32 default_value = 2; // Runtime key to get value for comparison. This value is used if defined. - string runtime_key = 3 [(validate.rules).string = {min_len: 1}]; + string runtime_key = 3; } // Runtime derived percentage with a default when not specified. @@ -275,7 +275,7 @@ message RuntimePercent { type.v3.Percent default_value = 1; // Runtime key to get value for comparison. This value is used if defined. - string runtime_key = 2 [(validate.rules).string = {min_len: 1}]; + string runtime_key = 2; } // Runtime derived double with a default when not specified. @@ -286,7 +286,7 @@ message RuntimeDouble { double default_value = 1; // Runtime key to get value for comparison. This value is used if defined. - string runtime_key = 2 [(validate.rules).string = {min_len: 1}]; + string runtime_key = 2; } // Runtime derived bool with a default when not specified. @@ -300,7 +300,7 @@ message RuntimeFeatureFlag { // Runtime key to get value for comparison. This value is used if defined. The boolean value must // be represented via its // `canonical JSON encoding `_. - string runtime_key = 2 [(validate.rules).string = {min_len: 1}]; + string runtime_key = 2; } // Please use :ref:`KeyValuePair ` instead. diff --git a/api/src/main/proto/envoy/config/core/v3/config_source.proto b/api/src/main/proto/envoy/config/core/v3/config_source.proto index f0effd99e..430562aa5 100644 --- a/api/src/main/proto/envoy/config/core/v3/config_source.proto +++ b/api/src/main/proto/envoy/config/core/v3/config_source.proto @@ -276,7 +276,8 @@ message ExtensionConfigSource { // to be supplied. bool apply_default_config_without_warming = 3; - // A set of permitted extension type URLs. Extension configuration updates are rejected - // if they do not match any type URL in the set. + // A set of permitted extension type URLs for the type encoded inside of the + // :ref:`TypedExtensionConfig `. Extension + // configuration updates are rejected if they do not match any type URL in the set. repeated string type_urls = 4 [(validate.rules).repeated = {min_items: 1}]; } diff --git a/api/src/main/proto/envoy/config/core/v3/grpc_service.proto b/api/src/main/proto/envoy/config/core/v3/grpc_service.proto index 5fd7921a8..f8feb2f51 100644 --- a/api/src/main/proto/envoy/config/core/v3/grpc_service.proto +++ b/api/src/main/proto/envoy/config/core/v3/grpc_service.proto @@ -64,7 +64,7 @@ message GrpcService { bool skip_envoy_headers = 5; } - // [#next-free-field: 9] + // [#next-free-field: 11] message GoogleGrpc { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.GrpcService.GoogleGrpc"; @@ -249,16 +249,31 @@ message GrpcService { } // The target URI when using the `Google C++ gRPC client - // `_. SSL credentials will be supplied in - // :ref:`channel_credentials `. + // `_. string target_uri = 1 [(validate.rules).string = {min_len: 1}]; + // The channel credentials to use. See `channel credentials + // `_. + // Ignored if ``channel_credentials_plugin`` is set. ChannelCredentials channel_credentials = 2; - // A set of call credentials that can be composed with `channel credentials + // A list of channel credentials plugins. + // The data plane will iterate over the list in order and stop at the first credential type + // that it supports. This provides a mechanism for starting to use new credential types that + // are not yet supported by all data planes. + // [#not-implemented-hide:] + repeated google.protobuf.Any channel_credentials_plugin = 9; + + // The call credentials to use. See `channel credentials // `_. + // Ignored if ``call_credentials_plugin`` is set. repeated CallCredentials call_credentials = 3; + // A list of call credentials plugins. All supported plugins will be used. + // Unsupported plugin types will be ignored. + // [#not-implemented-hide:] + repeated google.protobuf.Any call_credentials_plugin = 10; + // The human readable prefix to use when emitting statistics for the gRPC // service. // diff --git a/api/src/main/proto/envoy/config/core/v3/health_check.proto b/api/src/main/proto/envoy/config/core/v3/health_check.proto index fd4440d8f..a4ed6e918 100644 --- a/api/src/main/proto/envoy/config/core/v3/health_check.proto +++ b/api/src/main/proto/envoy/config/core/v3/health_check.proto @@ -102,7 +102,8 @@ message HealthCheck { // ``/healthcheck``. string path = 2 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_VALUE}]; - // [#not-implemented-hide:] HTTP specific payload. + // HTTP specific payload to be sent as the request body during health checking. + // If specified, the method should support a request body (POST, PUT, PATCH, etc.). Payload send = 3; // Specifies a list of HTTP expected responses to match in the first ``response_buffer_size`` bytes of the response body. @@ -161,7 +162,8 @@ message HealthCheck { type.matcher.v3.StringMatcher service_name_matcher = 11; // HTTP Method that will be used for health checking, default is "GET". - // GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, PATCH methods are supported, but making request body is not supported. + // GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, PATCH methods are supported. + // Request body payloads are supported for POST, PUT, PATCH, and OPTIONS methods only. // CONNECT method is disallowed because it is not appropriate for health check request. // If a non-200 response is expected by the method, it needs to be set in :ref:`expected_statuses `. RequestMethod method = 13 [(validate.rules).enum = {defined_only: true not_in: 6}]; diff --git a/api/src/main/proto/envoy/config/core/v3/protocol.proto b/api/src/main/proto/envoy/config/core/v3/protocol.proto index a90c07421..74fe641fe 100644 --- a/api/src/main/proto/envoy/config/core/v3/protocol.proto +++ b/api/src/main/proto/envoy/config/core/v3/protocol.proto @@ -64,8 +64,11 @@ message QuicProtocolOptions { // `_ size. Valid values range from // 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 window size now, so it's also the minimum. + // .. 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 + // 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 // QUIC stream send and receive buffers. Once the buffer reaches this pointer, watermark callbacks will fire to @@ -74,11 +77,14 @@ message QuicProtocolOptions { [(validate.rules).uint32 = {lte: 16777216 gte: 1}]; // Similar to ``initial_stream_window_size``, but for connection-level - // flow-control. Valid values rage from 1 to 25165824 (24MB, maximum supported by QUICHE) and defaults + // 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 - // window size now, so it's also the minimum. + // .. note:: + // + // 16384 (2^14) is the minimum window size supported in Google QUIC. We only support increasing the default + // window size now, so it's also the minimum. + // google.protobuf.UInt32Value initial_connection_window_size = 3 [(validate.rules).uint32 = {lte: 25165824 gte: 1}]; @@ -105,10 +111,9 @@ message QuicProtocolOptions { // 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. - google.protobuf.Duration idle_network_timeout = 8 [(validate.rules).duration = { - lte {seconds: 600} - gte {seconds: 1} - }]; + // 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. @@ -270,7 +275,7 @@ message HttpProtocolOptions { // 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 // reset for HTTP/2. - // Upstream responses that exceed this limit will result in a 503 response. + // Upstream responses that exceed this limit will result in a 502 response. google.protobuf.UInt32Value max_headers_count = 2 [(validate.rules).uint32 = {gte: 1}]; // The maximum size of response headers. @@ -282,9 +287,13 @@ message HttpProtocolOptions { // :ref:`HTTP Connection Manager // `. // - // Note: 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. + // .. note:: + // + // 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. + // google.protobuf.UInt32Value max_response_headers_kb = 7 [(validate.rules).uint32 = {lte: 8192 gt: 0}]; @@ -294,9 +303,15 @@ message HttpProtocolOptions { // 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. - // Note: upstream responses are not affected by this setting. - // Note: this only affects client headers. It does not affect headers added - // by Envoy filters and does not have any impact if added to cluster config. + // + // .. note:: + // + // Upstream responses are not affected by this setting. + // + // .. note:: + // + // This only affects client headers. It does not affect headers added by Envoy filters and does not have any + // impact if added to cluster config. HeadersWithUnderscoresAction headers_with_underscores_action = 5; // Optional maximum requests for both upstream and downstream connections. @@ -404,7 +419,7 @@ message Http1ProtocolOptions { // envoy.reloadable_features.http1_use_balsa_parser. // See issue #21245. google.protobuf.BoolValue use_balsa_parser = 9 - [(xds.annotations.v3.field_status).work_in_progress = true]; + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // [#not-implemented-hide:] Hiding so that field can be removed. // If true, and BalsaParser is used (either `use_balsa_parser` above is true, @@ -487,7 +502,7 @@ message Http2ProtocolOptions { // `Maximum concurrent streams `_ // allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1) - // and defaults to 2147483647. + // 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 @@ -501,11 +516,13 @@ message Http2ProtocolOptions { // `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 268435456 - // (256 * 1024 * 1024). + // (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to + // 16MiB (16 * 1024 * 1024). + // + // .. note:: // - // NOTE: 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. + // 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 // HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to @@ -514,7 +531,7 @@ message Http2ProtocolOptions { [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; // Similar to ``initial_stream_window_size``, but for connection-level flow-control - // window. Currently, this has the same minimum/maximum/default as ``initial_stream_window_size``. + // window. The default is 24MiB (24 * 1024 * 1024). google.protobuf.UInt32Value initial_connection_window_size = 4 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; @@ -656,7 +673,7 @@ message GrpcProtocolOptions { } // A message which allows using HTTP/3. -// [#next-free-field: 8] +// [#next-free-field: 9] message Http3ProtocolOptions { QuicProtocolOptions quic_protocol_options = 1; @@ -691,6 +708,10 @@ message Http3ProtocolOptions { // No huffman encoding, zero dynamic table capacity and no cookie crumbing. // This can be useful for trading off CPU vs bandwidth when an upstream HTTP/3 connection multiplexes multiple downstream connections. bool disable_qpack = 7; + + // Disables connection level flow control for HTTP/3 streams. This is useful in situations where the streams share the same connection + // but originate from different end-clients, so that each stream can make progress independently at non-front-line proxies. + bool disable_connection_flow_control_for_streams = 8; } // A message to control transformations to the :scheme header diff --git a/api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto b/api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto index 564e76cb1..a530db3de 100644 --- a/api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto +++ b/api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.config.core.v3; +import "envoy/config/core/v3/substitution_format_string.proto"; + import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -37,8 +39,27 @@ message TlvEntry { // The type of the TLV. Must be a uint8 (0-255) as per the Proxy Protocol v2 specification. uint32 type = 1 [(validate.rules).uint32 = {lt: 256}]; - // The value of the TLV. Must be at least one byte long. - bytes value = 2 [(validate.rules).bytes = {min_len: 1}]; + // The static value of the TLV. + // Only one of ``value`` or ``format_string`` may be set. + bytes value = 2; + + // Uses the :ref:`format string ` to dynamically + // populate the TLV value from stream information. This allows dynamic values + // such as metadata, filter state, or other stream properties to be included in + // the TLV. + // + // For example: + // + // .. code-block:: yaml + // + // type: 0xF0 + // format_string: + // text_format_source: + // inline_string: "%DYNAMIC_METADATA(envoy.filters.network:key)%" + // + // The formatted string will be used directly as the TLV value. + // Only one of ``value`` or ``format_string`` may be set. + SubstitutionFormatString format_string = 3; } message ProxyProtocolConfig { diff --git a/api/src/main/proto/envoy/config/endpoint/v3/endpoint.proto b/api/src/main/proto/envoy/config/endpoint/v3/endpoint.proto index 894f68310..a149f6095 100644 --- a/api/src/main/proto/envoy/config/endpoint/v3/endpoint.proto +++ b/api/src/main/proto/envoy/config/endpoint/v3/endpoint.proto @@ -113,8 +113,9 @@ message ClusterLoadAssignment { // to determine the health of the priority level, or in other words assume each host has a weight of 1 for // this calculation. // - // Note: this is not currently implemented for - // :ref:`locality weighted load balancing `. + // .. note:: + // This is not currently implemented for + // :ref:`locality weighted load balancing `. bool weighted_priority_health = 6; } diff --git a/api/src/main/proto/envoy/config/endpoint/v3/load_report.proto b/api/src/main/proto/envoy/config/endpoint/v3/load_report.proto index 32bbfe2d3..6d12765ce 100644 --- a/api/src/main/proto/envoy/config/endpoint/v3/load_report.proto +++ b/api/src/main/proto/envoy/config/endpoint/v3/load_report.proto @@ -38,7 +38,8 @@ message UpstreamLocalityStats { // locality. uint64 total_successful_requests = 2; - // The total number of unfinished requests + // The total number of unfinished requests. A request can be an HTTP request + // or a TCP connection for a TCP connection pool. uint64 total_requests_in_progress = 3; // The total number of requests that failed due to errors at the endpoint, @@ -47,7 +48,8 @@ message UpstreamLocalityStats { // The total number of requests that were issued by this Envoy since // the last report. This information is aggregated over all the - // upstream endpoints in the locality. + // upstream endpoints in the locality. A request can be an HTTP request + // or a TCP connection for a TCP connection pool. uint64 total_issued_requests = 8; // The total number of connections in an established state at the time of the diff --git a/api/src/main/proto/envoy/config/grpc_credential/v3/aws_iam.proto b/api/src/main/proto/envoy/config/grpc_credential/v3/aws_iam.proto deleted file mode 100644 index 5137602d9..000000000 --- a/api/src/main/proto/envoy/config/grpc_credential/v3/aws_iam.proto +++ /dev/null @@ -1,46 +0,0 @@ -syntax = "proto3"; - -package envoy.config.grpc_credential.v3; - -import "envoy/annotations/deprecation.proto"; -import "udpa/annotations/status.proto"; -import "udpa/annotations/versioning.proto"; -import "validate/validate.proto"; - -option java_package = "io.envoyproxy.envoy.config.grpc_credential.v3"; -option java_outer_classname = "AwsIamProto"; -option java_multiple_files = true; -option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/grpc_credential/v3;grpc_credentialv3"; -option (udpa.annotations.file_status).package_version_status = ACTIVE; - -// [#protodoc-title: Grpc Credentials AWS IAM] -// Configuration for AWS IAM Grpc Credentials Plugin -// .. warning:: -// -// This extension is deprecated and will be deleted in a future Envoy release, no -// later than Envoy 1.35, but possibly sooner. -// -// [#extension: envoy.grpc_credentials.aws_iam] - -message AwsIamConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.config.grpc_credential.v2alpha.AwsIamConfig"; - - // The `service namespace - // `_ - // of the Grpc endpoint. - // - // Example: appmesh - string service_name = 1 [ - deprecated = true, - (validate.rules).string = {min_len: 1}, - (envoy.annotations.deprecated_at_minor_version) = "3.0" - ]; - - // The `region `_ hosting the Grpc - // endpoint. If unspecified, the extension will use the value in the ``AWS_REGION`` environment - // variable. - // - // Example: us-west-2 - string region = 2 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; -} diff --git a/api/src/main/proto/envoy/config/listener/v3/listener.proto b/api/src/main/proto/envoy/config/listener/v3/listener.proto index 4bcd3882c..ff2f79d11 100644 --- a/api/src/main/proto/envoy/config/listener/v3/listener.proto +++ b/api/src/main/proto/envoy/config/listener/v3/listener.proto @@ -5,6 +5,7 @@ package envoy.config.listener.v3; import "envoy/config/accesslog/v3/accesslog.proto"; import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/base.proto"; +import "envoy/config/core/v3/config_source.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/socket_option.proto"; import "envoy/config/listener/v3/api_listener.proto"; @@ -53,7 +54,7 @@ message ListenerCollection { repeated xds.core.v3.CollectionEntry entries = 1; } -// [#next-free-field: 36] +// [#next-free-field: 37] message Listener { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener"; @@ -115,6 +116,20 @@ message Listener { message InternalListenerConfig { } + // Configuration for filter chains discovery. + // [#not-implemented-hide:] + message FcdsConfig { + // Optional name to present to the filter chain discovery service. This may be an arbitrary name with arbitrary + // length. If a name is not provided, the listener's name is used. Refer to :ref:`filter_chains `. + // for details on how listener name is determined if unspecified. In addition, this may be a xdstp:// URL. + string name = 1; + + // Configuration for the source of FCDS updates for this listener. + // .. note:: + // This discovery service only supports ``AGGREGATED_GRPC`` API type. + core.v3.ConfigSource config_source = 2; + } + reserved 14, 23; // The unique name by which this listener is known. If no name is provided, @@ -147,6 +162,12 @@ message Listener { // :ref:`FAQ entry `. repeated FilterChain filter_chains = 3; + // Discover filter chains configurations by external service. Dynamic discovery of filter chains is allowed + // while having statically configured filter chains, however, a filter chain name must be unique within a + // listener. If a discovered filter chain matches a name of an existing filter chain, it is discarded. + // [#not-implemented-hide:] + FcdsConfig fcds_config = 36; + // :ref:`Matcher API ` resolving the filter chain name from the // network properties. This matcher is used as a replacement for the filter chain match condition // :ref:`filter_chain_match @@ -352,6 +373,11 @@ message Listener { // accepted in later event loop iterations. // If no value is provided Envoy will accept all connections pending accept // from the kernel. + // + // .. note:: + // + // It is recommended to lower this value for better overload management and reduced per-event cost. + // Setting it to 1 is a viable option with no noticeable impact on performance. google.protobuf.UInt32Value max_connections_to_accept_per_socket_event = 34 [(validate.rules).uint32 = {gt: 0}]; diff --git a/api/src/main/proto/envoy/config/listener/v3/listener_components.proto b/api/src/main/proto/envoy/config/listener/v3/listener_components.proto index 33eb349fd..cfa30afbb 100644 --- a/api/src/main/proto/envoy/config/listener/v3/listener_components.proto +++ b/api/src/main/proto/envoy/config/listener/v3/listener_components.proto @@ -233,7 +233,7 @@ message FilterChain { google.protobuf.BoolValue use_proxy_proto = 4 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // [#not-implemented-hide:] filter chain metadata. + // Filter chain metadata. core.v3.Metadata metadata = 5; // Optional custom transport socket implementation to use for downstream connections. diff --git a/api/src/main/proto/envoy/config/metrics/v3/stats.proto b/api/src/main/proto/envoy/config/metrics/v3/stats.proto index e7d7f80d6..02bb23aec 100644 --- a/api/src/main/proto/envoy/config/metrics/v3/stats.proto +++ b/api/src/main/proto/envoy/config/metrics/v3/stats.proto @@ -298,10 +298,12 @@ message HistogramBucketSettings { // Each value is the upper bound of a bucket. Each bucket must be greater than 0 and unique. // The order of the buckets does not matter. repeated double buckets = 2 [(validate.rules).repeated = { - min_items: 1 unique: true items {double {gt: 0.0}} }]; + + // Initial number of bins for the ``circllhist`` thread local histogram per time series. Default value is 100. + google.protobuf.UInt32Value bins = 3 [(validate.rules).uint32 = {lte: 46082 gt: 0}]; } // Stats configuration proto schema for built-in ``envoy.stat_sinks.statsd`` sink. This sink does not support diff --git a/api/src/main/proto/envoy/config/overload/v3/overload.proto b/api/src/main/proto/envoy/config/overload/v3/overload.proto index 1f267c186..b5bc2c4d8 100644 --- a/api/src/main/proto/envoy/config/overload/v3/overload.proto +++ b/api/src/main/proto/envoy/config/overload/v3/overload.proto @@ -109,6 +109,13 @@ message ScaleTimersOverloadActionConfig { // :ref:`HttpConnectionManager.common_http_protocol_options.max_connection_duration // `. HTTP_DOWNSTREAM_CONNECTION_MAX = 4; + + // Adjusts the timeout for the downstream codec to flush an ended stream. + // This affects the value of :ref:`RouteAction.flush_timeout + // ` and + // :ref:`HttpConnectionManager.stream_flush_timeout + // ` + HTTP_DOWNSTREAM_STREAM_FLUSH = 5; } message ScaleTimer { @@ -134,9 +141,16 @@ message OverloadAction { option (udpa.annotations.versioning).previous_message_type = "envoy.config.overload.v2alpha.OverloadAction"; - // The name of the overload action. This is just a well-known string that listeners can - // use for registering callbacks. Custom overload actions should be named using reverse - // DNS to ensure uniqueness. + // The name of the overload action. This is just a well-known string that + // listeners can use for registering callbacks. + // Valid known overload actions include: + // - envoy.overload_actions.stop_accepting_requests + // - envoy.overload_actions.disable_http_keepalive + // - envoy.overload_actions.stop_accepting_connections + // - envoy.overload_actions.reject_incoming_connections + // - envoy.overload_actions.shrink_heap + // - envoy.overload_actions.reduce_timeouts + // - envoy.overload_actions.reset_high_memory_stream string name = 1 [(validate.rules).string = {min_len: 1}]; // A set of triggers for this action. The state of the action is the maximum @@ -148,7 +162,7 @@ message OverloadAction { // in this list. repeated Trigger triggers = 2 [(validate.rules).repeated = {min_items: 1}]; - // Configuration for the action being instantiated. + // Configuration for the action being instantiated if applicable. google.protobuf.Any typed_config = 3; } diff --git a/api/src/main/proto/envoy/config/rbac/v3/rbac.proto b/api/src/main/proto/envoy/config/rbac/v3/rbac.proto index 0f17788ea..cdb1267a2 100644 --- a/api/src/main/proto/envoy/config/rbac/v3/rbac.proto +++ b/api/src/main/proto/envoy/config/rbac/v3/rbac.proto @@ -248,10 +248,14 @@ message Permission { // When any is set, it matches any action. bool any = 3 [(validate.rules).bool = {const: true}]; - // A header (or pseudo-header such as :path or :method) on the incoming HTTP request. Only - // available for HTTP request. - // Note: the pseudo-header :path includes the query and fragment string. Use the ``url_path`` - // field if you want to match the URL path without the query and fragment string. + // A header (or pseudo-header such as ``:path`` or ``:method``) on the incoming HTTP request. Only available + // for HTTP request. + // + // .. note:: + // + // The pseudo-header ``:path`` includes the query and fragment string. Use the ``url_path`` field if you + // want to match the URL path without the query and fragment string. + // route.v3.HeaderMatcher header = 4; // A URL path on the incoming HTTP request. Only available for HTTP. @@ -276,8 +280,7 @@ message Permission { // the value of ``not_rule`` would not match, this permission would match. Permission not_rule = 8; - // The request server from the client's connection request. This is - // typically TLS SNI. + // The request server from the client's connection request. This is typically TLS SNI. // // .. attention:: // @@ -294,8 +297,7 @@ message Permission { // * A :ref:`listener filter ` may // overwrite a connection's requested server name within Envoy. // - // Please refer to :ref:`this FAQ entry ` to learn to - // setup SNI. + // Please refer to :ref:`this FAQ entry ` to learn how to setup SNI. type.matcher.v3.StringMatcher requested_server_name = 9; // Extension for configuring custom matchers for RBAC. @@ -351,12 +353,10 @@ message Principal { oneof identifier { option (validate.required) = true; - // A set of identifiers that all must match in order to define the - // downstream. + // A set of identifiers that all must match in order to define the downstream. Set and_ids = 1; - // A set of identifiers at least one must match in order to define the - // downstream. + // A set of identifiers at least one must match in order to define the downstream. Set or_ids = 2; // When any is set, it matches any downstream. @@ -380,24 +380,33 @@ message Principal { [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // A CIDR block that describes the downstream remote/origin address. - // Note: This is always the physical peer even if the - // :ref:`remote_ip ` is - // inferred from for example the x-forwarder-for header, proxy protocol, - // etc. + // + // .. note:: + // + // This is always the physical peer even if the + // :ref:`remote_ip ` is inferred from the + // x-forwarder-for header, the proxy protocol, etc. + // core.v3.CidrRange direct_remote_ip = 10; // A CIDR block that describes the downstream remote/origin address. - // Note: This may not be the physical peer and could be different from the - // :ref:`direct_remote_ip - // `. E.g, if the - // remote ip is inferred from for example the x-forwarder-for header, proxy - // protocol, etc. + // + // .. note:: + // + // This may not be the physical peer and could be different from the :ref:`direct_remote_ip + // `. E.g, if the remote ip is inferred from + // the x-forwarder-for header, the proxy protocol, etc. + // core.v3.CidrRange remote_ip = 11; - // A header (or pseudo-header such as :path or :method) on the incoming HTTP - // request. Only available for HTTP request. Note: the pseudo-header :path - // includes the query and fragment string. Use the ``url_path`` field if you - // want to match the URL path without the query and fragment string. + // A header (or pseudo-header such as ``:path`` or ``:method``) on the incoming HTTP request. Only available + // for HTTP request. + // + // .. note:: + // + // The pseudo-header ``:path`` includes the query and fragment string. Use the ``url_path`` field if you + // want to match the URL path without the query and fragment string. + // route.v3.HeaderMatcher header = 6; // A URL path on the incoming HTTP request. Only available for HTTP. @@ -434,7 +443,7 @@ message Action { // The action to take if the matcher matches. Every action either allows or denies a request, // and can also carry out action-specific operations. // - // Actions: + // **Actions:** // // * ``ALLOW``: If the request gets matched on ALLOW, it is permitted. // * ``DENY``: If the request gets matched on DENY, it is not permitted. @@ -443,7 +452,7 @@ message Action { // ``envoy.common`` will be set to the value ``true``. // * If the request cannot get matched, it will fallback to ``DENY``. // - // Log behavior: + // **Log behavior:** // // If the RBAC matcher contains at least one LOG action, the dynamic // metadata key ``access_log_hint`` will be set based on if the request diff --git a/api/src/main/proto/envoy/config/route/v3/route_components.proto b/api/src/main/proto/envoy/config/route/v3/route_components.proto index b12d51034..7364a9625 100644 --- a/api/src/main/proto/envoy/config/route/v3/route_components.proto +++ b/api/src/main/proto/envoy/config/route/v3/route_components.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.config.route.v3; +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"; @@ -41,7 +42,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // host header. This allows a single listener to service multiple top level domain path trees. Once // a virtual host is selected based on the domain, the routes are processed in order to see which // upstream cluster to route to or whether to perform a redirect. -// [#next-free-field: 25] +// [#next-free-field: 26] message VirtualHost { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualHost"; @@ -78,7 +79,7 @@ message VirtualHost { // .. note:: // // The wildcard will not match the empty string. - // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. + // For example, ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. // The longest wildcards match first. // Only a single virtual host in the entire route configuration can match on ``*``. A domain // must be unique across all virtual hosts or the config will fail to load. @@ -155,7 +156,7 @@ message VirtualHost { // This field can be used to provide virtual host level per filter config. The key should match the // :ref:`filter config name // `. - // See :ref:`Http filter route specific config ` + // See :ref:`HTTP filter route-specific config ` // for details. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` @@ -166,7 +167,10 @@ message VirtualHost { // ` header should be included // in the upstream request. Setting this option will cause it to override any existing header // value, so in the case of two Envoys on the request path with this option enabled, the upstream - // will see the attempt count as perceived by the second Envoy. Defaults to false. + // will see the attempt count as perceived by the second Envoy. + // + // Defaults to ``false``. + // // This header is unaffected by the // :ref:`suppress_envoy_headers // ` flag. @@ -178,7 +182,10 @@ message VirtualHost { // ` header should be included // in the downstream response. Setting this option will cause the router to override any existing header // value, so in the case of two Envoys on the request path with this option enabled, the downstream - // will see the attempt count as perceived by the Envoy closest upstream from itself. Defaults to false. + // will see the attempt count as perceived by the Envoy closest upstream from itself. + // + // Defaults to ``false``. + // // This header is unaffected by the // :ref:`suppress_envoy_headers // ` flag. @@ -186,29 +193,56 @@ message VirtualHost { // Indicates the retry policy for all routes in this virtual host. Note that setting a // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). + // independently (e.g., values are not inherited). RetryPolicy retry_policy = 16; // [#not-implemented-hide:] // Specifies the configuration for retry policy extension. Note that setting a route level entry - // will take precedence over this config and it'll be treated independently (e.g.: values are not + // will take precedence over this config and it'll be treated independently (e.g., values are not // inherited). :ref:`Retry policy ` should not be // set if this field is used. google.protobuf.Any retry_policy_typed_config = 20; // Indicates the hedge policy for all routes in this virtual host. Note that setting a // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). + // independently (e.g., values are not inherited). HedgePolicy hedge_policy = 17; // Decides whether to include the :ref:`x-envoy-is-timeout-retry ` - // request header in retries initiated by per try timeouts. + // request header in retries initiated by per-try timeouts. bool include_is_timeout_retry_header = 23; - // The maximum bytes which will be buffered for retries and shadowing. - // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum - // value of this and the listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18; + // The maximum bytes which will be buffered for retries and shadowing. If set, the bytes actually buffered will be + // the minimum value of this and the listener ``per_connection_buffer_limit_bytes``. + // + // .. attention:: + // + // This field has been deprecated. Please use :ref:`request_body_buffer_limit + // ` instead. + // Only one of ``per_request_buffer_limit_bytes`` and ``request_body_buffer_limit`` could be set. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; + + // The maximum bytes which will be buffered for request bodies to support large request body + // buffering beyond the ``per_connection_buffer_limit_bytes``. + // + // This limit is specifically for the request body buffering and allows buffering larger payloads while maintaining + // flow control. + // + // Buffer limit precedence (from highest to lowest priority): + // + // 1. If ``request_body_buffer_limit`` is set, then ``request_body_buffer_limit`` will be used. + // 2. If :ref:`per_request_buffer_limit_bytes ` + // is set but ``request_body_buffer_limit`` is not, then ``min(per_request_buffer_limit_bytes, per_connection_buffer_limit_bytes)`` + // will be used. + // 3. If neither is set, then ``per_connection_buffer_limit_bytes`` will be used. + // + // For flow control chunk sizes, ``min(per_connection_buffer_limit_bytes, 16KB)`` will be used. + // + // Only one of :ref:`per_request_buffer_limit_bytes ` + // and ``request_body_buffer_limit`` could be set. + google.protobuf.UInt64Value request_body_buffer_limit = 25 + [(validate.rules).message = {required: false}]; // Specify a set of default request mirroring policies for every route under this virtual host. // It takes precedence over the route config mirror policy entirely. @@ -244,7 +278,7 @@ message RouteList { // // Envoy supports routing on HTTP method via :ref:`header matching // `. -// [#next-free-field: 20] +// [#next-free-field: 21] message Route { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Route"; @@ -297,7 +331,7 @@ message Route { // This field can be used to provide route specific per filter config. The key should match the // :ref:`filter config name // `. - // See :ref:`Http filter route specific config ` + // See :ref:`HTTP filter route-specific config ` // for details. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` @@ -341,7 +375,14 @@ message Route { // The maximum bytes which will be buffered for retries and shadowing. // If set, the bytes actually buffered will be the minimum value of this and the // listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; + // + // .. attention:: + // + // This field has been deprecated. Please use :ref:`request_body_buffer_limit + // ` instead. + // Only one of ``per_request_buffer_limit_bytes`` and ``request_body_buffer_limit`` may be set. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // The human readable prefix to use when emitting statistics for this endpoint. // The statistics are rooted at vhost..route.. @@ -355,8 +396,27 @@ message Route { // // We do not recommend setting up a stat prefix for // every application endpoint. This is both not easily maintainable and - // statistics use a non-trivial amount of memory(approximately 1KiB per route). + // statistics use a non-trivial amount of memory (approximately 1KiB per route). string stat_prefix = 19; + + // The maximum bytes which will be buffered for request bodies to support large request body + // buffering beyond the ``per_connection_buffer_limit_bytes``. + // + // This limit is specifically for the request body buffering and allows buffering larger payloads while maintaining + // flow control. + // + // Buffer limit precedence (from highest to lowest priority): + // + // 1. If ``request_body_buffer_limit`` is set: use ``request_body_buffer_limit`` + // 2. If :ref:`per_request_buffer_limit_bytes ` + // is set but ``request_body_buffer_limit`` is not: use ``min(per_request_buffer_limit_bytes, per_connection_buffer_limit_bytes)`` + // 3. If neither is set: use ``per_connection_buffer_limit_bytes`` + // + // For flow control chunk sizes, use ``min(per_connection_buffer_limit_bytes, 16KB)``. + // + // Only one of :ref:`per_request_buffer_limit_bytes ` + // and ``request_body_buffer_limit`` may be set. + google.protobuf.UInt64Value request_body_buffer_limit = 20; } // Compared to the :ref:`cluster ` field that specifies a @@ -365,6 +425,7 @@ message Route { // multiple upstream clusters along with weights that indicate the percentage of // traffic to be forwarded to each cluster. The router selects an upstream cluster based on the // weights. +// [#next-free-field: 6] message WeightedCluster { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.WeightedCluster"; @@ -452,7 +513,7 @@ message WeightedCluster { // This field can be used to provide weighted cluster specific per filter config. The key should match the // :ref:`filter config name // `. - // See :ref:`Http filter route specific config ` + // See :ref:`HTTP filter route-specific config ` // for details. // [#comment: An entry's value may be wrapped in a // :ref:`FilterConfig` @@ -495,12 +556,18 @@ message WeightedCluster { // the process for the consistency. And the value is a unsigned number between 0 and UINT64_MAX. string header_name = 4 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}]; + + // When set to true, the hash policies will be used to generate the random value for weighted cluster selection. + // This could ensure consistent cluster picking across multiple proxy levels for weighted traffic. + google.protobuf.BoolValue use_hash_policy = 5; } } // Configuration for a cluster specifier plugin. message ClusterSpecifierPlugin { // The name of the plugin and its opaque configuration. + // + // [#extension-category: envoy.router.cluster_specifier_plugin] core.v3.TypedExtensionConfig extension = 1 [(validate.rules).message = {required: true}]; // If is_optional is not set or is set to false and the plugin defined by this message is not a @@ -569,7 +636,7 @@ message RouteMatch { // // [#next-major-version: In the v3 API we should redo how path specification works such // that we utilize StringMatcher, and additionally have consistent options around whether we - // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive + // strip query strings, do a case-sensitive match, etc. In the interim it will be too disruptive // to deprecate the existing options. We should even consider whether we want to do away with // path_specifier entirely and just rely on a set of header matchers which can already match // on :path, etc. The issue with that is it is unclear how to generically deal with query string @@ -601,7 +668,7 @@ message RouteMatch { core.v3.TypedExtensionConfig path_match_policy = 15; } - // Indicates that prefix/path matching should be case sensitive. The default + // Indicates that prefix/path matching should be case-sensitive. The default // is true. Ignored for safe_regex matching. google.protobuf.BoolValue case_sensitive = 4; @@ -641,14 +708,14 @@ message RouteMatch { // // If query parameters are used to pass request message fields when // `grpc_json_transcoder `_ - // is used, the transcoded message fields maybe different. The query parameters are - // url encoded, but the message fields are not. For example, if a query + // is used, the transcoded message fields may be different. The query parameters are + // URL-encoded, but the message fields are not. For example, if a query // parameter is "foo%20bar", the message field will be "foo bar". repeated QueryParameterMatcher query_parameters = 7; // If specified, only gRPC requests will be matched. The router will check - // that the content-type header has a application/grpc or one of the various - // application/grpc+ values. + // that the ``Content-Type`` header has ``application/grpc`` or one of the various + // ``application/grpc+`` values. GrpcRouteMatchOptions grpc = 8; // If specified, the client tls context will be matched against the defined @@ -734,11 +801,11 @@ message CorsPolicy { google.protobuf.BoolValue allow_private_network_access = 12; // Specifies if preflight requests not matching the configured allowed origin should be forwarded - // to the upstream. Default is true. + // to the upstream. Default is ``true``. google.protobuf.BoolValue forward_not_matching_preflights = 13; } -// [#next-free-field: 42] +// [#next-free-field: 43] message RouteAction { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction"; @@ -777,8 +844,8 @@ message RouteAction { // // .. note:: // - // Shadowing doesn't support Http CONNECT and upgrades. - // [#next-free-field: 7] + // Shadowing doesn't support HTTP CONNECT and upgrades. + // [#next-free-field: 9] message RequestMirrorPolicy { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction.RequestMirrorPolicy"; @@ -828,8 +895,24 @@ message RouteAction { // is disabled. google.protobuf.BoolValue trace_sampled = 4; - // Disables appending the ``-shadow`` suffix to the shadowed ``Host`` header. Defaults to ``false``. + // Disables appending the ``-shadow`` suffix to the shadowed ``Host`` header. + // + // Defaults to ``false``. bool disable_shadow_host_suffix_append = 6; + + // Specifies a list of header mutations that should be applied to each mirrored request. + // Header mutations are applied in the order they are specified. For more information, including + // details on header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated common.mutation_rules.v3.HeaderMutation request_headers_mutations = 7 + [(validate.rules).repeated = {max_items: 1000}]; + + // Indicates that during mirroring, the host header will be swapped with this value. + // :ref:`disable_shadow_host_suffix_append + // ` + // is implicitly enabled if this field is set. + string host_rewrite_literal = 8 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; } // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer @@ -991,13 +1074,15 @@ message RouteAction { bool allow_post = 2; } - // The case-insensitive name of this upgrade, e.g. "websocket". + // The case-insensitive name of this upgrade, for example, "websocket". // For each upgrade type present in upgrade_configs, requests with // Upgrade: [upgrade_type] will be proxied upstream. string upgrade_type = 1 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_VALUE strict: false}]; - // Determines if upgrades are available on this route. Defaults to true. + // Determines if upgrades are available on this route. + // + // Defaults to ``true``. google.protobuf.BoolValue enabled = 2; // Configuration for sending data upstream as a raw data payload. This is used for @@ -1159,12 +1244,21 @@ message RouteAction { // [#extension-category: envoy.path.rewrite] core.v3.TypedExtensionConfig path_rewrite_policy = 41; + // If one of the host rewrite specifiers is set and the + // :ref:`suppress_envoy_headers + // ` flag is not + // set to true, the router filter will place the original host header value before + // rewriting into the :ref:`x-envoy-original-host + // ` header. + // + // And if the + // :ref:`append_x_forwarded_host ` + // is set to true, the original host value will also be appended to the + // :ref:`config_http_conn_man_headers_x-forwarded-host` header. + // oneof host_rewrite_specifier { // Indicates that during forwarding, the host header will be swapped with - // this value. Using this option will append the - // :ref:`config_http_conn_man_headers_x-forwarded-host` header if - // :ref:`append_x_forwarded_host ` - // is set. + // this value. string host_rewrite_literal = 6 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; @@ -1174,18 +1268,12 @@ message RouteAction { // type ``strict_dns`` or ``logical_dns``, // or when :ref:`hostname ` // field is not empty. Setting this to true with other cluster types - // has no effect. Using this option will append the - // :ref:`config_http_conn_man_headers_x-forwarded-host` header if - // :ref:`append_x_forwarded_host ` - // is set. + // has no effect. google.protobuf.BoolValue auto_host_rewrite = 7; // Indicates that during forwarding, the host header will be swapped with the content of given // downstream or :ref:`custom ` header. - // If header value is empty, host header is left intact. Using this option will append the - // :ref:`config_http_conn_man_headers_x-forwarded-host` header if - // :ref:`append_x_forwarded_host ` - // is set. + // If header value is empty, host header is left intact. // // .. attention:: // @@ -1201,10 +1289,6 @@ message RouteAction { // Indicates that during forwarding, the host header will be swapped with // the result of the regex substitution executed on path value with query and fragment removed. // This is useful for transitioning variable content between path segment and subdomain. - // Using this option will append the - // :ref:`config_http_conn_man_headers_x-forwarded-host` header if - // :ref:`append_x_forwarded_host ` - // is set. // // For example with the following config: // @@ -1264,8 +1348,28 @@ message RouteAction { // If the :ref:`overload action ` "envoy.overload_actions.reduce_timeouts" // is configured, this timeout is scaled according to the value for // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE `. + // + // This timeout may also be used in place of ``flush_timeout`` in very specific cases. See the + // documentation for ``flush_timeout`` for more details. google.protobuf.Duration idle_timeout = 24; + // Specifies the codec stream flush timeout for the route. + // + // If not specified, the first preference is the global :ref:`stream_flush_timeout + // `, + // but only if explicitly configured. + // + // If neither the explicit HCM-wide flush timeout nor this route-specific flush timeout is configured, + // the route's stream idle timeout is reused for this timeout. This is for + // backwards compatibility since both behaviors were historically controlled by the one timeout. + // + // If the route also does not have an idle timeout configured, the global :ref:`stream_idle_timeout + // `. used, again + // for backwards compatibility. That timeout defaults to 5 minutes. + // + // A value of 0 via any of the above paths will completely disable the timeout for a given route. + google.protobuf.Duration flush_timeout = 42; + // Specifies how to send request over TLS early data. // If absent, allows `safe HTTP requests `_ to be sent on early data. // [#extension-category: envoy.route.early_data_policy] @@ -1273,13 +1377,13 @@ message RouteAction { // Indicates that the route has a retry policy. Note that if this is set, // it'll take precedence over the virtual host level retry policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). + // (e.g., policies are not merged, the most internal one becomes the enforced policy). RetryPolicy retry_policy = 9; // [#not-implemented-hide:] // Specifies the configuration for retry policy extension. Note that if this is set, it'll take - // precedence over the virtual host level retry policy entirely (e.g.: policies are not merged, - // most internal one becomes the enforced policy). :ref:`Retry policy ` + // precedence over the virtual host level retry policy entirely (e.g., policies are not merged, + // the most internal one becomes the enforced policy). :ref:`Retry policy ` // should not be set if this field is used. google.protobuf.Any retry_policy_typed_config = 33; @@ -1300,7 +1404,9 @@ message RouteAction { // :ref:`rate_limits ` are not applied to the // request. // - // This field is deprecated. Please use :ref:`vh_rate_limits ` + // .. attention:: + // + // This field is deprecated. Please use :ref:`vh_rate_limits ` google.protobuf.BoolValue include_vh_rate_limits = 14 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -1394,7 +1500,7 @@ message RouteAction { // Indicates that the route has a hedge policy. Note that if this is set, // it'll take precedence over the virtual host level hedge policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). + // (e.g., policies are not merged, the most internal one becomes the enforced policy). HedgePolicy hedge_policy = 27; // Specifies the maximum stream duration for this route. @@ -1528,7 +1634,9 @@ message RetryPolicy { // Specifies the maximum back off interval that Envoy will allow. If a reset // header contains an interval longer than this then it will be discarded and - // the next header will be tried. Defaults to 300 seconds. + // the next header will be tried. + // + // Defaults to 300 seconds. google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; } @@ -1557,7 +1665,7 @@ message RetryPolicy { google.protobuf.Duration per_try_timeout = 3; // Specifies an upstream idle timeout per retry attempt (including the initial attempt). This - // parameter is optional and if absent there is no per try idle timeout. The semantics of the per + // parameter is optional and if absent there is no per-try idle timeout. The semantics of the per- // try idle timeout are similar to the // :ref:`route idle timeout ` and // :ref:`stream idle timeout @@ -1632,12 +1740,14 @@ message HedgePolicy { // Specifies the number of initial requests that should be sent upstream. // Must be at least 1. + // // Defaults to 1. // [#not-implemented-hide:] google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}]; // Specifies a probability that an additional upstream request should be sent // on top of what is specified by initial_requests. + // // Defaults to 0. // [#not-implemented-hide:] type.v3.FractionalPercent additional_request_chance = 2; @@ -1647,14 +1757,16 @@ message HedgePolicy { // The first request to complete successfully will be the one returned to the caller. // // * At any time, a successful response (i.e. not triggering any of the retry-on conditions) would be returned to the client. - // * Before per-try timeout, an error response (per retry-on conditions) would be retried immediately or returned ot the client + // * Before per-try timeout, an error response (per retry-on conditions) would be retried immediately or returned to the client // if there are no more retries left. // * After per-try timeout, an error response would be discarded, as a retry in the form of a hedged request is already in progress. // - // Note: For this to have effect, you must have a :ref:`RetryPolicy ` that retries at least - // one error code and specifies a maximum number of retries. + // .. note:: + // + // For this to have effect, you must have a :ref:`RetryPolicy ` that retries at least + // one error code and specifies a maximum number of retries. // - // Defaults to false. + // Defaults to ``false``. bool hedge_on_per_try_timeout = 3; } @@ -1800,7 +1912,7 @@ message Decorator { // ` header. string operation = 1 [(validate.rules).string = {min_len: 1}]; - // Whether the decorated details should be propagated to the other party. The default is true. + // Whether the decorated details should be propagated to the other party. The default is ``true``. google.protobuf.BoolValue propagate = 2; } @@ -1965,7 +2077,7 @@ message RateLimit { // the value of the descriptor entry for the descriptor_key. string query_parameter_name = 1 [(validate.rules).string = {min_len: 1}]; - // The key to use when creating the rate limit descriptor entry. his descriptor key will be used to identify the + // The key to use when creating the rate limit descriptor entry. This descriptor key will be used to identify the // rate limit rule in the rate limiting service. string descriptor_key = 2 [(validate.rules).string = {min_len: 1}]; @@ -2003,14 +2115,18 @@ message RateLimit { // ("masked_remote_address", "") message MaskedRemoteAddress { // Length of prefix mask len for IPv4 (e.g. 0, 32). + // // Defaults to 32 when unset. + // // For example, trusted address from x-forwarded-for is ``192.168.1.1``, // the descriptor entry is ("masked_remote_address", "192.168.1.1/32"); // if mask len is 24, the descriptor entry is ("masked_remote_address", "192.168.1.0/24"). google.protobuf.UInt32Value v4_prefix_mask_len = 1 [(validate.rules).uint32 = {lte: 32}]; // Length of prefix mask len for IPv6 (e.g. 0, 128). + // // Defaults to 128 when unset. + // // For example, trusted address from x-forwarded-for is ``2001:abcd:ef01:2345:6789:abcd:ef01:234``, // the descriptor entry is ("masked_remote_address", "2001:abcd:ef01:2345:6789:abcd:ef01:234/128"); // if mask len is 64, the descriptor entry is ("masked_remote_address", "2001:abcd:ef01:2345::/64"). @@ -2043,7 +2159,9 @@ message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch"; - // The key to use in the descriptor entry. Defaults to ``header_match``. + // The key to use in the descriptor entry. + // + // Defaults to ``header_match``. string descriptor_key = 4; // The value to use in the descriptor entry. @@ -2137,7 +2255,9 @@ message RateLimit { // // ("query_match", "") message QueryParameterValueMatch { - // The key to use in the descriptor entry. Defaults to ``query_match``. + // The key to use in the descriptor entry. + // + // Defaults to ``query_match``. string descriptor_key = 4; // The value to use in the descriptor entry. @@ -2367,14 +2487,20 @@ message HeaderMatcher { // Specifies how the header match will be performed to route the request. oneof header_match_specifier { // If specified, header match will be performed based on the value of the header. - // This field is deprecated. Please use :ref:`string_match `. + // + // .. attention:: + // + // This field is deprecated. Please use :ref:`string_match `. string exact_match = 4 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // If specified, this regex string is a regular expression rule which implies the entire request // header value must match the regex. The rule will not match if only a subsequence of the // request header value matches the regex. - // This field is deprecated. Please use :ref:`string_match `. + // + // .. attention:: + // + // This field is deprecated. Please use :ref:`string_match `. type.matcher.v3.RegexMatcher safe_regex_match = 11 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -2396,8 +2522,14 @@ message HeaderMatcher { bool present_match = 7; // If specified, header match will be performed based on the prefix of the header value. - // Note: empty prefix is not allowed, please use present_match instead. - // This field is deprecated. Please use :ref:`string_match `. + // + // .. note:: + // + // Empty prefix is not allowed. Please use ``present_match`` instead. + // + // .. attention:: + // + // This field is deprecated. Please use :ref:`string_match `. // // Examples: // @@ -2409,8 +2541,14 @@ message HeaderMatcher { ]; // If specified, header match will be performed based on the suffix of the header value. - // Note: empty suffix is not allowed, please use present_match instead. - // This field is deprecated. Please use :ref:`string_match `. + // + // .. note:: + // + // Empty suffix is not allowed. Please use ``present_match`` instead. + // + // .. attention:: + // + // This field is deprecated. Please use :ref:`string_match `. // // Examples: // @@ -2423,8 +2561,14 @@ message HeaderMatcher { // If specified, header match will be performed based on whether the header value contains // the given value or not. - // Note: empty contains match is not allowed, please use present_match instead. - // This field is deprecated. Please use :ref:`string_match `. + // + // .. note:: + // + // Empty contains match is not allowed. Please use ``present_match`` instead. + // + // .. attention:: + // + // This field is deprecated. Please use :ref:`string_match `. // // Examples: // @@ -2439,7 +2583,9 @@ message HeaderMatcher { type.matcher.v3.StringMatcher string_match = 13; } - // If specified, the match result will be inverted before checking. Defaults to false. + // If specified, the match result will be inverted before checking. + // + // Defaults to ``false``. // // Examples: // @@ -2448,7 +2594,9 @@ message HeaderMatcher { bool invert_match = 8; // If specified, for any header match rule, if the header match rule specified header - // does not exist, this header value will be treated as empty. Defaults to false. + // does not exist, this header value will be treated as empty. + // + // Defaults to ``false``. // // Examples: // @@ -2525,7 +2673,7 @@ message InternalRedirectPolicy { repeated core.v3.TypedExtensionConfig predicates = 3; // Allow internal redirect to follow a target URI with a different scheme than the value of - // x-forwarded-proto. The default is false. + // x-forwarded-proto. The default is ``false``. bool allow_cross_scheme_redirect = 4; // Specifies a list of headers, by name, to copy from the internal redirect into the subsequent diff --git a/api/src/main/proto/envoy/config/tap/v3/common.proto b/api/src/main/proto/envoy/config/tap/v3/common.proto index 126993d0f..ecdb5faaa 100644 --- a/api/src/main/proto/envoy/config/tap/v3/common.proto +++ b/api/src/main/proto/envoy/config/tap/v3/common.proto @@ -154,6 +154,7 @@ message HttpGenericBodyMatch { } // Tap output configuration. +// [#next-free-field: 6] message OutputConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.service.tap.v2alpha.OutputConfig"; @@ -181,6 +182,12 @@ message OutputConfig { // match can be determined. See the HTTP tap filter :ref:`streaming // ` documentation for more information. bool streaming = 4; + + // Tapped messages will be sent on each read/write event for streamed tapping by default. + // But this behavior could be controlled by setting this field. + // If set then the tapped messages will be send once the threshold is reached. + // This could be used to avoid high frequent sending. + google.protobuf.UInt32Value min_streamed_sent_bytes = 5; } // Tap output sink configuration. diff --git a/api/src/main/proto/envoy/config/trace/v3/opentelemetry.proto b/api/src/main/proto/envoy/config/trace/v3/opentelemetry.proto index 59028326f..5260d9bd6 100644 --- a/api/src/main/proto/envoy/config/trace/v3/opentelemetry.proto +++ b/api/src/main/proto/envoy/config/trace/v3/opentelemetry.proto @@ -6,6 +6,8 @@ import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/grpc_service.proto"; import "envoy/config/core/v3/http_service.proto"; +import "google/protobuf/wrappers.proto"; + import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; @@ -19,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the OpenTelemetry tracer. // [#extension: envoy.tracers.opentelemetry] -// [#next-free-field: 6] +// [#next-free-field: 7] message OpenTelemetryConfig { // The upstream gRPC cluster that will receive OTLP traces. // Note that the tracer drops traces if the server does not read data fast enough. @@ -57,4 +59,9 @@ message OpenTelemetryConfig { // See: `OpenTelemetry sampler specification `_ // [#extension-category: envoy.tracers.opentelemetry.samplers] core.v3.TypedExtensionConfig sampler = 5; + + // Envoy caches the span in memory when the OpenTelemetry backend service is temporarily unavailable. + // This field specifies the maximum number of spans that can be cached. If not specified, the + // default is 1024. + google.protobuf.UInt32Value max_cache_size = 6; } diff --git a/api/src/main/proto/envoy/config/trace/v3/zipkin.proto b/api/src/main/proto/envoy/config/trace/v3/zipkin.proto index 2d8f3195c..7405c596e 100644 --- a/api/src/main/proto/envoy/config/trace/v3/zipkin.proto +++ b/api/src/main/proto/envoy/config/trace/v3/zipkin.proto @@ -2,13 +2,14 @@ syntax = "proto3"; package envoy.config.trace.v3; +import "envoy/config/core/v3/http_service.proto"; + import "google/protobuf/wrappers.proto"; import "envoy/annotations/deprecation.proto"; import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; -import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.config.trace.v3"; option java_outer_classname = "ZipkinProto"; @@ -21,10 +22,22 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the Zipkin tracer. // [#extension: envoy.tracers.zipkin] -// [#next-free-field: 8] +// [#next-free-field: 10] message ZipkinConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.ZipkinConfig"; + // Available trace context options for handling different trace header formats. + enum TraceContextOption { + // Use B3 headers only (default behavior). + USE_B3 = 0; + + // Enable B3 and W3C dual header support: + // - For downstream: Extract from B3 headers first, fallback to W3C traceparent if B3 is unavailable. + // - For upstream: Inject both B3 and W3C traceparent headers. + // When this option is NOT set, only B3 headers are used for both extraction and injection. + USE_B3_WITH_W3C_PROPAGATION = 1; + } + // Available Zipkin collector endpoint versions. enum CollectorEndpointVersion { // Zipkin API v1, JSON over HTTP. @@ -48,11 +61,17 @@ message ZipkinConfig { } // The cluster manager cluster that hosts the Zipkin collectors. - string collector_cluster = 1 [(validate.rules).string = {min_len: 1}]; + // 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. - string collector_endpoint = 2 [(validate.rules).string = {min_len: 1}]; + // 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 // trace instance. The default value is false, which will result in a 64 bit trace id being used. @@ -67,6 +86,8 @@ 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 `. 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 @@ -88,4 +109,60 @@ message ZipkinConfig { // Please use that ``spawn_upstream_span`` field to control the span creation. bool split_spans_for_request = 7 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; + + // Determines which trace context format to use for trace header extraction and propagation. + // This controls both downstream request header extraction and upstream request header injection. + // Here is the spec for W3C trace headers: https://www.w3.org/TR/trace-context/ + // The default value is USE_B3 to maintain backward compatibility. + TraceContextOption trace_context_option = 8; + + // HTTP service configuration for the Zipkin collector. + // When specified, this configuration takes precedence over the legacy fields: + // collector_cluster, collector_endpoint, and collector_hostname. + // This provides a complete HTTP service configuration including cluster, URI, timeout, and headers. + // If not specified, the legacy fields above will be used for backward compatibility. + // + // Required fields when using collector_service: + // + // * ``http_uri.cluster`` - Must be specified and non-empty + // * ``http_uri.uri`` - Must be specified and non-empty + // * ``http_uri.timeout`` - Optional + // + // Full URI Support with Automatic Parsing: + // + // The ``uri`` field supports both path-only and full URI formats: + // + // .. code-block:: yaml + // + // tracing: + // provider: + // name: envoy.tracers.zipkin + // typed_config: + // "@type": type.googleapis.com/envoy.config.trace.v3.ZipkinConfig + // collector_service: + // http_uri: + // # Full URI format - hostname and path are extracted automatically + // uri: "https://zipkin-collector.example.com/api/v2/spans" + // cluster: zipkin + // timeout: 5s + // request_headers_to_add: + // - header: + // key: "X-Custom-Token" + // value: "your-custom-token" + // - header: + // key: "X-Service-ID" + // value: "your-service-id" + // + // URI Parsing Behavior: + // + // * Full URI: ``"https://zipkin-collector.example.com/api/v2/spans"`` + // + // * Hostname: ``zipkin-collector.example.com`` (sets HTTP ``Host`` header) + // * Path: ``/api/v2/spans`` (sets HTTP request path) + // + // * Path only: ``"/api/v2/spans"`` + // + // * Hostname: Uses cluster name as fallback + // * Path: ``/api/v2/spans`` + core.v3.HttpService collector_service = 9; } diff --git a/api/src/main/proto/envoy/data/core/v3/tlv_metadata.proto b/api/src/main/proto/envoy/data/core/v3/tlv_metadata.proto index 8f99b004e..caa798986 100644 --- a/api/src/main/proto/envoy/data/core/v3/tlv_metadata.proto +++ b/api/src/main/proto/envoy/data/core/v3/tlv_metadata.proto @@ -17,8 +17,7 @@ message TlvsMetadata { // Typed metadata for :ref:`Proxy protocol filter `, that represents a map of TLVs. // Each entry in the map consists of a key which corresponds to a configured // :ref:`rule key ` and a value (TLV value in bytes). - // When runtime flag ``envoy.reloadable_features.use_typed_metadata_in_proxy_protocol_listener`` is enabled, // :ref:`Proxy protocol filter ` - // will populate typed metadata and regular metadata. By default filter will populate typed and untyped metadata. + // populates both typed and untyped metadata. map typed_metadata = 1; } diff --git a/api/src/main/proto/envoy/data/tap/v3/http.proto b/api/src/main/proto/envoy/data/tap/v3/http.proto index 2e5c566e5..42ba44c1d 100644 --- a/api/src/main/proto/envoy/data/tap/v3/http.proto +++ b/api/src/main/proto/envoy/data/tap/v3/http.proto @@ -49,6 +49,9 @@ message HttpBufferedTrace { // downstream connection Connection downstream_connection = 3; + + // upstream connection + Connection upstream_connection = 4; } // A streamed HTTP trace segment. Multiple segments make up a full trace. diff --git a/api/src/main/proto/envoy/data/tap/v3/transport.proto b/api/src/main/proto/envoy/data/tap/v3/transport.proto index a89e15dab..8aef68978 100644 --- a/api/src/main/proto/envoy/data/tap/v3/transport.proto +++ b/api/src/main/proto/envoy/data/tap/v3/transport.proto @@ -96,6 +96,11 @@ message SocketBufferedTrace { bool write_truncated = 5; } +// A message for the sequence of observed events +message SocketEvents { + repeated SocketEvent events = 1; +} + // A streamed socket trace segment. Multiple segments make up a full trace. message SocketStreamedTraceSegment { option (udpa.annotations.versioning).previous_message_type = @@ -111,5 +116,8 @@ message SocketStreamedTraceSegment { // Socket event. SocketEvent event = 3; + + // Sequence of observed events. + SocketEvents events = 4; } } diff --git a/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto b/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto new file mode 100644 index 000000000..fba8cdee8 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3/downstream_reverse_connection_socket_interface.proto @@ -0,0 +1,27 @@ +syntax = "proto3"; + +package envoy.extensions.bootstrap.reverse_tunnel.downstream_socket_interface.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.bootstrap.reverse_tunnel.downstream_socket_interface.v3"; +option java_outer_classname = "DownstreamReverseConnectionSocketInterfaceProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/bootstrap/reverse_tunnel/downstream_socket_interface/v3;downstream_socket_interfacev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Bootstrap settings for downstream reverse connection socket interface] +// [#extension: envoy.bootstrap.reverse_tunnel.downstream_socket_interface] + +// Configuration for the downstream reverse connection socket interface. +// This interface initiates reverse connections to upstream Envoys and provides +// them as socket connections for downstream requests. +message DownstreamReverseConnectionSocketInterface { + // 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. + bool enable_detailed_stats = 2; +} diff --git a/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto b/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto new file mode 100644 index 000000000..2ba83ac88 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3/upstream_reverse_connection_socket_interface.proto @@ -0,0 +1,32 @@ +syntax = "proto3"; + +package envoy.extensions.bootstrap.reverse_tunnel.upstream_socket_interface.v3; + +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.bootstrap.reverse_tunnel.upstream_socket_interface.v3"; +option java_outer_classname = "UpstreamReverseConnectionSocketInterfaceProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/bootstrap/reverse_tunnel/upstream_socket_interface/v3;upstream_socket_interfacev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Upstream reverse connection socket interface] +// [#extension: envoy.bootstrap.reverse_tunnel.upstream_socket_interface] + +// Configuration for the upstream reverse connection socket interface. +message UpstreamReverseConnectionSocketInterface { + // Stat prefix for upstream reverse connection socket interface stats. + string stat_prefix = 1; + + // Number of consecutive ping failures before an idle reverse connection socket is marked dead. + // Defaults to 3 if unset. Must be at least 1. + google.protobuf.UInt32Value ping_failure_threshold = 2 [(validate.rules).uint32 = {gte: 1}]; + + // Enable detailed per-node and per-cluster statistics. + // When enabled, emits hidden statistics for individual nodes and clusters. + // Defaults to false. + bool enable_detailed_stats = 3; +} diff --git a/api/src/main/proto/envoy/extensions/clusters/aggregate/v3/cluster.proto b/api/src/main/proto/envoy/extensions/clusters/aggregate/v3/cluster.proto index 4f44ac9cd..d23d767f7 100644 --- a/api/src/main/proto/envoy/extensions/clusters/aggregate/v3/cluster.proto +++ b/api/src/main/proto/envoy/extensions/clusters/aggregate/v3/cluster.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.clusters.aggregate.v3; +import "envoy/config/core/v3/config_source.proto"; + import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; @@ -25,3 +27,18 @@ message ClusterConfig { // appear in this list. repeated string clusters = 1 [(validate.rules).repeated = {min_items: 1}]; } + +// Configures an aggregate cluster whose +// :ref:`ClusterConfig ` +// is to be fetched from a separate xDS resource. +// [#extension: envoy.clusters.aggregate_resource] +// [#not-implemented-hide:] +message AggregateClusterResource { + // Configuration source specifier for the ClusterConfig resource. + // Only the aggregated protocol variants are supported; if configured + // otherwise, the cluster resource will be NACKed. + config.core.v3.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; + + // The name of the ClusterConfig resource to subscribe to. + string resource_name = 2 [(validate.rules).string = {min_len: 1}]; +} diff --git a/api/src/main/proto/envoy/extensions/clusters/reverse_connection/v3/reverse_connection.proto b/api/src/main/proto/envoy/extensions/clusters/reverse_connection/v3/reverse_connection.proto new file mode 100644 index 000000000..054ac1436 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/clusters/reverse_connection/v3/reverse_connection.proto @@ -0,0 +1,49 @@ +syntax = "proto3"; + +package envoy.extensions.clusters.reverse_connection.v3; + +import "google/protobuf/duration.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.clusters.reverse_connection.v3"; +option java_outer_classname = "ReverseConnectionProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/clusters/reverse_connection/v3;reverse_connectionv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Reverse connection cluster] +// [#extension: envoy.clusters.reverse_connection] + +// Configuration for a cluster of type REVERSE_CONNECTION. +message ReverseConnectionClusterConfig { + // Time interval after which Envoy removes unused dynamic hosts created for reverse connections. + // Hosts that are not referenced by any connection pool are deleted during cleanup. + // + // If unset, Envoy uses a default of 60s. + google.protobuf.Duration cleanup_interval = 1 [(validate.rules).duration = {gt {}}]; + + // Host identifier format string. + // + // This format string is evaluated against the downstream request context to compute + // the host identifier for selecting the reverse connection endpoint. The format string + // supports Envoy's standard formatter syntax, including: + // + // * ``%REQ(header-name)%``: Extract request header value. + // * ``%DYNAMIC_METADATA(namespace:key)%``: Extract dynamic metadata value. + // * ``%CEL(expression)%``: Evaluate CEL expression. + // * ``%DOWNSTREAM_REMOTE_ADDRESS%``: Downstream connection address. + // * ``%DOWNSTREAM_LOCAL_ADDRESS%``: Downstream local address. + // * Plain text and combinations of the above. + // + // Examples: + // + // * ``%REQ(x-remote-node-id)%``: Use the value of the ``x-remote-node-id`` header. + // * ``%REQ(host):EXTRACT_FIRST_PART%``: Extract the first part of the Host header before a dot. + // * ``%CEL(request.headers['x-node-id'] | orValue('default'))%``: Use CEL with fallback. + // * ``node-%REQ(x-tenant-id)%-%REQ(x-region)%``: Combine multiple values. + // + // If the format string evaluates to an empty value, the request will not be routed. + string host_id_format = 2 [(validate.rules).string = {min_len: 1}]; +} diff --git a/api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto b/api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto index 722e9b328..e51ade131 100644 --- a/api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto +++ b/api/src/main/proto/envoy/extensions/common/aws/v3/credential_provider.proto @@ -4,6 +4,8 @@ package envoy.extensions.common.aws.v3; import "envoy/config/core/v3/base.proto"; +import "google/protobuf/duration.proto"; + import "udpa/annotations/sensitive.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -19,6 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for AWS credential provider. This is optional and the credentials are normally // retrieved from the environment or AWS configuration files by following the default credential // provider chain. However, this configuration can be used to override the default behavior. +// [#next-free-field: 11] message AwsCredentialProvider { // The option to use `AssumeRoleWithWebIdentity `_. AssumeRoleWithWebIdentityCredentialProvider assume_role_with_web_identity_provider = 1; @@ -36,6 +39,24 @@ message AwsCredentialProvider { // // This has no effect if inline_credential is provided. bool custom_credential_provider_chain = 4; + + // The option to use `IAM Roles Anywhere `_. + IAMRolesAnywhereCredentialProvider iam_roles_anywhere_credential_provider = 5; + + // The option to use credentials sourced from standard `AWS configuration files `_. + ConfigCredentialProvider config_credential_provider = 6; + + // The option to use credentials sourced from `container environment variables `_. + ContainerCredentialProvider container_credential_provider = 7; + + // The option to use credentials sourced from `environment variables `_. + EnvironmentCredentialProvider environment_credential_provider = 8; + + // The option to use credentials sourced from an EC2 `Instance Profile `_. + InstanceProfileCredentialProvider instance_profile_credential_provider = 9; + + // The option to use `STS:AssumeRole aka Role Chaining `_. + AssumeRoleCredentialProvider assume_role_credential_provider = 10; } // Configuration to use an inline AWS credential. This is an equivalent to setting the well-known @@ -77,3 +98,88 @@ message CredentialsFileCredentialProvider { // The profile within the credentials_file data source. If not provided, the default profile will be used. string profile = 2; } + +// Configuration to use `IAM Roles Anywhere `_ +// to retrieve AWS credentials. +// [#next-free-field: 9] +message IAMRolesAnywhereCredentialProvider { + // The ARN of the role to assume via the IAM Roles Anywhere sessions API. See `Configure Roles `_ for more details. + string role_arn = 1 [(validate.rules).string = {min_len: 1}]; + + // The certificate used for authenticating to the IAM Roles Anywhere service. + // This certificate must match one configured in the IAM Roles Anywhere profile. See `Configure Roles `_ for more details. + config.core.v3.DataSource certificate = 2 [(validate.rules).message = {required: true}]; + + // The optional certificate chain, required when you are using a subordinate certificate authority for certificate issuance. + // A certificate chain can contain a maximum of 5 elements, see `The IAM Roles Anywhere authentication process `_ for more details. + config.core.v3.DataSource certificate_chain = 3; + + // The TLS private key matching the certificate provided. + config.core.v3.DataSource private_key = 4 + [(validate.rules).message = {required: true}, (udpa.annotations.sensitive) = true]; + + // The arn of the IAM Roles Anywhere trust anchor configured in your AWS account. A trust anchor in IAM Roles anywhere establishes + // trust between your certificate authority (CA) and AWS. See `Establish trust `_ for more details. + string trust_anchor_arn = 5 [(validate.rules).string = {min_len: 1}]; + + // The IAM Roles Anywhere profile ARN configured in your AWS account. + string profile_arn = 6 [(validate.rules).string = {min_len: 1}]; + + // An optional role session name, used when identifying the role in subsequent AWS API calls. + string role_session_name = 7; + + // An optional session duration, used when calculating the maximum time before vended credentials expire. This value cannot exceed the value configured + // in the IAM Roles Anywhere profile and the resultant session duration is calculate by the formula `here `_. + // If no session duration is provided here, the session duration is sourced from the IAM Roles Anywhere profile. + google.protobuf.Duration session_duration = 8 [(validate.rules).duration = { + lte {seconds: 43200} + gte {seconds: 900} + }]; +} + +// The Config Credential Provider has no configurable parameters, but listing it in a custom credential provider chain will enable this +// credential provider. +message ConfigCredentialProvider { +} + +// The Container Credential Provider has no configurable parameters, but listing it in a custom credential provider chain will enable this +// credential provider. +message ContainerCredentialProvider { +} + +// The Environment Credential Provider has no configurable parameters, but listing it in a custom credential provider chain will enable this +// credential provider. +message EnvironmentCredentialProvider { +} + +// The Instance Profile Credential Provider has no configurable parameters, but listing it in a custom credential provider chain will enable this +// credential provider. +message InstanceProfileCredentialProvider { +} + +// Configuration to use `AssumeRole `_ for retrieving new credentials, via role chaining. +// [#next-free-field: 6] +message AssumeRoleCredentialProvider { + // The ARN of the role to assume. + string role_arn = 1 [(validate.rules).string = {min_len: 1}]; + + // An optional role session name, used when identifying the role in subsequent AWS API calls. If not provided, the role session name will default + // to the current timestamp. + string role_session_name = 2; + + // Optional string value to use as the externalId + string external_id = 3; + + // An optional duration, in seconds, of the role session. Minimum role duration is 900s (5 minutes) and maximum is 43200s (12 hours). + // If the session duration is not provided, the default will be determined using the `table described here `_. + google.protobuf.Duration session_duration = 4 [(validate.rules).duration = { + lte {seconds: 43200} + gte {seconds: 900} + }]; + + // The credential provider for signing the AssumeRole request. This is optional and if not set, + // it will be retrieved from the procedure described in :ref:`config_http_filters_aws_request_signing`. + // This list of credential providers cannot include an AssumeRole credential provider and if one is provided + // it will be ignored. + AwsCredentialProvider credential_provider = 5; +} diff --git a/api/src/main/proto/envoy/extensions/filters/http/api_key_auth/v3/api_key_auth.proto b/api/src/main/proto/envoy/extensions/filters/http/api_key_auth/v3/api_key_auth.proto index a75b803cf..87e05cb2e 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/api_key_auth/v3/api_key_auth.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/api_key_auth/v3/api_key_auth.proto @@ -23,7 +23,8 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // // For example, the following configuration configures the filter to authenticate the clients using // the API key from the header ``X-API-KEY``. And only the clients with the key ``real-key`` are -// considered as authenticated. +// considered as authenticated. The client information is configured to be forwarded +// in the header ``x-client-id``. // // .. code-block:: yaml // @@ -32,6 +33,9 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // client: user // key_sources: // - header: "X-API-KEY" +// forwarding: +// header: "x-client-id" +// hide_credentials: false // message ApiKeyAuth { // The credentials that are used to authenticate the clients. @@ -39,6 +43,9 @@ message ApiKeyAuth { // The key sources to fetch the key from the coming request. repeated KeySource key_sources = 2; + + // Optional configuration to control what information should be propagated to upstream services. + Forwarding forwarding = 3; } // API key auth configuration of per route or per virtual host or per route configuration. @@ -67,6 +74,11 @@ message ApiKeyAuthPerRoute { // route. // repeated string allowed_clients = 3; + + // Optional configuration to control what information should be propagated to upstream services. + // If this field is non-empty, then the forwarding information in the filter level configuration + // will be ignored and the forwarding in this configuration will be used. + Forwarding forwarding = 4; } // Single credential entry that contains the API key and the related client id. @@ -101,3 +113,16 @@ message KeySource { [(validate.rules).string = {max_len: 1024 well_known_regex: HTTP_HEADER_NAME strict: false ignore_empty: true}]; } + +message Forwarding { + // The header name in which to store the client information. If this field is non-empty, + // the client string associated with the matched credential will be injected into + // the request before forwarding upstream. + string header = 1 + [(validate.rules).string = {max_len: 1024 well_known_regex: HTTP_HEADER_NAME strict: false}]; + + // If true, remove the API key from the request before forwarding upstream. + // + // This applies to all configured key sources: ``header``, ``query``, and ``cookie``. + bool hide_credentials = 2; +} diff --git a/api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto b/api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto index 254352e77..610c8c7c6 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto @@ -110,7 +110,7 @@ message AwsRequestSigning { QueryString query_string = 7; // The credential provider for signing the request. This is optional and if not set, - // it will be retrieved from the procedure described in :ref:`config_http_filters_aws_request_signing`. + // it will be retrieved using the procedure described in :ref:`config_http_filters_aws_request_signing`. common.aws.v3.AwsCredentialProvider credential_provider = 8; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/cache_v2/v3/cache.proto b/api/src/main/proto/envoy/extensions/filters/http/cache_v2/v3/cache.proto new file mode 100644 index 000000000..9a335f55a --- /dev/null +++ b/api/src/main/proto/envoy/extensions/filters/http/cache_v2/v3/cache.proto @@ -0,0 +1,108 @@ +syntax = "proto3"; + +package envoy.extensions.filters.http.cache_v2.v3; + +import "envoy/config/route/v3/route_components.proto"; +import "envoy/type/matcher/v3/string.proto"; + +import "google/protobuf/any.proto"; +import "google/protobuf/wrappers.proto"; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.http.cache_v2.v3"; +option java_outer_classname = "CacheProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/cache_v2/v3;cache_v2v3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: HTTP Cache Filter V2] + +// [#extension: envoy.filters.http.cache_v2] +// [#next-free-field: 8] +message CacheV2Config { + // [#not-implemented-hide:] + // Modifies cache key creation by restricting which parts of the URL are included. + message KeyCreatorParams { + // If true, exclude the URL scheme from the cache key. Set to true if your origins always + // produce the same response for http and https requests. + bool exclude_scheme = 1; + + // If true, exclude the host from the cache key. Set to true if your origins' responses don't + // ever depend on host. + bool exclude_host = 2; + + // If ``query_parameters_included`` is nonempty, only query parameters matched + // by one or more of its matchers are included in the cache key. Any other + // query params will not affect cache lookup. + repeated config.route.v3.QueryParameterMatcher query_parameters_included = 3; + + // If ``query_parameters_excluded`` is nonempty, query parameters matched by one + // or more of its matchers are excluded from the cache key (even if also + // matched by ``query_parameters_included``), and will not affect cache lookup. + repeated config.route.v3.QueryParameterMatcher query_parameters_excluded = 4; + } + + // Config specific to the cache storage implementation. Required unless ``disabled`` + // is true. + // [#extension-category: envoy.http.cache_v2] + google.protobuf.Any typed_config = 1; + + // When true, the cache filter is a no-op filter. + // + // Possible use-cases for this include: + // - Turning a filter on and off with :ref:`ECDS `. + // [#comment: once route-specific overrides are implemented, they are the more likely use-case.] + google.protobuf.BoolValue disabled = 5; + + // [#not-implemented-hide:] + // List of matching rules that defines allowed ``Vary`` headers. + // + // The ``vary`` response header holds a list of header names that affect the + // contents of a response, as described by + // https://httpwg.org/specs/rfc7234.html#caching.negotiated.responses. + // + // During insertion, ``allowed_vary_headers`` acts as a allowlist: if a + // response's ``vary`` header mentions any header names that aren't matched by any rules in + // ``allowed_vary_headers``, that response will not be cached. + // + // During lookup, ``allowed_vary_headers`` controls what request headers will be + // sent to the cache storage implementation. + repeated type.matcher.v3.StringMatcher allowed_vary_headers = 2; + + // [#not-implemented-hide:] + // + // + // Modifies cache key creation by restricting which parts of the URL are included. + KeyCreatorParams key_creator_params = 3; + + // [#not-implemented-hide:] + // + // + // Max body size the cache filter will insert into a cache. 0 means unlimited (though the cache + // storage implementation may have its own limit beyond which it will reject insertions). + uint32 max_body_bytes = 4; + + // By default, a ``cache-control: no-cache`` or ``pragma: no-cache`` header in the request + // causes the cache to validate with its upstream even if the lookup is a hit. Setting this + // to true will ignore these headers. + bool ignore_request_cache_control_header = 6; + + // If this is set, requests sent upstream to populate the cache will go to the + // specified cluster rather than the cluster selected by the vhost and route. + // + // If you have actions to be taken by the router filter - either + // ``upstream_http_filters`` or one of the ``RouteConfiguration`` actions such as + // ``response_headers_to_add`` - then the cache's side-channel going directly to the + // routed cluster will bypass these actions. You can set ``override_upstream_cluster`` + // to an internal listener which duplicates the relevant ``RouteConfiguration``, to + // replicate the desired behavior on the side-channel upstream request issued by the + // cache. + // + // This is a workaround for implementation constraints which it is hoped will at some + // point become unnecessary, then unsupported and this field will be removed. + string override_upstream_cluster = 7; +} diff --git a/api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto b/api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto index 4e7d372ab..c5f1b4fb1 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto @@ -33,9 +33,21 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; message Composite { } +// A list of filter configurations to be called in order. Note that this can be used as the type +// inside of an ECDS :ref:`TypedExtensionConfig +// ` extension, which allows a chain of +// filters to be configured dynamically. In that case, the types of all filters in the chain must +// be present in the :ref:`ExtensionConfigSource.type_urls +// ` field. +message FilterChainConfiguration { + repeated config.core.v3.TypedExtensionConfig typed_config = 1; +} + // Configuration for an extension configuration discovery service with name. message DynamicConfig { // The name of the extension configuration. It also serves as a resource name in ExtensionConfigDS. + // The resource type in the ``DiscoveryRequest`` will be :ref:`TypedExtensionConfig + // `. string name = 1 [(validate.rules).string = {min_len: 1}]; // Configuration source specifier for an extension configuration discovery @@ -50,15 +62,21 @@ 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. // [#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. 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:] + FilterChainConfiguration filter_chain = 4; + // 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/api/src/main/proto/envoy/extensions/filters/http/compressor/v3/compressor.proto b/api/src/main/proto/envoy/extensions/filters/http/compressor/v3/compressor.proto index c49ccfead..7e679380a 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/compressor/v3/compressor.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/compressor/v3/compressor.proto @@ -28,21 +28,31 @@ message Compressor { "envoy.config.filter.http.compressor.v2.Compressor"; message CommonDirectionConfig { - // Runtime flag that controls whether compression is enabled or not for the direction this - // common config is put in. If set to false, the filter will operate as a pass-through filter - // in the chosen direction, unless overridden by CompressorPerRoute. - // If the field is omitted, the filter will be enabled. + // Runtime flag that controls whether compression is enabled for the direction this + // common config is applied to. When this field is ``false``, the filter will operate as a + // pass-through filter in the chosen direction, unless overridden by ``CompressorPerRoute``. + // If this field is not specified, the filter will be enabled. config.core.v3.RuntimeFeatureFlag enabled = 1; - // Minimum value of Content-Length header of request or response messages (depending on the direction - // this common config is put in), in bytes, which will trigger compression. The default value is 30. + // Minimum value of the ``Content-Length`` header in request or response messages (depending on the + // direction this common config is applied to), in bytes, that will trigger compression. Defaults to 30. google.protobuf.UInt32Value min_content_length = 2; // Set of strings that allows specifying which mime-types yield compression; e.g., - // application/json, text/html, etc. When this field is not defined, compression will be applied - // to the following mime-types: "application/javascript", "application/json", - // "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml" - // and their synonyms. + // ``application/json``, ``text/html``, etc. + // + // When this field is not specified, compression will be applied to these following mime-types + // and their synonyms: + // + // * ``application/javascript`` + // * ``application/json`` + // * ``application/xhtml+xml`` + // * ``image/svg+xml`` + // * ``text/css`` + // * ``text/html`` + // * ``text/plain`` + // * ``text/xml`` + // repeated string content_type = 3; } @@ -52,28 +62,40 @@ message Compressor { } // Configuration for filter behavior on the response direction. + // [#next-free-field: 6] message ResponseDirectionConfig { CommonDirectionConfig common_config = 1; - // If true, disables compression when the response contains an etag header. When it is false, the - // filter will preserve weak etags and remove the ones that require strong validation. + // When this field is ``true``, disables compression when the response contains an ``ETag`` header. + // When this field is ``false``, the filter will preserve weak ``ETag`` values and remove those that + // require strong validation. bool disable_on_etag_header = 2; - // If true, removes accept-encoding from the request headers before dispatching it to the upstream - // so that responses do not get compressed before reaching the filter. + // When this field is ``true``, removes ``Accept-Encoding`` from the request headers before dispatching + // the request to the upstream so that responses do not get compressed before reaching the filter. // // .. attention:: // - // To avoid interfering with other compression filters in the same chain use this option in + // To avoid interfering with other compression filters in the same chain, use this option in // the filter closest to the upstream. bool remove_accept_encoding_header = 3; - // Set of response codes for which compression is disabled, e.g. 206 Partial Content should not + // Set of response codes for which compression is disabled; e.g., 206 Partial Content should not // be compressed. repeated uint32 uncompressible_response_codes = 4 [(validate.rules).repeated = { unique: true items {uint32 {lt: 600 gte: 200}} }]; + + // If true, the filter adds the ``x-envoy-compression-status`` response + // header to indicate whether the compression occurred and, if not, provide + // the reason why. The header's value format is + // ``;[;]``, where ```` is + // ``Compressed`` or the reason compression was skipped (e.g., + // ``ContentLengthTooSmall``). When this field is enabled, the compressor + // filter alters the order of the compression eligibility checks to report + // the most valid reason for skipping the compression. + bool status_header_enabled = 5; } // Minimum response length, in bytes, which will trigger compression. The default value is 30. @@ -81,60 +103,69 @@ message Compressor { [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Set of strings that allows specifying which mime-types yield compression; e.g., - // application/json, text/html, etc. When this field is not defined, compression will be applied - // to the following mime-types: "application/javascript", "application/json", - // "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml" - // and their synonyms. + // ``application/json``, ``text/html``, etc. + // + // When this field is not specified, compression will be applied to these following mime-types + // and their synonyms: + // + // * ``application/javascript`` + // * ``application/json`` + // * ``application/xhtml+xml`` + // * ``image/svg+xml`` + // * ``text/css`` + // * ``text/html`` + // * ``text/plain`` + // * ``text/xml`` + // repeated string content_type = 2 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // If true, disables compression when the response contains an etag header. When it is false, the - // filter will preserve weak etags and remove the ones that require strong validation. + // When this field is ``true``, disables compression when the response contains an ``ETag`` header. + // When this field is ``false``, the filter will preserve weak ``ETag`` values and remove those that + // require strong validation. bool disable_on_etag_header = 3 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // If true, removes accept-encoding from the request headers before dispatching it to the upstream - // so that responses do not get compressed before reaching the filter. + // When this field is ``true``, removes ``Accept-Encoding`` from the request headers before dispatching + // the request to the upstream so that responses do not get compressed before reaching the filter. // // .. attention:: // - // To avoid interfering with other compression filters in the same chain use this option in + // To avoid interfering with other compression filters in the same chain, use this option in // the filter closest to the upstream. bool remove_accept_encoding_header = 4 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // Runtime flag that controls whether the filter is enabled or not. If set to false, the - // filter will operate as a pass-through filter, unless overridden by - // CompressorPerRoute. If not specified, defaults to enabled. + // Runtime flag that controls whether the filter is enabled. When this field is ``false``, the + // filter will operate as a pass-through filter, unless overridden by ``CompressorPerRoute``. + // If this field is not specified, the filter is enabled by default. config.core.v3.RuntimeFeatureFlag runtime_enabled = 5 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // A compressor library to use for compression. Currently only - // :ref:`envoy.compression.gzip.compressor` - // is included in Envoy. + // A compressor library to use for compression. // [#extension-category: envoy.compression.compressor] config.core.v3.TypedExtensionConfig compressor_library = 6 [(validate.rules).message = {required: true}]; - // Configuration for request compression. Compression is disabled by default if left empty. + // Configuration for request compression. If this field is not specified, request compression is disabled. RequestDirectionConfig request_direction_config = 7; - // Configuration for response compression. Compression is enabled by default if left empty. + // Configuration for response compression. If this field is not specified, response compression is enabled. // // .. attention:: // - // If the field is not empty then the duplicate deprecated fields of the ``Compressor`` message, + // When this field is set, duplicate deprecated fields of the ``Compressor`` message, // such as ``content_length``, ``content_type``, ``disable_on_etag_header``, - // ``remove_accept_encoding_header`` and ``runtime_enabled``, are ignored. + // ``remove_accept_encoding_header``, and ``runtime_enabled``, are ignored. // - // Also all the statistics related to response compression will be rooted in + // Additionally, all statistics related to response compression will be rooted in // ``.compressor...response.*`` // instead of // ``.compressor...*``. ResponseDirectionConfig response_direction_config = 8; - // If true, chooses this compressor first to do compression when the q-values in ``Accept-Encoding`` are same. - // The last compressor which enables choose_first will be chosen if multiple compressor filters in the chain have choose_first as true. + // When this field is ``true``, this compressor is preferred when q-values in ``Accept-Encoding`` are equal. + // If multiple compressor filters set ``choose_first`` to ``true``, the last one in the filter chain is chosen. bool choose_first = 9; } @@ -152,6 +183,10 @@ message ResponseDirectionOverrides { message CompressorOverrides { // If present, response compression is enabled. ResponseDirectionOverrides response_direction_config = 1; + + // A compressor library to use for compression. If specified, this overrides + // the filter-level ``compressor_library`` configuration for this route. + config.core.v3.TypedExtensionConfig compressor_library = 2; } message CompressorPerRoute { @@ -159,7 +194,7 @@ message CompressorPerRoute { option (validate.required) = true; // If set, the filter will operate as a pass-through filter. - // Overrides Compressor.runtime_enabled and CommonDirectionConfig.enabled. + // Overrides ``Compressor.runtime_enabled`` and ``CommonDirectionConfig.enabled``. bool disabled = 1 [(validate.rules).bool = {const: true}]; // Per-route overrides. Fields set here will override corresponding fields in ``Compressor``. diff --git a/api/src/main/proto/envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto b/api/src/main/proto/envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto index 5dc8e82b5..452a3f71d 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto @@ -4,8 +4,6 @@ package envoy.extensions.filters.http.credential_injector.v3; import "envoy/config/core/v3/extension.proto"; -import "xds/annotations/v3/status.proto"; - import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -14,7 +12,6 @@ option java_outer_classname = "CredentialInjectorProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/credential_injector/v3;credential_injectorv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Credential Injector] // Credential Injector :ref:`configuration overview `. diff --git a/api/src/main/proto/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto b/api/src/main/proto/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto index 1ef5e0242..76dc47bd0 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto @@ -41,6 +41,17 @@ message FilterConfig { // ``envoy.stream.upstream_address`` (See // :repo:`upstream_address.h`). bool save_upstream_address = 2; + + // When this flag is set, the filter will check for the ``envoy.upstream.dynamic_host`` + // and/or ``envoy.upstream.dynamic_port`` filter state values before using the HTTP + // Host header for DNS resolution. This provides consistency with the + // :ref:`SNI dynamic forward proxy ` and + // :ref:`UDP dynamic forward proxy ` + // filters behavior when enabled. + // + // If the flag is not set (default), the filter will use the HTTP Host header + // for DNS resolution, maintaining backward compatibility. + bool allow_dynamic_host_from_filter_state = 4; } // Per route Configuration for the dynamic forward proxy HTTP filter. @@ -53,22 +64,25 @@ message PerRouteConfig { // 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 DNS lookup 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 DNS lookups 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 DNS lookup and host header forwarding. However, this option shouldn't be used with + // :ref:`HCM host rewrite header ` given that + // the value set here would be used for DNS lookups whereas the value set in the HCM would be used for host + // header forwarding which might not be the desired outcome. + // string host_rewrite_literal = 1; // Indicates that before DNS lookup, the host header will be swapped with // the value of this header. If not set or empty, the original host header // value will be used and no rewrite will happen. // - // Note: this rewrite affects both DNS lookup and host header forwarding. However, this - // option shouldn't be used with - // :ref:`HCM host rewrite header ` - // given that the value set here would be used for DNS lookups 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 DNS lookup and host header forwarding. However, this option shouldn't be used with + // :ref:`HCM host rewrite header ` given that + // the value set here would be used for DNS lookups whereas the value set in the HCM would be used for host + // header forwarding which might not be the desired outcome. // // .. note:: // @@ -78,6 +92,6 @@ message PerRouteConfig { } message SubClusterConfig { - // The timeout used for sub cluster initialization. Defaults to 5s if not set. + // The timeout used for sub cluster initialization. Defaults to **5s** if not set. google.protobuf.Duration cluster_init_timeout = 3 [(validate.rules).duration = {gt {}}]; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto b/api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto index d713bf810..2856a7f9b 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto @@ -22,6 +22,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // // 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 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. message DynamicModuleFilter { // Specifies the shared-object level configuration. envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1; @@ -58,4 +62,48 @@ message DynamicModuleFilter { // value: aGVsbG8= # echo -n "hello" | base64 // google.protobuf.Any filter_config = 3; + + // Set true if 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. + 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. +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. + 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. + // + // 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. + // + // .. code-block:: yaml + // + // # Passing in a string + // filter_config: + // "@type": "type.googleapis.com/google.protobuf.StringValue" + // value: hello + // + // # Passing in 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/api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 0a2492b2f..2d2c2a724 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/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: 30] +// [#next-free-field: 31] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v3.ExtAuthz"; @@ -53,40 +53,39 @@ message ExtAuthz { config.core.v3.ApiVersion transport_api_version = 12 [(validate.rules).enum = {defined_only: true}]; - // Changes filter's behavior on errors: + // Changes the filter's behavior on errors: // - // 1. When set to true, the filter will ``accept`` client request even if the communication with - // the authorization service has failed, or if the authorization service has returned a 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. // - // 2. When set to false, ext-authz will ``reject`` client requests and return a ``Forbidden`` - // response if the communication with the authorization service has failed, or if the - // authorization service has returned a 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. // - // Note that errors can be ``always`` tracked in the :ref:`stats - // `. + // Errors can always be tracked in the :ref:`stats `. bool failure_mode_allow = 2; - // When ``failure_mode_allow`` and ``failure_mode_allow_header_add`` are both set to true, + // When ``failure_mode_allow`` and ``failure_mode_allow_header_add`` are both set to ``true``, // ``x-envoy-auth-failure-mode-allowed: true`` will be added to request headers if the communication // with the authorization service has failed, or if the authorization service has returned a // HTTP 5xx error. bool failure_mode_allow_header_add = 19; - // Enables filter to buffer the client request body and send it within the authorization request. - // A ``x-envoy-auth-partial-body: false|true`` metadata header will be added to the authorization - // request message indicating if the body data is partial. + // Enables the filter to buffer the client request body and send it within the authorization request. + // The ``x-envoy-auth-partial-body: false|true`` metadata header will be added to the authorization + // request indicating whether the body data is partial. BufferSettings with_request_body = 5; - // Clears route cache in order to allow the external authorization service to correctly affect - // routing decisions. Filter clears all cached routes when: + // Clears the route cache in order to allow the external authorization service to correctly affect + // routing decisions. The filter clears all cached routes when: // - // 1. The field is set to ``true``. + // #. The field is set to ``true``. // - // 2. The status returned from the authorization service is a HTTP 200 or gRPC 0. + // #. The status returned from the authorization service is an HTTP 200 or gRPC 0. // - // 3. At least one ``authorization response header`` is added to the client request, or is used for - // altering another client request header. + // #. At least one ``authorization response header`` is added to the client request, or is used to + // alter another client request header. // bool clear_route_cache = 6; @@ -94,26 +93,27 @@ message ExtAuthz { // 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 - // ` for invalid header & + // When this is 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. // - // Note that headers_to_remove & query_parameters_to_remove are validated, but invalid elements in - // those fields should not affect any headers & thus will not cause the filter to send a local - // reply. + // .. note:: + // Both ``headers_to_remove`` and ``query_parameters_to_remove`` are validated, but invalid elements in + // those fields should not affect any headers and thus will not cause the filter to send a local reply. // - // When set to false, any invalid mutations will be visible to the rest of envoy and may cause + // When set to ``false``, any invalid mutations will be visible to the rest of Envoy and may cause // unexpected behavior. // - // If you are using ext_authz with an untrusted ext_authz server, you should set this to true. + // If you are using ext_authz with an untrusted ext_authz server, you should set this to ``true``. bool validate_mutations = 24; // 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``. // - // Please note that this field exclusively applies to the gRPC ext_authz service and has no effect on the HTTP service. + // .. note:: + // This field applies exclusively to the gRPC ext_authz service and has no effect on the HTTP service. // // For example, if the ``jwt_authn`` filter is used and :ref:`payload_in_metadata // ` is set, @@ -130,10 +130,11 @@ message ExtAuthz { // ext_authz service. :ref:`typed_filter_metadata ` // is passed as a ``protobuf::Any``. // - // Please note that this field exclusively applies to the gRPC ext_authz service and has no effect on the HTTP service. + // .. note:: + // This field applies exclusively to the gRPC ext_authz service and has no effect on the HTTP service. // - // It works in a way similar to ``metadata_context_namespaces`` but allows Envoy and ext_authz server to share - // the protobuf message definition in order to do a safe parsing. + // 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 = 16; @@ -146,7 +147,7 @@ message ExtAuthz { // Specifies a list of route metadata namespaces whose values, if present, will be passed to the // ext_authz service at :ref:`route_metadata_context ` in // :ref:`CheckRequest `. - // :ref:`typed_filter_metadata ` is passed as an ``protobuf::Any``. + // :ref:`typed_filter_metadata ` is passed as a ``protobuf::Any``. repeated string route_typed_metadata_context_namespaces = 22; // Specifies if the filter is enabled. @@ -161,11 +162,11 @@ message ExtAuthz { // If this field is not specified, the filter will be enabled for all requests. type.matcher.v3.MetadataMatcher filter_enabled_metadata = 14; - // Specifies whether to deny the requests, when the filter is disabled. + // Specifies whether to deny the requests when the filter is disabled. // If :ref:`runtime_key ` is specified, - // Envoy will lookup the runtime key to determine whether to deny request for - // filter protected path at filter disabling. If filter is disabled in - // typed_per_filter_config for the path, requests will not be denied. + // Envoy will lookup the runtime key to determine whether to deny requests for filter-protected paths + // when the filter is disabled. If the filter is disabled in ``typed_per_filter_config`` for the path, + // requests will not be denied. // // If this field is not specified, all requests will be allowed when disabled. // @@ -176,11 +177,11 @@ message ExtAuthz { // Specifies if the peer certificate is sent to the external service. // - // When this field is true, Envoy will include the peer X.509 certificate, if available, in the + // When this field is ``true``, Envoy will include the peer X.509 certificate, if available, in the // :ref:`certificate`. bool include_peer_certificate = 10; - // Optional additional prefix to use when emitting statistics. This allows to distinguish + // Optional additional prefix to use when emitting statistics. This allows distinguishing // emitted statistics between configured ``ext_authz`` filters in an HTTP filter chain. For example: // // .. code-block:: yaml @@ -210,21 +211,20 @@ message ExtAuthz { // // .. note:: // - // 1. For requests to an HTTP authorization server: in addition to the user's supplied matchers, ``Host``, ``Method``, ``Path``, - // ``Content-Length``, and ``Authorization`` are **additionally included** in the list. + // For requests to an HTTP authorization server: in addition to the user's supplied matchers, ``Host``, ``Method``, ``Path``, + // ``Content-Length``, and ``Authorization`` are **additionally included** in the list. // // .. note:: // - // 2. For requests to an HTTP authorization server: value of ``Content-Length`` will be set to 0 and the request to the + // For requests to an HTTP authorization server: the value of ``Content-Length`` will be set to ``0`` and the request to the // authorization server will not have a message body. However, the check request can include the buffered // client request body (controlled by :ref:`with_request_body - // ` setting), - // consequently the value of *Content-Length* of the authorization request reflects the size of - // its payload size. + // ` setting); + // consequently, the value of ``Content-Length`` in the authorization request reflects the size of its payload. // // .. note:: // - // 3. This can be overridden by the field ``disallowed_headers`` below. That is, if a header + // This can be overridden by the field ``disallowed_headers`` below. That is, if a header // matches for both ``allowed_headers`` and ``disallowed_headers``, the header will NOT be sent. type.matcher.v3.ListStringMatcher allowed_headers = 17; @@ -234,34 +234,35 @@ message ExtAuthz { // Specifies if the TLS session level details like SNI are sent to the external service. // - // When this field is true, Envoy will include the SNI name used for TLSClientHello, if available, in the + // When this field is ``true``, Envoy will include the SNI name used for TLSClientHello, if available, in the // :ref:`tls_session`. bool include_tls_session = 18; // Whether to increment cluster statistics (e.g. cluster..upstream_rq_*) on authorization failure. - // Defaults to true. + // Defaults to ``true``. google.protobuf.BoolValue charge_cluster_response_stats = 20; - // Whether to encode the raw headers (i.e. unsanitized values & unconcatenated multi-line headers) - // in authentication request. Works with both HTTP and gRPC clients. + // Whether to encode the raw headers (i.e., unsanitized values and unconcatenated multi-line headers) + // in the authorization request. Works with both HTTP and gRPC clients. // - // When this is set to true, header values are not sanitized. Headers with the same key will also + // When this is set to ``true``, header values are not sanitized. Headers with the same key will also // not be combined into a single, comma-separated header. // Requests to gRPC services will populate the field // :ref:`header_map`. // Requests to HTTP services will be constructed with the unsanitized header values and preserved // multi-line headers with the same key. // - // If this field is set to false, header values will be sanitized, with any non-UTF-8-compliant - // bytes replaced with '!'. Headers with the same key will have their values concatenated into a + // If this field is set to ``false``, header values will be sanitized, with any non-UTF-8-compliant + // bytes replaced with ``'!'``. Headers with the same key will have their values concatenated into a // single comma-separated header value. // Requests to gRPC services will populate the field // :ref:`headers`. // Requests to HTTP services will have their header values sanitized and will not preserve // multi-line headers with the same key. // - // It's recommended you set this to true unless you already rely on the old behavior. False is the - // default only for backwards compatibility. + // It is recommended to set this to ``true`` unless you rely on the previous behavior. + // + // It is set to ``false`` by default for backwards compatibility. bool encode_raw_headers = 23; // Rules for what modifications an ext_authz server may make to the request headers before @@ -281,15 +282,15 @@ message ExtAuthz { // This field allows the filter to reject mutations to specific headers. config.common.mutation_rules.v3.HeaderMutationRules decoder_header_mutation_rules = 26; - // Enable / disable ingestion of dynamic metadata from ext_authz service. + // Enable or disable ingestion of dynamic metadata from the ext_authz service. // - // If false, the filter will ignore dynamic metadata injected by the ext_authz service. If the + // If ``false``, the filter will ignore dynamic metadata injected by the ext_authz service. If the // ext_authz service tries injecting dynamic metadata, the filter will log, increment the // ``ignored_dynamic_metadata`` stat, then continue handling the response. // - // If true, the filter will ingest dynamic metadata entries as normal. + // If ``true``, the filter will ingest dynamic metadata entries as normal. // - // If unset, defaults to true. + // If unset, defaults to ``true``. google.protobuf.BoolValue enable_dynamic_metadata_ingestion = 27; // Additional metadata to be added to the filter state for logging purposes. The metadata will be @@ -297,19 +298,30 @@ message ExtAuthz { // name. google.protobuf.Struct filter_metadata = 28; - // When set to true, the filter will emit per-stream stats for access logging. The filter state + // When set to ``true``, the filter will emit per-stream stats for access logging. The filter state // 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. // - // If this is false the filter will not emit stats, but filter_metadata will still be respected if + // If this is ``false`` the filter will not emit stats, but filter_metadata will still be respected if // it has a value. // // Field ``latency_us`` is exposed for CEL and logging when using gRPC or HTTP service. // Fields ``bytesSent`` and ``bytesReceived`` are exposed for CEL and logging only when using gRPC service. bool emit_filter_state_stats = 29; + + // Sets the maximum size (in bytes) of the response body that the filter will send downstream + // when a request is denied by the external authorization service. + // + // If the authorization server returns a response body larger than this configured limit, + // the body will be truncated to ``max_denied_response_body_bytes`` before being sent to the + // downstream client. + // + // 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; } // Configuration for buffering the request data. @@ -318,21 +330,21 @@ message BufferSettings { "envoy.config.filter.http.ext_authz.v2.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 buffer reaches the number + // ``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 // `. 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. + // 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. bool allow_partial_message = 2; - // If true, the body sent to the external authorization service is set with raw bytes, it sets - // the :ref:`raw_body` - // field of HTTP request attribute context. Otherwise, :ref:`body - // ` will be filled - // with UTF-8 string request body. + // If ``true``, the body sent to the external authorization service is set as raw bytes and populates + // :ref:`raw_body` + // in the HTTP request attribute context. Otherwise, :ref:`body + // ` will be populated + // with a UTF-8 string request body. // // This field only affects configurations using a :ref:`grpc_service // `. In configurations that use @@ -347,7 +359,7 @@ message BufferSettings { // request. Note that 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 +// On authorization request, a list of allowed request headers may be supplied. See // :ref:`allowed_headers // ` // for details. Additional headers metadata may be added to the authorization request. See @@ -355,7 +367,7 @@ message BufferSettings { // ` for // details. // -// On authorization response status HTTP 200 OK, the filter will allow traffic to the upstream and +// On authorization response status ``HTTP 200 OK``, the filter will allow traffic to the upstream and // additional headers metadata may be added to the original client request. See // :ref:`allowed_upstream_headers // ` @@ -368,7 +380,7 @@ message BufferSettings { // metadata as well as body may be added to the client's response. See :ref:`allowed_client_headers // ` // for details. -// [#next-free-field: 9] +// [#next-free-field: 10] message HttpService { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.HttpService"; @@ -386,13 +398,20 @@ message HttpService { // Settings used for controlling authorization response metadata. AuthorizationResponse authorization_response = 8; + + // Optional retry policy for requests to the authorization server. + // If not set, no retries will be performed. + // + // .. note:: + // When this field is set, the ``ext_authz`` filter will buffer the request body for retry purposes. + config.core.v3.RetryPolicy retry_policy = 9; } message AuthorizationRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.AuthorizationRequest"; - // Authorization request includes the client request headers that have a correspondent match + // Authorization request includes the client request headers that have a corresponding match // in the :ref:`list `. // This field has been deprecated in favor of :ref:`allowed_headers // `. @@ -404,17 +423,17 @@ message AuthorizationRequest { // // .. note:: // - // By default, ``Content-Length`` header is set to ``0`` and the request to the authorization + // By default, the ``Content-Length`` header is set to ``0`` and the request to the authorization // service has no message body. However, the authorization request *may* include the buffered // client request body (controlled by :ref:`with_request_body // ` - // setting) hence the value of its ``Content-Length`` reflects the size of its payload size. + // setting); hence the value of its ``Content-Length`` reflects the size of its payload. // 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 to the request to authorization service. Note that - // client request of the same key will be overridden. + // 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. repeated config.core.v3.HeaderValue headers_to_add = 2; } @@ -466,7 +485,7 @@ message ExtAuthzPerRoute { // Disable the ext auth filter for this particular vhost or route. // If disabled is specified in multiple per-filter-configs, the most specific one will be used. - // If the filter is disabled by default and this is set to false, the filter will be enabled + // If the filter is disabled by default and this is set to ``false``, the filter will be enabled // for this vhost or route. bool disabled = 1; @@ -476,6 +495,7 @@ message ExtAuthzPerRoute { } // Extra settings for the check request. +// [#next-free-field: 6] message CheckSettings { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.CheckSettings"; @@ -492,15 +512,14 @@ message CheckSettings { // Merge semantics for this field are such that keys from more specific configs override. // // .. note:: - // // These settings are only applied to a filter configured with a // :ref:`grpc_service`. map context_extensions = 1 [(udpa.annotations.sensitive) = true]; - // When set to true, disable the configured :ref:`with_request_body + // When set to ``true``, disable the configured :ref:`with_request_body // ` for a specific route. // - // Please note that only one of *disable_request_body_buffering* or + // Only one of ``disable_request_body_buffering`` and // :ref:`with_request_body ` // may be specified. bool disable_request_body_buffering = 2; @@ -509,8 +528,20 @@ message CheckSettings { // :ref:`with_request_body ` // option for a specific route. // - // Please note that only one of ``with_request_body`` or + // Only one of ``with_request_body`` and // :ref:`disable_request_body_buffering ` // may be specified. BufferSettings with_request_body = 3; + + // Override the external authorization service for this route. + // This allows different routes to use different external authorization service backends + // and service types (gRPC or HTTP). If specified, this overrides the filter-level service + // configuration regardless of the original service type. + oneof service_override { + // Override with a gRPC service configuration. + config.core.v3.GrpcService grpc_service = 4; + + // Override with an HTTP service configuration. + HttpService http_service = 5; + } } diff --git a/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto b/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto index f7c1d8405..0108434ae 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto @@ -9,12 +9,15 @@ import "envoy/config/core/v3/grpc_service.proto"; import "envoy/config/core/v3/http_service.proto"; import "envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto"; import "envoy/type/matcher/v3/string.proto"; +import "envoy/type/v3/http_status.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; import "xds/annotations/v3/status.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -34,10 +37,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // The filter communicates with an external gRPC service called an "external processor" // that can do a variety of things with the request and response: // -// * Access and modify the HTTP headers on the request, response, or both -// * Access and modify the HTTP request and response bodies -// * Access and modify the dynamic stream metadata -// * Immediately send an HTTP response downstream and terminate other processing +// * Access and modify the HTTP headers on the request, response, or both. +// * Access and modify the HTTP request and response bodies. +// * Access and modify the dynamic stream metadata. +// * Immediately send an HTTP response downstream and terminate other processing. // // The filter communicates with the server using a gRPC bidirectional stream. After the initial // request, the external server is in control over what additional data is sent to it @@ -45,22 +48,22 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // // By implementing the protocol specified by the stream, the external server can choose: // -// * Whether it receives the response message at all -// * Whether it receives the message body at all, in separate chunks, or as a single buffer -// * Whether subsequent HTTP requests are transmitted synchronously or whether they are -// sent asynchronously. -// * To modify request or response trailers if they already exist +// * Whether it receives the response message at all. +// * Whether it receives the message body at all, in separate chunks, or as a single buffer. +// * To modify request or response trailers if they already exist. // // The filter supports up to six different processing steps. Each is represented by // a gRPC stream message that is sent to the external processor. For each message, the // processor must send a matching response. // // * Request headers: Contains the headers from the original HTTP request. -// * Request body: Delivered if they are present and sent in a single message if -// the BUFFERED or BUFFERED_PARTIAL mode is chosen, in multiple messages if the -// STREAMED mode is chosen, and not at all otherwise. +// * 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. // * Request trailers: Delivered if they are present and if the trailer mode is set -// to SEND. +// to ``SEND``. // * Response headers: Contains the headers from the HTTP response. Keep in mind // that if the upstream system sends them before processing the request body that // this message may arrive before the complete body. @@ -69,12 +72,12 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // request trailers. // // By default, the processor sends only the request and response headers messages. -// This may be changed to include any of the six steps by changing the processing_mode -// setting of the filter configuration, or by setting the mode_override of any response -// from the external processor. The latter is only enabled if allow_mode_override is +// This may be changed to include any of the six steps by changing the ``processing_mode`` +// setting of the filter configuration, or by setting the ``mode_override`` of any response +// from the external processor. The latter is only enabled if ``allow_mode_override`` is // set to true. This way, a processor may, for example, use information // in the request header to determine whether the message body must be examined, or whether -// the proxy should simply stream it straight through. +// the data plane should simply stream it straight through. // // All of this together allows a server to process the filter traffic in fairly // sophisticated ways. For example: @@ -83,12 +86,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // on the content of the headers. // * A server may choose to immediately reject some messages based on their HTTP // headers (or other dynamic metadata) and more carefully examine others. -// * A server may asynchronously monitor traffic coming through the filter by inspecting -// headers, bodies, or both, and then decide to switch to a synchronous processing -// mode, either permanently or temporarily. // -// The protocol itself is based on a bidirectional gRPC stream. Envoy will send the -// server +// The protocol itself is based on a bidirectional gRPC stream. The data plane will send the server // :ref:`ProcessingRequest ` // messages, and the server must reply with // :ref:`ProcessingResponse `. @@ -97,7 +96,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` object in a namespace matching the filter // name. // -// [#next-free-field: 24] +// [#next-free-field: 26] message ExternalProcessor { // Describes the route cache action to be taken when an external processor response // is received in response to request headers. @@ -107,12 +106,12 @@ message ExternalProcessor { // field is set in an external processor response. DEFAULT = 0; - // Always clear the route cache irrespective of the clear_route_cache bit in + // Always clear the route cache irrespective of the ``clear_route_cache`` bit in // the external processor response. CLEAR = 1; - // Do not clear the route cache irrespective of the clear_route_cache bit in - // the external processor response. Setting to RETAIN is equivalent to set the + // Do not clear the route cache irrespective of the ``clear_route_cache`` bit in + // the external processor response. Setting to ``RETAIN`` is equivalent to setting the // :ref:`disable_clear_route_cache ` // to true. RETAIN = 2; @@ -123,7 +122,6 @@ message ExternalProcessor { reserved "async_mode"; // Configuration for the gRPC service that the filter will communicate with. - // The filter supports both the "Envoy" and "Google" gRPC clients. // Only one of ``grpc_service`` or ``http_service`` can be set. // It is required that one of them must be set. config.core.v3.GrpcService grpc_service = 1 @@ -131,22 +129,22 @@ message ExternalProcessor { // Configuration for the HTTP service that the filter will communicate with. // Only one of ``http_service`` or - // :ref:`grpc_service `. + // :ref:`grpc_service ` // can be set. It is required that one of them must be set. // // If ``http_service`` is set, the // :ref:`processing_mode ` - // can not be configured to send any body or trailers. i.e, http_service only supports + // cannot be configured to send any body or trailers. i.e., ``http_service`` only supports // sending request or response headers to the side stream server. // - // With this configuration, Envoy behavior: + // With this configuration, the data plane behavior is: // // 1. The headers are first put in a proto message // :ref:`ProcessingRequest `. // // 2. This proto message is then transcoded into a JSON text. // - // 3. Envoy then sends a HTTP POST message with content-type as "application/json", + // 3. The data plane then sends an HTTP POST message with content-type as "application/json", // and this JSON text as body to the side stream server. // // After the side-stream receives this HTTP request message, it is expected to do as follows: @@ -157,58 +155,70 @@ message ExternalProcessor { // 2. It then sets the mutated headers into a new proto message // :ref:`ProcessingResponse `. // - // 3. It converts ``ProcessingResponse`` proto message into a JSON text. + // 3. It converts the ``ProcessingResponse`` proto message into a JSON text. // - // 4. It then sends a HTTP response back to Envoy with status code as "200", - // content-type as "application/json" and sets the JSON text as the body. + // 4. It then sends an HTTP response back to the data plane with status code as ``"200"``, + // ``content-type`` as ``"application/json"`` and sets the JSON text as the body. // ExtProcHttpService http_service = 20 [ (udpa.annotations.field_migrate).oneof_promotion = "ext_proc_service_type", (xds.annotations.v3.field_status).work_in_progress = true ]; - // By default, if the gRPC stream cannot be established, or if it is closed - // prematurely with an error, the filter will fail. Specifically, if the - // response headers have not yet been delivered, then it will return a 500 - // error downstream. If they have been delivered, then instead the HTTP stream to the - // downstream client will be reset. - // With this parameter set to true, however, then if the gRPC stream is prematurely closed - // or could not be opened, processing continues without error. + // By default, if in the following cases: + // + // 1. The gRPC stream cannot be established. + // + // 2. The gRPC stream is closed prematurely with an error. + // + // 3. The external processing timeouts. + // + // 4. The ext_proc server sends back spurious response messages. + // + // The filter will fail and a local reply with error code + // 504(for timeout case) or 500(for all other cases), will be sent to the downstream. + // + // However, with this parameter set to true and if the above cases happen, the processing + // continues without error. + // bool failure_mode_allow = 2; // Specifies default options for how HTTP headers, trailers, and bodies are - // sent. See ProcessingMode for details. + // sent. See ``ProcessingMode`` for details. ProcessingMode processing_mode = 3; - // Envoy provides a number of :ref:`attributes ` + // The data plane provides a number of :ref:`attributes ` // for expressive policies. Each attribute name provided in this field will be - // matched against that list and populated in the request_headers message. + // matched against that list and populated in the + // :ref:`ProcessingRequest.attributes ` field. // See the :ref:`attribute documentation ` // for the list of supported attributes and their types. repeated string request_attributes = 5; - // Envoy provides a number of :ref:`attributes ` + // The data plane provides a number of :ref:`attributes ` // for expressive policies. Each attribute name provided in this field will be - // matched against that list and populated in the response_headers message. + // matched against that list and populated in the + // :ref:`ProcessingRequest.attributes ` field. // See the :ref:`attribute documentation ` // for the list of supported attributes and their types. repeated string response_attributes = 6; - // Specifies the timeout for each individual message sent on the stream and - // when the filter is running in synchronous mode. Whenever the proxy sends - // a message on the stream that requires a response, it will reset this timer, - // and will stop processing and return 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 asynchronous mode. Zero is a valid - // config which means the timer will be triggered immediately. If not - // configured, default is 200 milliseconds. + // Specifies the timeout for each individual message sent on the stream. + // Whenever the data plane sends a message on the stream that requires a + // response, it will reset this timer, and will stop processing and return + // 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. google.protobuf.Duration message_timeout = 7 [(validate.rules).duration = { lte {seconds: 3600} gte {} }]; // Optional additional prefix to use when emitting statistics. This allows to distinguish - // emitted statistics between configured *ext_proc* filters in an HTTP filter chain. + // emitted statistics between configured ``ext_proc`` filters in an HTTP filter chain. string stat_prefix = 8; // Rules that determine what modifications an external processing server may @@ -218,7 +228,7 @@ message ExternalProcessor { // :ref:`header_prefix ` // (which is usually "x-envoy"). // Note that changing headers such as "host" or ":authority" may not in itself - // change Envoy's routing decision, as routes can be cached. To also force the + // change the data plane's routing decision, as routes can be cached. To also force the // route to be recomputed, set the // :ref:`clear_route_cache ` // field to true in the same response. @@ -246,6 +256,7 @@ message ExternalProcessor { // can be overridden by the response message from the external processing server // :ref:`mode_override `. // If not set, ``mode_override`` API in the response message will be ignored. + // Mode override is not supported if the body send mode is ``FULL_DUPLEX_STREAMED``. bool allow_mode_override = 14; // If set to true, ignore the @@ -258,12 +269,12 @@ message ExternalProcessor { // Options related to the sending and receiving of dynamic metadata. MetadataOptions metadata_options = 16; - // If true, send each part of the HTTP request or response specified by ProcessingMode + // If true, send each part of the HTTP request or response specified by ``ProcessingMode`` // without pausing on filter chain iteration. It is "Send and Go" mode that can be used - // by external processor to observe Envoy data and status. In this mode: + // by external processor to observe the request's data and status. In this mode: // - // 1. Only STREAMED body processing mode is supported and any other body processing modes will be - // ignored. NONE mode(i.e., skip body processing) will still work as expected. + // 1. Only ``STREAMED`` 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 @@ -274,7 +285,7 @@ message ExternalProcessor { // // .. warning:: // - // Flow control is necessary mechanism to prevent the fast sender (either downstream client or upstream server) + // Flow control is a necessary mechanism to prevent the fast sender (either downstream client or upstream server) // from overwhelming the external processor when its processing speed is slower. // This protective measure is being explored and developed but has not been ready yet, so please use your own // discretion when enabling this feature. @@ -291,7 +302,7 @@ message ExternalProcessor { [(udpa.annotations.field_migrate).oneof_promotion = "clear_route_cache_type"]; // Specifies the action to be taken when an external processor response is - // received in response to request headers. It is recommended to set this field than set + // received in response to request headers. It is recommended to set this field rather than set // :ref:`disable_clear_route_cache `. // Only one of ``disable_clear_route_cache`` or ``route_cache_action`` can be set. RouteCacheAction route_cache_action = 18 @@ -300,12 +311,13 @@ message ExternalProcessor { // Specifies the deferred closure timeout for gRPC stream that connects to external processor. Currently, the deferred stream closure // is only used in :ref:`observability_mode `. // In observability mode, gRPC streams may be held open to the external processor longer than the lifetime of the regular client to - // backend stream lifetime. In this case, Envoy will eventually timeout the external processor stream according to this time limit. + // backend stream lifetime. In this case, the data plane will eventually timeout the external processor stream according to this time limit. // The default value is 5000 milliseconds (5 seconds) if not specified. google.protobuf.Duration deferred_close_timeout = 19; // Send body to the side stream server once it arrives without waiting for the header response from that server. - // It only works for STREAMED body processing mode. For any other body processing modes, it is ignored. + // It only works for ``STREAMED`` body processing mode. For any other body + // processing modes, it is ignored. // The server has two options upon receiving a header request: // // 1. Instant Response: send the header response as soon as the header request is received. @@ -314,9 +326,9 @@ message ExternalProcessor { // // In all scenarios, the header-body ordering must always be maintained. // - // If enabled Envoy will ignore the + // If enabled the data plane will ignore the // :ref:`mode_override ` - // value that the server sends in the header response. This is because Envoy may have already + // value that the server sends in the header response. This is because the data plane may have already // sent the body to the server, prior to processing the header response. bool send_body_without_waiting_for_header_response = 21; @@ -327,9 +339,19 @@ message ExternalProcessor { // can only be overridden by the response message from the external processing server iff the // :ref:`mode_override ` is allowed by // the ``allowed_override_modes`` allow-list below. - // Since request_header_mode is not applicable in any way, it's ignored in comparison. + // Since ``request_header_mode`` is not applicable in any way, it's ignored in comparison. repeated ProcessingMode allowed_override_modes = 22; + // Decorator to introduce custom logic that runs after the ``ProcessingRequest`` is constructed, but + // before it is sent to the External Processor. The ``ProcessingRequest`` may be modified. + // + // .. note:: + // Processing request modifiers are currently in alpha. + // + // [#extension-category: envoy.http.ext_proc.processing_request_modifiers] + config.core.v3.TypedExtensionConfig processing_request_modifier = 25 + [(xds.annotations.v3.field_status).work_in_progress = true]; + // Decorator to introduce custom logic that runs after a message received from // the External Processor is processed, but before continuing filter chain iteration. // @@ -339,6 +361,12 @@ message ExternalProcessor { // [#extension-category: envoy.http.ext_proc.response_processors] config.core.v3.TypedExtensionConfig on_processing_response = 23 [(xds.annotations.v3.field_status).work_in_progress = true]; + + // Sets the HTTP status code that is returned to the client when the external processing server returns + // an error, fails to respond, or cannot be reached. + // + // The default status is ``HTTP 500 Internal Server Error``. + type.v3.HttpStatus status_on_error = 24; } // ExtProcHttpService is used for HTTP communication between the filter and the external processing service. @@ -353,11 +381,11 @@ message ExtProcHttpService { message MetadataOptions { message MetadataNamespaces { // Specifies a list of metadata namespaces whose values, if present, - // will be passed to the ext_proc service as an opaque *protobuf::Struct*. + // will be passed to the ``ext_proc`` service as an opaque ``protobuf::Struct``. repeated string untyped = 1; // Specifies a list of metadata namespaces whose values, if present, - // will be passed to the ext_proc service as a *protobuf::Any*. This allows + // will be passed to the ``ext_proc`` service as a ``protobuf::Any``. This allows // envoy and the external processing server to share the protobuf message // definition for safe parsing. repeated string typed = 2; @@ -413,14 +441,15 @@ message ExtProcPerRoute { } // Overrides that may be set on a per-route basis -// [#next-free-field: 8] +// [#next-free-field: 10] message ExtProcOverrides { // Set a different processing mode for this route than the default. ProcessingMode processing_mode = 1; // [#not-implemented-hide:] // Set a different asynchronous processing option than the default. - bool async_mode = 2; + // Deprecated and not implemented. + bool async_mode = 2 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // [#not-implemented-hide:] // Set different optional attributes than the default setting of the @@ -442,9 +471,21 @@ message ExtProcOverrides { // most-specific config contains the correct final overrides. MetadataOptions metadata_options = 6; - // Additional metadata to include into streams initiated to the ext_proc gRPC + // Additional metadata to include into streams initiated to the ``ext_proc`` gRPC // service. This can be used for scenarios in which additional ad hoc // authorization headers (e.g. ``x-foo-bar: baz-key``) are to be injected or // when a route needs to partially override inherited metadata. repeated config.core.v3.HeaderValue grpc_initial_metadata = 7; + + // If true, the filter will not fail closed if the gRPC stream is prematurely closed + // or could not be opened. This field is the per-route override of + // :ref:`failure_mode_allow `. + google.protobuf.BoolValue failure_mode_allow = 8; + + // Decorator to introduce custom logic that runs after the ``ProcessingRequest`` is constructed, but + // before it is sent to the External Processor. The ``ProcessingRequest`` may be modified. + // This is a per-route override of + // :ref:`processing_request_modifier `. + config.core.v3.TypedExtensionConfig processing_request_modifier = 9 + [(xds.annotations.v3.field_status).work_in_progress = true]; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto b/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto index 467320d4a..5ad32af51 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto @@ -65,8 +65,7 @@ message ProcessingMode { // Do not send the body at all. This is the default. NONE = 0; - // Stream the body to the server in pieces as they arrive at the - // proxy. + // Stream the body to the server in pieces as they are seen. STREAMED = 1; // Buffer the message body in memory and send the entire body at once. @@ -79,11 +78,11 @@ message ProcessingMode { // up to the buffer limit will be sent. BUFFERED_PARTIAL = 3; - // Envoy streams the body to the server in pieces as they arrive. + // The ext_proc client (the data plane) streams the body to the server in pieces as they arrive. // // 1) The server may choose to buffer any number chunks of data before processing them. // After it finishes buffering, the server processes the buffered data. Then it splits the processed - // data into any number of chunks, and streams them back to Envoy one by one. + // data into any number of chunks, and streams them back to the ext_proc client one by one. // The server may continuously do so until the complete body is processed. // The individual response chunk size is recommended to be no greater than 64K bytes, or // :ref:`max_receive_message_length ` @@ -98,15 +97,15 @@ message ProcessingMode { // // In this body mode: // * The corresponding trailer mode has to be set to ``SEND``. - // * Envoy will send body and trailers (if present) to the server as they arrive. + // * The client will send body and trailers (if present) to the server as they arrive. // Sending the trailers (if present) is to inform the server the complete body arrives. - // In case there are no trailers, then Envoy will set + // In case there are no trailers, then the client will set // :ref:`end_of_stream ` // to true as part of the last body chunk request to notify the server that no other data is to be sent. // * The server needs to send // :ref:`StreamedBodyResponse ` - // to Envoy in the body response. - // * Envoy will stream the body chunks in the responses from the server to the upstream/downstream as they arrive. + // to the client in the body response. + // * The client will stream the body chunks in the responses from the server to the upstream/downstream as they arrive. FULL_DUPLEX_STREAMED = 4; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/grpc_json_reverse_transcoder/v3/transcoder.proto b/api/src/main/proto/envoy/extensions/filters/http/grpc_json_reverse_transcoder/v3/transcoder.proto index ddcae1ad8..f8dc4636a 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/grpc_json_reverse_transcoder/v3/transcoder.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/grpc_json_reverse_transcoder/v3/transcoder.proto @@ -17,7 +17,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // gRPC-JSON reverse transcoder :ref:`configuration overview `. // [#extension: envoy.filters.http.grpc_json_reverse_transcoder] -// [#next-free-field: 6] +// [#next-free-field: 7] // ``GrpcJsonReverseTranscoder`` is the filter configuration for the gRPC JSON // reverse transcoder. The reverse transcoder acts as a bridge between a gRPC // client and an HTTP/JSON server, converting the gRPC request into HTTP/JSON @@ -26,6 +26,68 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // :ref:`grpc_json_transcoder filter `, // allowing a gRPC client to communicate with an HTTP/JSON server. message GrpcJsonReverseTranscoder { + message PrintOptions { + // Whether to always print primitive fields. By default primitive + // fields with default values will be omitted in JSON output. For + // example, an int32 field set to 0 will be omitted. Setting this flag to + // true will override the default behavior and print primitive fields + // regardless of their values. Defaults to false. + bool always_print_primitive_fields = 1; + + // Whether to always print enums as ints. By default they are rendered + // as strings. Defaults to false. + bool always_print_enums_as_ints = 2; + + // Whether to convert the proto field names to ``json_name`` annotation value, or lower camel case, + // in absence of ``json_name``. By default the field names will be preserved after conversion. + // Setting this flag will convert the field names to their canonical form. Defaults to false. + // + // Example: + // + // .. code-block:: proto + // + // message Author { + // int64 id = 1; + // enum Gender { + // UNKNOWN = 0; + // MALE = 1; + // FEMALE = 2; + // }; + // Gender gender = 2; + // string first_name = 3; + // string last_name = 4 [json_name = "lname"]; + // } + // + // The above proto message after being transcoded to JSON with + // ``use_canonical_field_names`` set to ``false`` will have the + // field names same as in the proto message, as follows: + // + // .. code-block:: json + // + // { + // "id": "12345", + // "gender": "MALE", + // "first_name": "John", + // "last_name": "Doe" + // } + // + // and with the ``use_canonical_field_names`` set to ``true``, the + // transcoded JSON will have ``first_name`` converted to camelCase + // and ``last_name`` converted to its ``json_name`` annotation value, + // as follows: + // + // .. code-block:: json + // + // { + // "id": "12345", + // "gender": "MALE", + // "firstName": "John", + // "lname": "Doe" + // } + // + bool use_canonical_field_names = 3; + } + // Supplies the filename of // :ref:`the proto descriptor set // ` for the gRPC services. @@ -58,4 +120,9 @@ message GrpcJsonReverseTranscoder { // The name of the header field that has the API version of the request. string api_version_header = 5; + + // Control options for upstream request JSON. These options are passed directly to + // `JsonPrintOptions `_. + PrintOptions request_json_print_options = 6; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/grpc_json_transcoder/v3/transcoder.proto b/api/src/main/proto/envoy/extensions/filters/http/grpc_json_transcoder/v3/transcoder.proto index 4fcf1b98e..8562c9df1 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/grpc_json_transcoder/v3/transcoder.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/grpc_json_transcoder/v3/transcoder.proto @@ -47,7 +47,7 @@ message GrpcJsonTranscoder { ALL_CHARACTERS = 2; } - // [#next-free-field: 6] + // [#next-free-field: 7] message PrintOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions"; @@ -74,6 +74,11 @@ message GrpcJsonTranscoder { // If true, return all streams as newline-delimited JSON messages instead of as a comma-separated array bool stream_newline_delimited = 5; + + // If true, enforces Server-Sent Events (SSE) message framing (``data: + // \n\n``) and, ``stream_newline_delimited`` is ignored. If false, + // message framing is determined by ``stream_newline_delimited``. + bool stream_sse_style_delimited = 6; } message RequestValidationOptions { diff --git a/api/src/main/proto/envoy/extensions/filters/http/header_mutation/v3/header_mutation.proto b/api/src/main/proto/envoy/extensions/filters/http/header_mutation/v3/header_mutation.proto index ca951db82..6215eab83 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/header_mutation/v3/header_mutation.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/header_mutation/v3/header_mutation.proto @@ -14,8 +14,10 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/fil option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Header mutation filter configuration] +// Mutate HTTP headers and trailers in requests and responses. // [#extension: envoy.filters.http.header_mutation] +// [#next-free-field: 6] message Mutations { // The request mutations are applied before the request is forwarded to the upstream cluster. repeated config.common.mutation_rules.v3.HeaderMutation request_mutations = 1; @@ -26,6 +28,12 @@ message Mutations { // The response mutations are applied before the response is sent to the downstream client. repeated config.common.mutation_rules.v3.HeaderMutation response_mutations = 2; + + // The response trailer mutations are applied before the response is sent to the downstream client. + repeated config.common.mutation_rules.v3.HeaderMutation response_trailers_mutations = 4; + + // The request trailer mutations are applied before the request is sent to the upstream cluster. + repeated config.common.mutation_rules.v3.HeaderMutation request_trailers_mutations = 5; } // Per route configuration for the header mutation filter. diff --git a/api/src/main/proto/envoy/extensions/filters/http/header_to_metadata/v3/header_to_metadata.proto b/api/src/main/proto/envoy/extensions/filters/http/header_to_metadata/v3/header_to_metadata.proto index a34568c0e..662eefc4c 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/header_to_metadata/v3/header_to_metadata.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/header_to_metadata/v3/header_to_metadata.proto @@ -27,6 +27,7 @@ message Config { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.header_to_metadata.v2.Config"; + // Specifies the value type to use in metadata. enum ValueType { STRING = 0; @@ -37,14 +38,18 @@ message Config { PROTOBUF_VALUE = 2; } - // ValueEncode defines the encoding algorithm. + // Specifies the encoding scheme for the value. enum ValueEncode { - // The value is not encoded. + // No encoding is applied. NONE = 0; // The value is encoded in `Base64 `_. - // Note: this is mostly used for STRING and PROTOBUF_VALUE to escape the - // non-ASCII characters in the header. + // + // .. note:: + // + // This is mostly used for ``STRING`` and ``PROTOBUF_VALUE`` to escape the + // non-ASCII characters in the header. + // BASE64 = 1; } @@ -74,7 +79,10 @@ message Config { // // This is only used for :ref:`on_header_present `. // - // Note: if the ``value`` field is non-empty this field should be empty. + // .. note:: + // + // If the ``value`` field is non-empty this field should be empty. + // type.matcher.v3.RegexMatchAndSubstitute regex_value_rewrite = 6 [(udpa.annotations.field_migrate).oneof_promotion = "value_type"]; @@ -106,15 +114,15 @@ message Config { (udpa.annotations.field_migrate).oneof_promotion = "header_cookie_specifier" ]; - // If the header or cookie is present, apply this metadata KeyValuePair. + // If the header or cookie is present, apply this metadata ``KeyValuePair``. // - // If the value in the KeyValuePair is non-empty, it'll be used instead + // If the value in the ``KeyValuePair`` is non-empty, it'll be used instead // of the header or cookie value. KeyValuePair on_header_present = 2 [(udpa.annotations.field_migrate).rename = "on_present"]; - // If the header or cookie is not present, apply this metadata KeyValuePair. + // If the header or cookie is not present, apply this metadata ``KeyValuePair``. // - // The value in the KeyValuePair must be set, since it'll be used in lieu + // The value in the ``KeyValuePair`` must be set, since it'll be used in lieu // of the missing header or cookie value. KeyValuePair on_header_missing = 3 [(udpa.annotations.field_migrate).rename = "on_missing"]; @@ -130,4 +138,15 @@ message Config { // The list of rules to apply to responses. repeated Rule response_rules = 2; + + // Optional prefix to use when emitting filter statistics. When configured, + // statistics are emitted with the prefix ``http_filter_name.``. + // + // This emits statistics such as: + // + // - ``http_filter_name.my_header_converter.rules_processed`` + // - ``http_filter_name.my_header_converter.metadata_added`` + // + // If not configured, no statistics are emitted. + string stat_prefix = 3; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/local_ratelimit/v3/local_rate_limit.proto b/api/src/main/proto/envoy/extensions/filters/http/local_ratelimit/v3/local_rate_limit.proto index b0199c04b..8306adda2 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/local_ratelimit/v3/local_rate_limit.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/local_ratelimit/v3/local_rate_limit.proto @@ -130,6 +130,20 @@ message LocalRateLimit { // Defines the standard version to use for X-RateLimit headers emitted by the filter. // + // * ``X-RateLimit-Limit`` - indicates the request-quota associated to the + // client in the current time-window followed by the description of the + // quota policy. + // * ``X-RateLimit-Remaining`` - indicates the remaining requests in the + // current time-window. + // * ``X-RateLimit-Reset`` - indicates the number of seconds until reset of + // the current time-window. + // + // In case rate limiting policy specifies more then one time window, the values + // above represent the window that is closest to reaching its limit. + // + // For more information about the headers specification see selected version of + // the `draft RFC `_. + // // Disabled by default. common.ratelimit.v3.XRateLimitHeadersRFCVersion enable_x_ratelimit_headers = 12 [(validate.rules).enum = {defined_only: true}]; diff --git a/api/src/main/proto/envoy/extensions/filters/http/lua/v3/lua.proto b/api/src/main/proto/envoy/extensions/filters/http/lua/v3/lua.proto index c8b914999..115749e72 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/lua/v3/lua.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/lua/v3/lua.proto @@ -4,6 +4,7 @@ package envoy.extensions.filters.http.lua.v3; import "envoy/config/core/v3/base.proto"; +import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; import "envoy/annotations/deprecation.proto"; @@ -91,8 +92,6 @@ message Lua { message LuaPerRoute { oneof override { - option (validate.required) = true; - // Disable the Lua filter for this particular vhost or route. If disabled is specified in // multiple per-filter-configs, the most specific one will be used. bool disabled = 1 [(validate.rules).bool = {const: true}]; @@ -104,4 +103,18 @@ message LuaPerRoute { // A configured per-route Lua source code that can be served by RDS or provided inline. config.core.v3.DataSource source_code = 3; } + + // Optional filter context for Lua script. This could be used to pass configuration + // to Lua script. The Lua script can access the filter context using ``handle:filterContext()``. + // For example: + // + // .. code-block:: lua + // + // function envoy_on_request(request_handle) + // local filter_context = request_handle:filterContext() + // local filter_context_value = filter_context["key"] + // -- Do something with filter_context_value. + // end + // + google.protobuf.Struct filter_context = 4; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto b/api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto new file mode 100644 index 000000000..7c873fc2f --- /dev/null +++ b/api/src/main/proto/envoy/extensions/filters/http/mcp/v3/mcp.proto @@ -0,0 +1,24 @@ +syntax = "proto3"; + +package envoy.extensions.filters.http.mcp.v3; + +import "udpa/annotations/status.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; + +// [#protodoc-title: MCP] +// MCP filter :ref:`configuration overview `. +// [#extension: envoy.filters.http.mcp] + +message Mcp { + // TODO: Add configuration fields +} + +// McpOverride for MCP filter +message McpOverride { + // TODO: Add configuration fields +} diff --git a/api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto b/api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto index 90f4401e8..2354f2b92 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/oauth2/v3/oauth.proto @@ -126,7 +126,7 @@ message OAuth2Credentials { // OAuth config // -// [#next-free-field: 23] +// [#next-free-field: 27] message OAuth2Config { enum AuthType { // The ``client_id`` and ``client_secret`` will be sent in the URL encoded request body. @@ -146,6 +146,14 @@ message OAuth2Config { // The endpoint redirect to for authorization in response to unauthorized requests. string authorization_endpoint = 2 [(validate.rules).string = {min_len: 1}]; + // The endpoint at the authorization server to request the user be logged out of the Authorization server. + // This field is optional and should be set only if openid is in the auth_scopes and the authorization server + // supports the OpenID Connect RP-Initiated Logout specification. + // For more information, see https://openid.net/specs/openid-connect-rpinitiated-1_0.html + // + // If configured, the OAuth2 filter will redirect users to this endpoint when they access the signout_path. + string end_session_endpoint = 23; + // Credentials used for OAuth. OAuth2Credentials credentials = 3 [(validate.rules).message = {required: true}]; @@ -234,6 +242,23 @@ message OAuth2Config { // Optional additional prefix to use when emitting statistics. string stat_prefix = 22; + + // Optional expiration time for the CSRF protection token cookie. + // The CSRF token prevents cross-site request forgery attacks during the OAuth2 flow. + // If not specified, defaults to ``600s`` (10 minutes), which should provide sufficient time + // for users to complete the OAuth2 authorization flow. + google.protobuf.Duration csrf_token_expires_in = 24; + + // Optional expiration time for the code verifier cookie. + // The code verifier is stored in a secure, HTTP-only cookie during the OAuth2 authorization process. + // If not specified, defaults to ``600s`` (10 minutes), which should provide sufficient time + // for users to complete the OAuth2 authorization flow. + google.protobuf.Duration code_verifier_token_expires_in = 25; + + // Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text. + // This option should only be used in secure environments where token encryption is not required. + // Default is false (tokens are encrypted). + bool disable_token_encryption = 26; } // Filter config. diff --git a/api/src/main/proto/envoy/extensions/filters/http/on_demand/v3/on_demand.proto b/api/src/main/proto/envoy/extensions/filters/http/on_demand/v3/on_demand.proto index 93c9f76f8..3e23afe08 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/on_demand/v3/on_demand.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/on_demand/v3/on_demand.proto @@ -8,7 +8,6 @@ import "google/protobuf/duration.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; -import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.filters.http.on_demand.v3"; option java_outer_classname = "OnDemandProto"; @@ -29,7 +28,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; message OnDemandCds { // A configuration source for the service that will be used for // on-demand cluster discovery. - config.core.v3.ConfigSource source = 1 [(validate.rules).message = {required: true}]; + config.core.v3.ConfigSource source = 1; // xdstp:// resource locator for on-demand cluster collection. string resources_locator = 2; diff --git a/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto b/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto new file mode 100644 index 000000000..b41e0a416 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/config.proto @@ -0,0 +1,89 @@ +syntax = "proto3"; + +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"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.http.proto_api_scrubber.v3"; +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 +// response payloads based on the configured field restrictions and actions. +// 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 +// `here `_ + +message ProtoApiScrubberConfig { + // An enum enlisting all the filtering modes supported by this filter. + enum FilteringMode { + // Override the original request/response body with the filtered + // request/response body. + OVERRIDE = 0; + } + + // The proto descriptor set for the proto services. + DescriptorSet descriptor_set = 1; + + // Contains the restrictions for the supported proto elements. + Restrictions restrictions = 2; + + // Specifies the filtering mode of this filter. + FilteringMode filtering_mode = 3; +} + +// Specifies the descriptor set for proto services. +message DescriptorSet { + // It could be passed by a local file through ``Datasource.filename`` or + // embedded in the ``Datasource.inline_bytes``. + config.core.v3.DataSource data_source = 1; +} + +// Contains the restrictions for the methods. +message Restrictions { + // Specifies the method restrictions. + // Key - Fully qualified method name e.g., ``endpoints.examples.bookstore.BookStore/GetShelf``. + // Value - Method restrictions. + map method_restrictions = 1; +} + +// 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 + // 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 + // Value - Restrictions map containing the mapping from restriction name to + // the restriction values. + map response_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/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto b/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto new file mode 100644 index 000000000..a6f3c7eff --- /dev/null +++ b/api/src/main/proto/envoy/extensions/filters/http/proto_api_scrubber/v3/matcher_actions.proto @@ -0,0 +1,21 @@ +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"; +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] + +// Specifies an :ref:`Unified Matcher API ` action to remove a field. +// This actual action needs to be implemented by the filter using it. +message RemoveFieldAction { +} diff --git a/api/src/main/proto/envoy/extensions/filters/http/ratelimit/v3/rate_limit.proto b/api/src/main/proto/envoy/extensions/filters/http/ratelimit/v3/rate_limit.proto index f135424cb..5c5a9f3e0 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/ratelimit/v3/rate_limit.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/ratelimit/v3/rate_limit.proto @@ -23,7 +23,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Rate limit :ref:`configuration overview `. // [#extension: envoy.filters.http.ratelimit] -// [#next-free-field: 16] +// [#next-free-field: 18] message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.rate_limit.v2.RateLimit"; @@ -95,7 +95,7 @@ message RateLimit { // in :ref:`duration_until_reset` // field. // - // In case rate limiting policy specifies more then one time window, the values + // In case rate limiting policy specifies more than one time window, the values // above represent the window that is closest to reaching its limit. // // For more information about the headers specification see selected version of @@ -149,6 +149,43 @@ message RateLimit { // the fraction of requests to enforce rate limits on. And the default percentage of the // runtime key is 100% for backwards compatibility. config.core.v3.RuntimeFractionalPercent filter_enforced = 15; + + // If set, this will override the failure_mode_deny parameter with a runtime fraction. + // If the runtime key is not specified, the value of failure_mode_deny will be used. + // + // Example: + // + // .. code-block:: yaml + // + // failure_mode_deny: true + // failure_mode_deny_percent: + // default_value: + // numerator: 50 + // denominator: HUNDRED + // runtime_key: ratelimit.failure_mode_deny_percent + // + // This means that when the rate limit service is unavailable, 50% of requests will be denied + // (fail closed) and 50% will be allowed (fail open). + config.core.v3.RuntimeFractionalPercent failure_mode_deny_percent = 16; + + // Rate limit configuration that is used to generate a list of descriptor entries based on + // the request context. The generated entries will be sent to the rate limit service. + // If this is set, then + // :ref:`VirtualHost.rate_limits` or + // :ref:`RouteAction.rate_limits` fields + // will be ignored. However, :ref:`RateLimitPerRoute.rate_limits` + // will take precedence over this field. + // + // .. note:: + // Not all configuration fields of + // :ref:`rate limit config ` is supported at here. + // Following fields are not supported: + // + // 1. :ref:`rate limit stage `. + // 2. :ref:`dynamic metadata `. + // 3. :ref:`disable_key `. + // 4. :ref:`override limit `. + repeated config.route.v3.RateLimit rate_limits = 17; } message RateLimitPerRoute { @@ -192,8 +229,9 @@ message RateLimitPerRoute { // the request context. The generated entries will be used to find one or multiple matched rate // limit rule from the ``descriptors``. // If this is set, then - // :ref:`VirtualHost.rate_limits` or - // :ref:`RouteAction.rate_limits` fields + // :ref:`VirtualHost.rate_limits`, + // :ref:`RouteAction.rate_limits` and + // :ref:`RateLimit.rate_limits` fields // will be ignored. // // .. note:: diff --git a/api/src/main/proto/envoy/extensions/filters/http/stateful_session/v3/stateful_session.proto b/api/src/main/proto/envoy/extensions/filters/http/stateful_session/v3/stateful_session.proto index 5cef3fc71..b3e5e53af 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/stateful_session/v3/stateful_session.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/stateful_session/v3/stateful_session.proto @@ -29,6 +29,15 @@ message StatefulSession { // which allows Envoy to fall back to its load balancing mechanism. In this case, if the requested destination is not // found, the request will be routed according to the load balancing algorithm. bool strict = 2; + + // Optional stat prefix. If specified, the filter will emit statistics in the + // ``http..stateful_session..`` namespace. If not specified, no statistics will be emitted. + // + // .. note:: + // + // Per-route configuration overrides do not support statistics and will not emit stats even if this field is set + // in the per-route config. + string stat_prefix = 3; } message StatefulSessionPerRoute { diff --git a/api/src/main/proto/envoy/extensions/filters/http/tap/v3/tap.proto b/api/src/main/proto/envoy/extensions/filters/http/tap/v3/tap.proto index 0ed35de97..0c12c3f60 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/tap/v3/tap.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/tap/v3/tap.proto @@ -34,4 +34,7 @@ message Tap { // Indicates whether report downstream connection info bool record_downstream_connection = 3; + + // If enabled, upstream connection information will be reported. + bool record_upstream_connection = 4; } diff --git a/api/src/main/proto/envoy/extensions/filters/http/thrift_to_metadata/v3/thrift_to_metadata.proto b/api/src/main/proto/envoy/extensions/filters/http/thrift_to_metadata/v3/thrift_to_metadata.proto index 59dad1b7f..204f02f43 100644 --- a/api/src/main/proto/envoy/extensions/filters/http/thrift_to_metadata/v3/thrift_to_metadata.proto +++ b/api/src/main/proto/envoy/extensions/filters/http/thrift_to_metadata/v3/thrift_to_metadata.proto @@ -69,8 +69,6 @@ message KeyValuePair { } message FieldSelector { - option (xds.annotations.v3.message_status).work_in_progress = true; - // field name to log string name = 1 [(validate.rules).string = {min_len: 1}]; @@ -83,7 +81,9 @@ message FieldSelector { // [#next-free-field: 6] message Rule { - // The field to match on. If set, takes precedence over field_selector. + // The field to match on. + // :ref:`field_selector` + // takes precedence if both are set. Field field = 1; // Specifies that a match will be performed on the value of a field in the thrift body. @@ -123,11 +123,11 @@ message Rule { // bool bar(1: i32 id, 2: Info info); // } // - FieldSelector field_selector = 2 [(xds.annotations.v3.field_status).work_in_progress = true]; + FieldSelector field_selector = 2; // If specified, :ref:`field_selector` // will be used to extract the field value *only* on the thrift message with method name. - string method_name = 3 [(xds.annotations.v3.field_status).work_in_progress = true]; + string method_name = 3; // The key-value pair to set in the *filter metadata* if the field is present // in *thrift metadata*. diff --git a/api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto b/api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto index db2d07c8d..b4fe6d72f 100644 --- a/api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto +++ b/api/src/main/proto/envoy/extensions/filters/listener/tls_inspector/v3/tls_inspector.proto @@ -25,11 +25,27 @@ message TlsInspector { // Populate ``JA3`` fingerprint hash using data from the TLS Client Hello packet. Default is false. google.protobuf.BoolValue enable_ja3_fingerprinting = 1; + // Populate ``JA4`` fingerprint hash using data from the TLS Client Hello packet. + // ``JA4`` is an improved version of ``JA3`` that includes TLS version, ciphers, extensions, + // and ALPN information in a hex format. Default is false. + google.protobuf.BoolValue enable_ja4_fingerprinting = 3; + // The size in bytes of the initial buffer requested by the tls_inspector. // If the filter needs to read additional bytes from the socket, the - // filter will double the buffer up to it's default maximum of 64KiB. - // If this size is not defined, defaults to maximum 64KiB that the + // filter will double the buffer up to it's default maximum of 16KiB. + // If this size is not defined, defaults to maximum 16KiB that the // tls inspector will consume. google.protobuf.UInt32Value initial_read_buffer_size = 2 [(validate.rules).uint32 = {lt: 65537 gt: 255}]; + + // Close connection when TLS ClientHello message could not be parsed. + // This flag should be enabled only if it is known that incoming connections are expected to use + // TLS protocol, as Envoy does not distinguish between a plain text message or a malformed TLS + // ClientHello message. + // By default this flag is false and TLS ClientHello parsing errors are interpreted as a + // plain text connection. + // Setting this to true will cause connections to be terminated and the ``client_hello_too_large`` + // counter to be incremented if the ClientHello message is over implementation defined limit + // (currently 16Kb). + bool close_connection_on_client_hello_parsing_errors = 4; } diff --git a/api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto b/api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto index afd0197de..fb447f690 100644 --- a/api/src/main/proto/envoy/extensions/filters/network/ext_authz/v3/ext_authz.proto +++ b/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: 9] +// [#next-free-field: 10] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.ext_authz.v2.ExtAuthz"; @@ -68,4 +68,12 @@ message ExtAuthz { // When this field is true, Envoy will include the SNI name used for TLSClientHello, if available, in the // :ref:`tls_session`. bool include_tls_session = 8; + + // When set to ``true``, the filter will send a TLS ``access_denied(49)`` alert before closing + // the connection when authorization is denied. This provides better visibility to TLS clients + // about the reason for connection closure. This alert is only sent for TLS connections. The + // non-TLS connections will be closed without sending an alert. + // + // Defaults to ``false``. + bool send_tls_alert_on_denial = 9; } diff --git a/api/src/main/proto/envoy/extensions/filters/network/ext_proc/v3/ext_proc.proto b/api/src/main/proto/envoy/extensions/filters/network/ext_proc/v3/ext_proc.proto index d79f80c49..f37feaa94 100644 --- a/api/src/main/proto/envoy/extensions/filters/network/ext_proc/v3/ext_proc.proto +++ b/api/src/main/proto/envoy/extensions/filters/network/ext_proc/v3/ext_proc.proto @@ -27,12 +27,14 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // this filter operates at the L4 (transport) layer, giving access to raw network traffic. // // The filter communicates with an external gRPC service that can: -// * Inspect traffic in both directions -// * Modify the network traffic -// * Control connection lifecycle (continue, close, or reset) +// +// 1. Inspect traffic in both directions +// 2. Modify the network traffic +// 3. Control connection lifecycle (continue, close, or reset) // // By using the filter's processing mode, you can selectively choose which data // directions to process (read, write or both), allowing for efficient processing. +// [#next-free-field: 7] message NetworkExternalProcessor { // The gRPC service that will process network traffic. // This service must implement the NetworkExternalProcessor service @@ -43,11 +45,9 @@ message NetworkExternalProcessor { // prematurely with an error, the filter will fail, leading to the close of connection. // With this parameter set to true, however, then if the gRPC stream is prematurely closed // or could not be opened, processing continues without error. - // [#not-implemented-hide:] bool failure_mode_allow = 2; // Options for controlling processing behavior. - // [#not-implemented-hide:] ProcessingMode processing_mode = 3; // Specifies the timeout for each individual message sent on the stream and @@ -55,11 +55,15 @@ message NetworkExternalProcessor { // the proxy sends a message on the stream that requires a response, it will // reset this timer, and will stop processing and return an error (subject // to the processing mode) if the timer expires. Default is 200 ms. - // [#not-implemented-hide:] google.protobuf.Duration message_timeout = 4 [(validate.rules).duration = { lte {seconds: 3600} gte {} }]; + + string stat_prefix = 5 [(validate.rules).string = {min_len: 1}]; + + // Options related to the sending and receiving of dynamic metadata. + MetadataOptions metadata_options = 6; } // Options for controlling processing behavior. @@ -82,3 +86,23 @@ message ProcessingMode { // Default: STREAMED DataSendMode process_write = 2; } + +// The MetadataOptions structure defines options for sending dynamic metadata. Specifically, +// which namespaces to send to the server. +message MetadataOptions { + message MetadataNamespaces { + // Specifies a list of metadata namespaces whose values, if present, + // will be passed to the ext_proc service as an opaque *protobuf::Struct*. + repeated string untyped = 1; + + // Specifies a list of metadata namespaces whose values, if present, + // will be passed to the ext_proc service as a *protobuf::Any*. This allows + // envoy and the external processing server to share the protobuf message + // definition for safe parsing. + repeated string typed = 2; + } + + // Describes which typed or untyped dynamic metadata namespaces to forward to + // the external processing server. + MetadataNamespaces forwarding_namespaces = 1; +} diff --git a/api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index ce549d6a9..730e065e6 100644 --- a/api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/api/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -37,7 +37,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: 59] +// [#next-free-field: 60] message HttpConnectionManager { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"; @@ -99,33 +99,43 @@ message HttpConnectionManager { ALWAYS_FORWARD_ONLY = 4; } - // Determines the action for request that contain %2F, %2f, %5C or %5c sequences in the URI path. + // Determines the action for request that contain ``%2F``, ``%2f``, ``%5C`` or ``%5c`` sequences in the URI path. // This operation occurs before URL normalization and the merge slashes transformations if they were enabled. enum PathWithEscapedSlashesAction { // Default behavior specific to implementation (i.e. Envoy) of this configuration option. // Envoy, by default, takes the KEEP_UNCHANGED action. - // NOTE: the implementation may change the default behavior at-will. + // + // .. note:: + // + // The implementation may change the default behavior at-will. IMPLEMENTATION_SPECIFIC_DEFAULT = 0; // Keep escaped slashes. KEEP_UNCHANGED = 1; // Reject client request with the 400 status. gRPC requests will be rejected with the INTERNAL (13) error code. - // The "httpN.downstream_rq_failed_path_normalization" counter is incremented for each rejected request. + // The ``httpN.downstream_rq_failed_path_normalization`` counter is incremented for each rejected request. REJECT_REQUEST = 2; - // Unescape %2F and %5C sequences and redirect request to the new path if these sequences were present. + // Unescape ``%2F`` and ``%5C`` sequences and redirect request to the new path if these sequences were present. // Redirect occurs after path normalization and merge slashes transformations if they were configured. - // NOTE: gRPC requests will be rejected with the INTERNAL (13) error code. - // This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to - // traverse all parties: downstream client, intermediate proxies, Envoy and upstream server. - // The "httpN.downstream_rq_redirected_with_normalized_path" counter is incremented for each - // redirected request. + // + // .. note:: + // + // gRPC requests will be rejected with the INTERNAL (13) error code. This option minimizes possibility of path + // confusion exploits by forcing request with unescaped slashes to traverse all parties: downstream client, + // intermediate proxies, Envoy and upstream server. The ``httpN.downstream_rq_redirected_with_normalized_path`` + // counter is incremented for each redirected request. + // UNESCAPE_AND_REDIRECT = 3; - // Unescape %2F and %5C sequences. - // Note: this option should not be enabled if intermediaries perform path based access control as - // it may lead to path confusion vulnerabilities. + // Unescape ``%2F`` and ``%5C`` sequences. + // + // .. note:: + // + // This option should not be enabled if intermediaries perform path based access control as it may lead to path + // confusion vulnerabilities. + // UNESCAPE_AND_FORWARD = 4; } @@ -258,13 +268,12 @@ message HttpConnectionManager { // // .. warning:: // - // The current implementation of upgrade headers does not handle - // multi-valued upgrade headers. Support for multi-valued headers may be - // added in the future if needed. + // The current implementation of upgrade headers does not handle multi-valued upgrade headers. Support for + // multi-valued headers may be added in the future if needed. // // .. warning:: - // The current implementation of upgrade headers does not work with HTTP/2 - // upstreams. + // The current implementation of upgrade headers does not work with HTTP/2 upstreams. + // message UpgradeConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager." @@ -296,7 +305,10 @@ message HttpConnectionManager { // `) will apply to the ``:path`` header // destined for the upstream. // - // Note: access logging and tracing will show the original ``:path`` header. + // .. note:: + // + // Access logging and tracing will show the original ``:path`` header. + // message PathNormalizationOptions { // [#not-implemented-hide:] Normalization applies internally before any processing of requests by // HTTP filters, routing, and matching *and* will affect the forwarded ``:path`` header. Defaults @@ -434,23 +446,23 @@ message HttpConnectionManager { Tracing tracing = 7; // Additional settings for HTTP requests handled by the connection manager. These will be - // applicable to both HTTP1 and HTTP2 requests. + // applicable to both HTTP/1.1 and HTTP/2 requests. config.core.v3.HttpProtocolOptions common_http_protocol_options = 35 [(udpa.annotations.security).configure_for_untrusted_downstream = true]; - // If set to true, Envoy will not start a drain timer for downstream HTTP1 connections after - // :ref:`common_http_protocol_options.max_connection_duration - // ` passes. - // Instead, Envoy will wait for the next downstream request, add connection:close to the response - // headers, then close the connection after the stream ends. + // If set to ``true``, Envoy will not initiate an immediate drain timer for downstream HTTP/1 connections + // once :ref:`common_http_protocol_options.max_connection_duration + // ` is exceeded. + // Instead, Envoy will wait until the next downstream request arrives, add a ``connection: close`` header + // to the response, and then gracefully close the connection once the stream has completed. // - // This behavior is compliant with `RFC 9112 section 9.6 `_ + // This behavior adheres to `RFC 9112, Section 9.6 `_. // - // If set to false, ``max_connection_duration`` will cause Envoy to enter the normal drain - // sequence for HTTP1 with Envoy eventually closing the connection (once there are no active - // streams). + // If set to ``false``, exceeding ``max_connection_duration`` triggers Envoy's default drain behavior for HTTP/1, + // where the connection is eventually closed after all active streams finish. // - // Has no effect if ``max_connection_duration`` is unset. Defaults to false. + // This option has no effect if ``max_connection_duration`` is not configured. + // Defaults to ``false``. bool http1_safe_max_connection_duration = 58; // Additional HTTP/1 settings that are passed to the HTTP/1 codec. @@ -488,9 +500,13 @@ message HttpConnectionManager { // The default value can be overridden by setting runtime key ``envoy.reloadable_features.max_request_headers_size_kb``. // Requests that exceed this limit will receive a 431 response. // - // Note: 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. + // .. note:: + // + // 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. + // google.protobuf.UInt32Value max_request_headers_kb = 29 [(validate.rules).uint32 = {lte: 8192 gt: 0}]; @@ -511,16 +527,6 @@ message HttpConnectionManager { // is terminated with a 408 Request Timeout error code if no upstream response // header has been received, otherwise a stream reset occurs. // - // This timeout also specifies the amount of time that Envoy will wait for the peer to open enough - // window to write any remaining stream data once the entirety of stream data (local end stream is - // true) has been buffered pending available window. In other words, this timeout defends against - // a peer that does not release enough window to completely write the stream, even though all - // data has been proxied within available flow control windows. If the timeout is hit in this - // case, the :ref:`tx_flush_timeout ` counter will be - // incremented. Note that :ref:`max_stream_duration - // ` does not apply to - // this corner case. - // // If the :ref:`overload action ` "envoy.overload_actions.reduce_timeouts" // is configured, this timeout is scaled according to the value for // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE `. @@ -533,9 +539,29 @@ message HttpConnectionManager { // // A value of 0 will completely disable the connection manager stream idle // timeout, although per-route idle timeout overrides will continue to apply. + // + // This timeout is also used as the default value for :ref:`stream_flush_timeout + // `. google.protobuf.Duration stream_idle_timeout = 24 [(udpa.annotations.security).configure_for_untrusted_downstream = true]; + // The stream flush timeout for connections managed by the connection manager. + // + // If not specified, the value of stream_idle_timeout is used. This is for backwards compatibility + // since this was the original behavior. In essence this timeout is an override for the + // stream_idle_timeout that applies specifically to the end of stream flush case. + // + // This timeout specifies the amount of time that Envoy will wait for the peer to open enough + // window to write any remaining stream data once the entirety of stream data (local end stream is + // true) has been buffered pending available window. In other words, this timeout defends against + // a peer that does not release enough window to completely write the stream, even though all + // data has been proxied within available flow control windows. If the timeout is hit in this + // case, the :ref:`tx_flush_timeout ` counter will be + // incremented. Note that :ref:`max_stream_duration + // ` does not apply to + // this corner case. + google.protobuf.Duration stream_flush_timeout = 59; + // The amount of time that Envoy will wait for the entire request to be received. // The timer is activated when the request is initiated, and is disarmed when the last byte of the // request is sent upstream (i.e. all decoding filters have processed the request), OR when the @@ -568,31 +594,34 @@ message HttpConnectionManager { // during which Envoy will wait for the peer to close (i.e., a TCP FIN/RST is received by Envoy // from the downstream connection) prior to Envoy closing the socket associated with that // connection. - // NOTE: This timeout is enforced even when the socket associated with the downstream connection - // is pending a flush of the write buffer. However, any progress made writing data to the socket - // will restart the timer associated with this timeout. This means that the total grace period for - // a socket in this state will be - // +. + // + // .. note:: + // + // This timeout is enforced even when the socket associated with the downstream connection is pending a flush of + // the write buffer. However, any progress made writing data to the socket will restart the timer associated with + // this timeout. This means that the total grace period for a socket in this state will be + // +. // // Delaying Envoy's connection close and giving the peer the opportunity to initiate the close // sequence mitigates a race condition that exists when downstream clients do not drain/process // data in a connection's receive buffer after a remote close has been detected via a socket - // write(). This race leads to such clients failing to process the response code sent by Envoy, + // ``write()``. This race leads to such clients failing to process the response code sent by Envoy, // which could result in erroneous downstream processing. // // If the timeout triggers, Envoy will close the connection's socket. // // The default timeout is 1000 ms if this option is not specified. // - // .. NOTE:: + // .. note:: // To be useful in avoiding the race condition described above, this timeout must be set // to *at least* +<100ms to account for // a reasonable "worst" case processing time for a full iteration of Envoy's event loop>. // - // .. WARNING:: - // A value of 0 will completely disable delayed close processing. When disabled, the downstream + // .. warning:: + // A value of ``0`` will completely disable delayed close processing. When disabled, the downstream // connection's socket will be closed immediately after the write flush is completed or will // never close if the write flush does not complete. + // google.protobuf.Duration delayed_close_timeout = 26; // Configuration for :ref:`HTTP access logs ` @@ -649,20 +678,19 @@ message HttpConnectionManager { // :ref:`config_http_conn_man_headers_x-forwarded-for` for more information. uint32 xff_num_trusted_hops = 19; - // The configuration for the original IP detection extensions. + // Configuration for original IP detection extensions. // - // When configured the extensions will be called along with the request headers - // and information about the downstream connection, such as the directly connected address. - // Each extension will then use these parameters to decide the request's effective remote address. - // If an extension fails to detect the original IP address and isn't configured to reject - // the request, the HCM will try the remaining extensions until one succeeds or rejects - // the request. If the request isn't rejected nor any extension succeeds, the HCM will - // fallback to using the remote address. + // When these extensions are configured, Envoy will invoke them with the incoming request headers and + // details about the downstream connection, including the directly connected address. Each extension uses + // this information to determine the effective remote IP address for the request. If an extension cannot + // identify the original IP address and isn't set to reject the request, Envoy will sequentially attempt + // the remaining extensions until one successfully determines the IP or explicitly rejects the request. + // If all extensions fail without rejection, Envoy defaults to using the directly connected remote address. // - // .. WARNING:: - // Extensions cannot be used in conjunction with :ref:`use_remote_address + // .. warning:: + // These extensions cannot be configured simultaneously with :ref:`use_remote_address // ` - // nor :ref:`xff_num_trusted_hops + // or :ref:`xff_num_trusted_hops // `. // // [#extension-category: envoy.http.original_ip_detection] @@ -1018,7 +1046,7 @@ message Rds { "envoy.config.filter.network.http_connection_manager.v2.Rds"; // Configuration source specifier for RDS. - config.core.v3.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; + config.core.v3.ConfigSource config_source = 1; // The name of the route configuration. This name will be passed to the RDS // API. This allows an Envoy configuration with multiple HTTP listeners (and diff --git a/api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto b/api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto index 21c87a12e..40cc2858d 100644 --- a/api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto +++ b/api/src/main/proto/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto @@ -4,6 +4,7 @@ package envoy.extensions.filters.network.redis_proxy.v3; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/grpc_service.proto"; +import "envoy/extensions/common/aws/v3/credential_provider.proto"; import "envoy/extensions/common/dynamic_forward_proxy/v3/dns_cache.proto"; import "google/protobuf/duration.proto"; @@ -381,11 +382,42 @@ message RedisProtocolOptions { // Upstream server password as defined by the ``requirepass`` directive // ``_ in the server's configuration file. + // If ``aws_iam`` is set, this field is ignored. config.core.v3.DataSource auth_password = 1 [(udpa.annotations.sensitive) = true]; // Upstream server username as defined by the ``user`` directive // ``_ in the server's configuration file. + // If ``aws_iam``` is set, this field will be used as the authenticating user for redis IAM authentication. + // See ``Create a new IAM-enabled user`` under `Setup `_ for more details. config.core.v3.DataSource auth_username = 2 [(udpa.annotations.sensitive) = true]; + + // The cluster level configuration for AWS IAM authentication + AwsIam aws_iam = 3; +} + +// [#next-free-field: 6] +message AwsIam { + // An AwsCredentialProvider, allowing the use of a specific credential provider chain or specific provider settings + common.aws.v3.AwsCredentialProvider credential_provider = 1; + + // The name of the cache, used when generating the authentication token. + string cache_name = 2 [(validate.rules).string = {min_len: 1}]; + + // The optional service name to be used in AWS IAM authentication. If not provided, the service name will be set to ``elasticache``. For Amazon MemoryDB + // the service name should be set to ``memorydb``. + string service_name = 3; + + // The optional AWS region that your cache is located in. If not provided, the region will be deduced using the region provider chain + // as described in :ref:`config_http_filters_aws_request_signing_region`. + string region = 4; + + // Number of seconds before the IAM authentication token will expire. If not set, defaults to 60s (1 minute). Maximum of 900s (15 minutes) + // Expiration of the current authentication token will automatically trigger generation of a new token. + // As envoy will automatically continue to generate new tokens as required, there is no substantial benefit to using a long expiration value here. + google.protobuf.Duration expiration_time = 5 [(validate.rules).duration = { + lte {seconds: 900} + gte {} + }]; } // RedisExternalAuthProvider specifies a gRPC service that can be used to authenticate Redis clients. diff --git a/api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto b/api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto new file mode 100644 index 000000000..28bcfe2c9 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/filters/network/reverse_tunnel/v3/reverse_tunnel.proto @@ -0,0 +1,116 @@ +syntax = "proto3"; + +package envoy.extensions.filters.network.reverse_tunnel.v3; + +import "envoy/config/core/v3/base.proto"; + +import "google/protobuf/duration.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.filters.network.reverse_tunnel.v3"; +option java_outer_classname = "ReverseTunnelProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/reverse_tunnel/v3;reverse_tunnelv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Reverse Tunnel Network Filter] +// Reverse Tunnel Network Filter :ref:`configuration overview `. +// [#extension: envoy.filters.network.reverse_tunnel] + +// Validation configuration for reverse tunnel identifiers. +// Validates the node ID and cluster ID extracted from reverse tunnel handshake headers +// against expected values specified using format strings. +message Validation { + // Format string to extract the expected node identifier for validation. + // The formatted value is compared against the ``x-envoy-reverse-tunnel-node-id`` header + // from the incoming handshake request. If they do not match, the connection is rejected + // with HTTP ``403 Forbidden``. + // + // Supports Envoy's :ref:`command operators `: + // + // * ``%DYNAMIC_METADATA(namespace:key)%``: Extract expected value from dynamic metadata. + // * ``%FILTER_STATE(key)%``: Extract expected value from filter state. + // * ``%DOWNSTREAM_REMOTE_ADDRESS%``: Use downstream connection IP address. + // * Plain strings: Use a static expected value. + // + // If empty, node ID validation is skipped. + // + // Example using dynamic metadata allowlist: + // + // .. code-block:: yaml + // + // node_id_format: "%DYNAMIC_METADATA(envoy.reverse_tunnel.allowlist:expected_node_id)%" + // + string node_id_format = 1 [(validate.rules).string = {max_len: 1024}]; + + // Format string to extract the expected cluster identifier for validation. + // The formatted value is compared against the ``x-envoy-reverse-tunnel-cluster-id`` header + // from the incoming handshake request. If they do not match, the connection is rejected + // with HTTP ``403 Forbidden``. + // + // Supports the same :ref:`command operators ` as + // ``node_id_format``. + // + // If empty, cluster ID validation is skipped. + // + // Example using filter state: + // + // .. code-block:: yaml + // + // cluster_id_format: "%FILTER_STATE(expected_cluster_id)%" + // + string cluster_id_format = 2 [(validate.rules).string = {max_len: 1024}]; + + // Whether to emit validation results as dynamic metadata. + // When enabled, the filter emits metadata under the namespace specified by + // ``dynamic_metadata_namespace`` containing: + // + // * ``node_id``: The actual node ID from the handshake request. + // * ``cluster_id``: The actual cluster ID from the handshake request. + // * ``validation_result``: Either ``allowed`` or ``denied``. + // + // This metadata can be used by subsequent filters or for access logging. + // Defaults to ``false``. + bool emit_dynamic_metadata = 3; + + // Namespace for emitted dynamic metadata when ``emit_dynamic_metadata`` is ``true``. + // If not specified, defaults to ``envoy.filters.network.reverse_tunnel``. + string dynamic_metadata_namespace = 4 [(validate.rules).string = {max_len: 255}]; +} + +// 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] +message ReverseTunnel { + // Ping interval for health checks on established reverse tunnel connections. + // If not specified, defaults to ``2 seconds``. + google.protobuf.Duration ping_interval = 1 [(validate.rules).duration = { + lte {seconds: 300} + gte {nanos: 1000000} + }]; + + // Whether to automatically close connections after processing reverse tunnel requests. + // + // * When set to ``true``, connections are closed after acceptance or rejection. + // * When set to ``false``, connections remain open for potential reuse. + // + // Defaults to ``false``. + bool auto_close_connections = 2; + + // HTTP path to match for reverse tunnel requests. + // If not specified, defaults to ``/reverse_connections/request``. + string request_path = 3 [(validate.rules).string = {min_len: 1 max_len: 255 ignore_empty: true}]; + + // HTTP method to match for reverse tunnel requests. + // If not specified (``METHOD_UNSPECIFIED``), this defaults to ``GET``. + config.core.v3.RequestMethod request_method = 4 [(validate.rules).enum = {defined_only: true}]; + + // Optional validation configuration for node and cluster identifiers. + // If specified, the filter validates the ``x-envoy-reverse-tunnel-node-id`` and + // ``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; +} diff --git a/api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto b/api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto index f4d57c969..ad47303d1 100644 --- a/api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto +++ b/api/src/main/proto/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto @@ -7,7 +7,9 @@ import "envoy/config/core/v3/backoff.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/config_source.proto"; import "envoy/config/core/v3/proxy_protocol.proto"; +import "envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"; import "envoy/type/v3/hash_policy.proto"; +import "envoy/type/v3/percent.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; @@ -27,14 +29,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // TCP Proxy :ref:`configuration overview `. // [#extension: envoy.filters.network.tcp_proxy] -// [#next-free-field: 20] +// [#next-free-field: 21] message TcpProxy { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.tcp_proxy.v2.TcpProxy"; - // Allows for specification of multiple upstream clusters along with weights - // that indicate the percentage of traffic to be forwarded to each cluster. - // The router selects an upstream cluster based on these weights. + // Allows specification of multiple upstream clusters along with weights indicating the percentage of + // traffic forwarded to each cluster. The cluster selection is based on these weights. message WeightedCluster { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster"; @@ -60,29 +61,29 @@ message TcpProxy { config.core.v3.Metadata metadata_match = 3; } - // Specifies one or more upstream clusters associated with the route. + // Specifies the upstream clusters associated with this configuration. repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; } // Configuration for tunneling TCP over other transports or application layers. - // Tunneling is supported over both HTTP/1.1 and HTTP/2. Upstream protocol is + // Tunneling is supported over HTTP/1.1 and HTTP/2. The upstream protocol is // determined by the cluster configuration. - // [#next-free-field: 7] + // [#next-free-field: 10] message TunnelingConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.tcp_proxy.v2.TcpProxy.TunnelingConfig"; // The hostname to send in the synthesized CONNECT headers to the upstream proxy. - // This field evaluates command operators if set, otherwise returns hostname as is. + // This field evaluates command operators if present; otherwise, the value is used as-is. // - // Example: dynamically set hostname using downstream SNI + // For example, dynamically set the hostname using downstream SNI: // // .. code-block:: yaml // // tunneling_config: // hostname: "%REQUESTED_SERVER_NAME%:443" // - // Example: dynamically set hostname using dynamic metadata + // For example, dynamically set the hostname using dynamic metadata: // // .. code-block:: yaml // @@ -91,62 +92,92 @@ message TcpProxy { // string hostname = 1 [(validate.rules).string = {min_len: 1}]; - // Use POST method instead of CONNECT method to tunnel the TCP stream. - // The 'protocol: bytestream' header is also NOT set for HTTP/2 to comply with the spec. + // Use the ``POST`` method instead of the ``CONNECT`` method to tunnel the TCP stream. + // The ``protocol: bytestream`` header is not set for HTTP/2 to comply with the specification. // - // The upstream proxy is expected to convert POST payload as raw TCP. + // The upstream proxy is expected to interpret the POST payload as raw TCP. bool use_post = 2; - // Additional request headers to upstream proxy. This is mainly used to - // trigger upstream to convert POST requests back to CONNECT requests. + // Additional request headers to send to the upstream proxy. This is mainly used to + // trigger the upstream to convert POST requests back to CONNECT requests. // - // Neither ``:-prefixed`` pseudo-headers nor the Host: header can be overridden. + // Neither ``:``-prefixed pseudo-headers like ``:path`` nor the ``host`` header can be overridden. repeated config.core.v3.HeaderValueOption headers_to_add = 3 [(validate.rules).repeated = {max_items: 1000}]; - // Save the response headers to the downstream info filter state for consumption - // by the network filters. The filter state key is ``envoy.tcp_proxy.propagate_response_headers``. + // Save response headers to the downstream connection's filter state for consumption + // by network filters. The filter state key is ``envoy.tcp_proxy.propagate_response_headers``. bool propagate_response_headers = 4; - // The path used with POST method. Default path is ``/``. If post path is specified and + // The path used with the POST method. The default path is ``/``. If this field is specified and // :ref:`use_post field ` - // isn't true, it will be rejected. + // is not set to true, the configuration will be rejected. string post_path = 5; - // Save the response trailers to the downstream info filter state for consumption - // by the network filters. The filter state key is ``envoy.tcp_proxy.propagate_response_trailers``. + // Save response trailers to the downstream connection's filter state for consumption + // by network filters. The filter state key is ``envoy.tcp_proxy.propagate_response_trailers``. bool propagate_response_trailers = 6; + + // The configuration of the request ID extension used for generation, validation, and + // associated tracing operations when tunneling. + // + // If this field is set, a request ID is generated using the specified extension. If + // this field is not set, no request ID is generated. + // + // When a request ID is generated, it is also stored in the downstream connection's + // dynamic metadata under the namespace ``envoy.filters.network.tcp_proxy`` with the key + // ``tunnel_request_id`` to allow emission from TCP proxy access logs via the + // ``%DYNAMIC_METADATA(envoy.filters.network.tcp_proxy:tunnel_request_id)%`` formatter. + // [#extension-category: envoy.request_id] + http_connection_manager.v3.RequestIDExtension request_id_extension = 7; + + // The request header name to use for emitting the generated request ID on the tunneling + // HTTP request. + // + // If not specified or set to an empty string, the default header name ``x-request-id`` is + // used. + // + // .. note:: + // This setting does not alter the internal request ID handling elsewhere in Envoy and + // only controls the header emitted on the tunneling request. + string request_id_header = 8; + + // The dynamic metadata key to use when storing the generated request ID. The metadata is + // stored under the namespace ``envoy.filters.network.tcp_proxy``. + // + // If not specified or set to an empty string, the default key ``tunnel_request_id`` is used. + // This enables customizing the key used by access log formatters such as + // ``%DYNAMIC_METADATA(envoy.filters.network.tcp_proxy:)%``. + string request_id_metadata_key = 9; } message OnDemand { - // An optional configuration for on-demand cluster discovery - // service. If not specified, the on-demand cluster discovery will - // be disabled. When it's specified, the filter will pause a request - // to an unknown cluster and will begin a cluster discovery - // process. When the discovery is finished (successfully or not), - // the request will be resumed. + // Optional configuration for the on-demand cluster discovery service. + // If not specified, on-demand cluster discovery is disabled. When specified, the filter pauses a request + // to an unknown cluster and begins a cluster discovery process. When discovery completes (successfully + // or not), the request is resumed. config.core.v3.ConfigSource odcds_config = 1; // xdstp:// resource locator for on-demand cluster collection. // [#not-implemented-hide:] string resources_locator = 2; - // The timeout for on demand cluster lookup. If the CDS cannot return the required cluster, + // The timeout for on-demand cluster lookup. If the CDS cannot return the required cluster, // the downstream request will be closed with the error code detail NO_CLUSTER_FOUND. // [#not-implemented-hide:] google.protobuf.Duration timeout = 3; } message TcpAccessLogOptions { - // The interval to flush access log. The TCP proxy will flush only one access log when the connection - // is closed by default. If this field is set, the TCP proxy will flush access log periodically with - // the specified interval. + // The interval for flushing access logs. By default, the TCP proxy flushes a single access log when the + // connection is closed. If this field is set, the TCP proxy flushes access logs periodically at the + // specified interval. // The interval must be at least 1ms. google.protobuf.Duration access_log_flush_interval = 1 [(validate.rules).duration = {gte {nanos: 1000000}}]; - // If set to true, access log will be flushed when the TCP proxy has successfully established a - // connection with the upstream. If the connection failed, the access log will not be flushed. + // If set to true, the access log is flushed when the TCP proxy successfully establishes a + // connection with the upstream. If the connection fails, the access log is not flushed. bool flush_access_log_on_connected = 2; } @@ -164,9 +195,8 @@ message TcpProxy { // The upstream cluster to connect to. string cluster = 2; - // Multiple upstream clusters can be specified for a given route. The - // request is routed to one of the upstream clusters based on weights - // assigned to each cluster. + // Multiple upstream clusters can be specified. The request is routed to one of the upstream clusters + // based on the weights assigned to each cluster. WeightedCluster weighted_clusters = 10; } @@ -182,16 +212,14 @@ message TcpProxy { // for load balancing. The filter name should be specified as ``envoy.lb``. config.core.v3.Metadata metadata_match = 9; - // The idle timeout for connections managed by the TCP proxy filter. The idle timeout - // is defined as the period in which there are no bytes sent or received on either - // the upstream or downstream connection. If not set, the default idle timeout is 1 hour. If set - // to 0s, the timeout will be disabled. - // It is possible to dynamically override this configuration by setting a per-connection filter - // state object for the key ``envoy.tcp_proxy.per_connection_idle_timeout_ms``. + // The idle timeout for connections managed by the TCP proxy filter. The idle timeout is defined as the + // period in which there are no bytes sent or received on either the upstream or downstream connection. + // If not set, the default idle timeout is 1 hour. If set to ``0s``, the timeout is disabled. + // It is possible to dynamically override this configuration by setting a per-connection filter state + // object for the key ``envoy.tcp_proxy.per_connection_idle_timeout_ms``. // // .. warning:: - // Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP - // FIN packets, etc. + // Disabling this timeout is likely to yield connection leaks due to lost TCP FIN packets, etc. google.protobuf.Duration idle_timeout = 8; // [#not-implemented-hide:] The idle timeout for connections managed by the TCP proxy @@ -205,8 +233,7 @@ message TcpProxy { // [#not-implemented-hide:] google.protobuf.Duration upstream_idle_timeout = 4; - // Configuration for :ref:`access logs ` - // emitted by the this tcp_proxy. + // Configuration for :ref:`access logs ` emitted by this TCP proxy. repeated config.accesslog.v3.AccessLog access_log = 5; // The maximum number of unsuccessful connection attempts that will be made before @@ -221,19 +248,25 @@ message TcpProxy { // limited to 1. repeated type.v3.HashPolicy hash_policy = 11 [(validate.rules).repeated = {max_items: 1}]; - // If set, this configures tunneling, e.g. configuration options to tunnel TCP payload over - // HTTP CONNECT. If this message is absent, the payload will be proxied upstream as per usual. - // It is possible to dynamically override this configuration and disable tunneling per connection, - // by setting a per-connection filter state object for the key ``envoy.tcp_proxy.disable_tunneling``. + // If set, this configures tunneling, for example configuration options to tunnel TCP payload over + // HTTP CONNECT. If this message is absent, the payload is proxied upstream as usual. + // It is possible to dynamically override this configuration and disable tunneling per connection by + // setting a per-connection filter state object for the key ``envoy.tcp_proxy.disable_tunneling``. TunnelingConfig tunneling_config = 12; - // The maximum duration of a connection. The duration is defined as the period since a connection - // was established. If not set, there is no max duration. When max_downstream_connection_duration - // is reached the connection will be closed. Duration must be at least 1ms. + // The maximum duration of a connection. The duration is defined as the period since a connection was + // established. If not set, there is no maximum duration. When ``max_downstream_connection_duration`` is + // reached, the connection is closed. The duration must be at least ``1ms``. google.protobuf.Duration max_downstream_connection_duration = 13 [(validate.rules).duration = {gte {nanos: 1000000}}]; - // Note that if both this field and :ref:`access_log_flush_interval + // Percentage-based jitter for ``max_downstream_connection_duration``. The jitter increases the + // ``max_downstream_connection_duration`` by a random duration up to the provided percentage. + // This field is ignored if ``max_downstream_connection_duration`` is not set. If not set, no jitter + // is added. + type.v3.Percent max_downstream_connection_duration_jitter_percentage = 20; + + // If both this field and :ref:`access_log_flush_interval // ` // are specified, the former (deprecated field) is ignored. // @@ -247,7 +280,7 @@ message TcpProxy { (envoy.annotations.deprecated_at_minor_version) = "3.0" ]; - // Note that if both this field and :ref:`flush_access_log_on_connected + // If both this field and :ref:`flush_access_log_on_connected // ` // are specified, the former (deprecated field) is ignored. // @@ -258,21 +291,22 @@ message TcpProxy { bool flush_access_log_on_connected = 16 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // Additional access log options for TCP Proxy. + // Additional access log options for the TCP proxy. TcpAccessLogOptions access_log_options = 17; - // If set, the specified PROXY protocol TLVs (Type-Length-Value) will be added to the PROXY protocol - // state created by the TCP proxy filter. These TLVs will be sent in the PROXY protocol v2 header - // to upstream. + // If set, the specified ``PROXY`` protocol TLVs (Type-Length-Value) are added to the ``PROXY`` protocol state + // created by the TCP proxy filter. These TLVs are sent in the PROXY protocol v2 header to the upstream. // - // This field only takes effect when the TCP proxy filter is creating new PROXY protocol - // state and there is an upstream proxy protocol transport socket configured in the cluster. - // If the connection already contains PROXY protocol state (including any TLVs) parsed by a - // downstream proxy protocol listener filter, the TLVs specified here are ignored. + // This field only takes effect when the TCP proxy filter is creating new ``PROXY`` protocol state and an + // upstream proxy protocol transport socket is configured in the cluster. If the connection already + // contains ``PROXY`` protocol state (including any TLVs) parsed by a downstream proxy protocol listener + // upstream proxy protocol transport socket is configured in the cluster. If the connection already + // contains PROXY protocol state (including any TLVs) parsed by a downstream proxy protocol listener + // filter, the TLVs specified here are ignored. // // .. note:: - // To ensure specified TLVs are allowed in the upstream PROXY protocol header, you must also - // configure the passthrough TLVs on the upstream proxy protocol transport. See + // To ensure the specified TLVs are allowed in the upstream ``PROXY`` protocol header, you must also + // configure passthrough TLVs on the upstream proxy protocol transport. See // :ref:`core.v3.ProxyProtocolConfig.pass_through_tlvs ` // for details. repeated config.core.v3.TlvEntry proxy_protocol_tlvs = 19; diff --git a/api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto b/api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto index 70c41643a..322dabd24 100644 --- a/api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto +++ b/api/src/main/proto/envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto @@ -102,6 +102,13 @@ message DnsFilterConfig { // Client context configuration controls Envoy's behavior when it must use external // resolvers to answer a query. This object is optional and if omitted instructs - // the filter to resolve queries from the data in the server_config + // the filter to resolve queries from the data in the server_config. + // Also, if ``client_config`` is omitted, here is the Envoy's behavior to create DNS resolver: + // + // 1. If :ref:`typed_dns_resolver_config ` + // is not empty, uses it. + // + // 2. Otherwise, uses the default c-ares DNS resolver. + // ClientContextConfig client_config = 3; } diff --git a/api/src/main/proto/envoy/extensions/formatter/cel/v3/cel.proto b/api/src/main/proto/envoy/extensions/formatter/cel/v3/cel.proto index 265f9dd35..ced34e735 100644 --- a/api/src/main/proto/envoy/extensions/formatter/cel/v3/cel.proto +++ b/api/src/main/proto/envoy/extensions/formatter/cel/v3/cel.proto @@ -30,6 +30,23 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // * ``%CEL(request.headers['x-envoy-original-path']):10%`` // * ``%CEL(request.headers['x-log-mtls'] || request.url_path.contains('v1beta3'))%`` +// Alternatively: %TYPED_CEL(EXPRESSION):Z% +// When using a non-text access log format like JSON, this format command is +// able to emit values of non-string types, like number, boolean, and null, +// based on the output of the CEL expression. It otherwise functions the same as +// %CEL%. CEL types not native to JSON are coerced as follows: +// +// * Bytes are base64 encoded to produce a string. +// * Durations are stringified as a count of seconds, e.g. `duration("1h30m")` +// becomes "5400s". +// * Timestamps are formatted to UTC, e.g. +// `timestamp("2023-08-26T12:39:00-07:00")` becomes +// "2023-08-26T19:39:00+00:00" +// * Maps become objects, provided all keys can be coerced to strings and that +// all values can coerce to types representable in JSON. +// * Lists become lists, provided all values can coerce to types representable +// in JSON. + // Configuration for the CEL formatter. // // .. warning:: diff --git a/api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto b/api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto index e289751f8..d4ccf4ebc 100644 --- a/api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto +++ b/api/src/main/proto/envoy/extensions/geoip_providers/common/v3/common.proto @@ -17,8 +17,8 @@ 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 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 the request. If any of the configured headers is present + // in the incoming request, it will be overridden by the :ref:`GeoIP filter `. // [#next-free-field: 13] message GeolocationHeadersToAdd { // If set, the header will be used to populate the country ISO code associated with the IP address. @@ -30,7 +30,7 @@ message CommonGeoipProviderConfig { [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; // If set, the header will be used to populate the region ISO code associated with the IP address. - // The least specific subdivision will be selected as region value. + // The least specific subdivision will be selected as the region value. string region = 3 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; @@ -38,35 +38,35 @@ message CommonGeoipProviderConfig { string asn = 4 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // This field is being deprecated, use ``anon`` instead. + // This field is deprecated; use ``anon`` instead. string is_anon = 5 [ deprecated = true, (validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}, (envoy.annotations.deprecated_at_minor_version) = "3.0" ]; - // If set, the IP address will be checked if it belongs to any type of anonymization network (e.g. VPN, public proxy etc) - // and header will be populated with the check result. Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to any type of anonymization network (e.g., VPN, public proxy). + // The header will be populated with the check result. Header value will be set to either ``true`` or ``false`` depending on the check result. string anon = 12 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // If set, the IP address will be checked if it belongs to a VPN and header will be populated with the check result. - // Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to a VPN and the header will be populated with the check result. + // Header value will be set to either ``true`` or ``false`` depending on the check result. string anon_vpn = 6 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // If set, the IP address will be checked if it belongs to a hosting provider and header will be populated with the check result. - // Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to a hosting provider and the header will be populated with the check result. + // Header value will be set to either ``true`` or ``false`` depending on the check result. string anon_hosting = 7 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // If set, the IP address will be checked if it belongs to a TOR exit node and header will be populated with the check result. - // Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to a TOR exit node and the header will be populated with the check result. + // Header value will be set to either ``true`` or ``false`` depending on the check result. string anon_tor = 8 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // If set, the IP address will be checked if it belongs to a public proxy and header will be populated with the check result. - // Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to a public proxy and the header will be populated with the check result. + // Header value will be set to either ``true`` or ``false`` depending on the check result. string anon_proxy = 9 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; @@ -74,12 +74,12 @@ message CommonGeoipProviderConfig { string isp = 10 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; - // If set, the IP address will be checked if it belongs to the ISP named iCloud Private Relay and header will be populated with the check result. - // Header value will be set to either "true" or "false" depending on the check result. + // If set, the IP address will be checked if it belongs to the ISP named iCloud Private Relay and the header will be populated with the check result. + // Header value will be set to either ``true`` or ``false`` depending on the check result. string apple_private_relay = 11 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}]; } - // Configuration for geolocation headers to add to request. + // Configuration for geolocation headers to add to the request. GeolocationHeadersToAdd geo_headers_to_add = 1 [(validate.rules).message = {required: true}]; } diff --git a/api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto b/api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto index c83f9b56e..c1d7a2480 100644 --- a/api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto +++ b/api/src/main/proto/envoy/extensions/geoip_providers/maxmind/v3/maxmind.proto @@ -18,28 +18,34 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: MaxMind Geolocation Provider] // MaxMind geolocation provider :ref:`configuration overview `. -// At least one geolocation database path :ref:`city_db_path `, -// :ref:`isp_db_path ` or -// :ref:`asn_db_path ` or -// :ref:`anon_db_path ` must be configured. +// +// At least one geolocation database path must be configured: +// +// * :ref:`city_db_path ` +// * :ref:`isp_db_path ` +// * :ref:`asn_db_path ` +// * :ref:`anon_db_path ` // [#extension: envoy.geoip_providers.maxmind] // [#next-free-field: 6] message MaxMindConfig { - // Full file path to the Maxmind city database, e.g. /etc/GeoLite2-City.mmdb. - // Database file is expected to have .mmdb extension. + // Full file path to the MaxMind city database, e.g., ``/etc/GeoLite2-City.mmdb``. + // Database file is expected to have ``.mmdb`` extension. string city_db_path = 1 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; - // Full file path to the Maxmind ASN database, e.g. /etc/GeoLite2-ASN.mmdb. - // Database file is expected to have .mmdb extension. + // Full file path to the MaxMind ASN database, e.g., ``/etc/GeoLite2-ASN.mmdb``. + // Database file is expected to have ``.mmdb`` extension. + // When this is defined, the ASN information will always be fetched from the ``asn_db``. string asn_db_path = 2 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; - // Full file path to the Maxmind anonymous IP database, e.g. /etc/GeoIP2-Anonymous-IP.mmdb. - // Database file is expected to have .mmdb extension. + // Full file path to the MaxMind Anonymous IP database, e.g., ``/etc/GeoIP2-Anonymous-IP.mmdb``. + // Database file is expected to have ``.mmdb`` extension. string anon_db_path = 3 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; - // Full file path to the Maxmind ISP database, e.g. /etc/GeoLite2-ISP.mmdb. - // Database file is expected to have .mmdb extension. + // Full file path to the MaxMind ISP database, e.g., ``/etc/GeoLite2-ISP.mmdb``. + // Database file is expected to have ``.mmdb`` extension. + // If ``asn_db_path`` is not defined, ASN information will be fetched from + // ``isp_db`` instead. string isp_db_path = 5 [(validate.rules).string = {pattern: "^$|^.*\\.mmdb$"}]; // Common provider configuration that specifies which geolocation headers will be populated with geolocation data. diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/access_token/v3/access_token_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/access_token/v3/access_token_credentials.proto new file mode 100644 index 000000000..45ee3839e --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/access_token/v3/access_token_credentials.proto @@ -0,0 +1,19 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.access_token.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.access_token.v3"; +option java_outer_classname = "AccessTokenCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/access_token/v3;access_tokenv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Access Token Credentials] + +// [#not-implemented-hide:] +message AccessTokenCredentials { + // The access token. + string token = 1; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/file_based_metadata/v3/file_based_metadata_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/file_based_metadata/v3/file_based_metadata_credentials.proto new file mode 100644 index 000000000..cacb09815 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/file_based_metadata/v3/file_based_metadata_credentials.proto @@ -0,0 +1,31 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.file_based_metadata.v3; + +import "envoy/config/core/v3/base.proto"; + +import "udpa/annotations/sensitive.proto"; +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.file_based_metadata.v3"; +option java_outer_classname = "FileBasedMetadataCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/file_based_metadata/v3;file_based_metadatav3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: File-Based Metadata Call Credentials] + +// [#not-implemented-hide:] +message FileBasedMetadataCallCredentials { + // Location or inline data of secret to use for authentication of the Google gRPC connection + // this secret will be attached to a header of the gRPC connection + config.core.v3.DataSource secret_data = 1 [(udpa.annotations.sensitive) = true]; + + // Metadata header key to use for sending the secret data + // if no header key is set, "authorization" header will be used + string header_key = 2; + + // Prefix to prepend to the secret in the metadata header + // if no prefix is set, the default is to use no prefix + string header_prefix = 3; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_compute_engine/v3/google_compute_engine_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_compute_engine/v3/google_compute_engine_credentials.proto new file mode 100644 index 000000000..d73086b95 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_compute_engine/v3/google_compute_engine_credentials.proto @@ -0,0 +1,17 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.google_compute_engine.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.google_compute_engine.v3"; +option java_outer_classname = "GoogleComputeEngineCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/google_compute_engine/v3;google_compute_enginev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Google Compute Engine Credentials] + +// [#not-implemented-hide:] +message GoogleComputeEngineCredentials { +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_iam/v3/google_iam_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_iam/v3/google_iam_credentials.proto new file mode 100644 index 000000000..0ed5a2d98 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_iam/v3/google_iam_credentials.proto @@ -0,0 +1,22 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.google_iam.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.google_iam.v3"; +option java_outer_classname = "GoogleIamCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/google_iam/v3;google_iamv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Google IAM Credentials] + +// [#not-implemented-hide:] +message GoogleIamCredentials { + // Authorization token. + string authorization_token = 1; + + // Authority selector. + string authority_selector = 2; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_refresh_token/v3/google_refresh_token_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_refresh_token/v3/google_refresh_token_credentials.proto new file mode 100644 index 000000000..ce32c957f --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/google_refresh_token/v3/google_refresh_token_credentials.proto @@ -0,0 +1,19 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.google_refresh_token.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.google_refresh_token.v3"; +option java_outer_classname = "GoogleRefreshTokenCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/google_refresh_token/v3;google_refresh_tokenv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Google Refresh Token Credentials] + +// [#not-implemented-hide:] +message GoogleRefreshTokenCredentials { + // JSON refresh token. + string token = 1; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/service_account_jwt_access/v3/service_account_jwt_access_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/service_account_jwt_access/v3/service_account_jwt_access_credentials.proto new file mode 100644 index 000000000..09c686f13 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/service_account_jwt_access/v3/service_account_jwt_access_credentials.proto @@ -0,0 +1,24 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.service_account_jwt_access.v3; + +import "google/protobuf/duration.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.service_account_jwt_access.v3"; +option java_outer_classname = "ServiceAccountJwtAccessCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/service_account_jwt_access/v3;service_account_jwt_accessv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Service Account JWT Access Credentials] + +// [#not-implemented-hide:] +message ServiceAccountJwtAccessCredentials { + // JSON key. + string json_key = 1; + + // Token lifetime. + google.protobuf.Duration token_lifetime = 2; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/sts_service/v3/sts_service_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/sts_service/v3/sts_service_credentials.proto new file mode 100644 index 000000000..12f285dfb --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/call_credentials/sts_service/v3/sts_service_credentials.proto @@ -0,0 +1,57 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.call_credentials.sts_service.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.call_credentials.sts_service.v3"; +option java_outer_classname = "StsServiceCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/call_credentials/sts_service/v3;sts_servicev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC STS Credentials] + +// Security token service configuration that allows Google gRPC to +// fetch security token from an OAuth 2.0 authorization server. +// See https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16 and +// https://github.com/grpc/grpc/pull/19587. +// [#not-implemented-hide:] +// [#next-free-field: 10] +message StsServiceCredentials { + // URI of the token exchange service that handles token exchange requests. + // [#comment:TODO(asraa): Add URI validation when implemented. Tracked by + // https://github.com/bufbuild/protoc-gen-validate/issues/303] + string token_exchange_service_uri = 1; + + // Location of the target service or resource where the client + // intends to use the requested security token. + string resource = 2; + + // Logical name of the target service where the client intends to + // use the requested security token. + string audience = 3; + + // The desired scope of the requested security token in the + // context of the service or resource where the token will be used. + string scope = 4; + + // Type of the requested security token. + string requested_token_type = 5; + + // The path of subject token, a security token that represents the + // identity of the party on behalf of whom the request is being made. + string subject_token_path = 6 [(validate.rules).string = {min_len: 1}]; + + // Type of the subject token. + string subject_token_type = 7 [(validate.rules).string = {min_len: 1}]; + + // The path of actor token, a security token that represents the identity + // of the acting party. The acting party is authorized to use the + // requested security token and act on behalf of the subject. + string actor_token_path = 8; + + // Type of the actor token. + string actor_token_type = 9; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/google_default/v3/google_default_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/google_default/v3/google_default_credentials.proto new file mode 100644 index 000000000..77c3af41f --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/google_default/v3/google_default_credentials.proto @@ -0,0 +1,17 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.channel_credentials.google_default.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.channel_credentials.google_default.v3"; +option java_outer_classname = "GoogleDefaultCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/channel_credentials/google_default/v3;google_defaultv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Google Default Credentials] + +// [#not-implemented-hide:] +message GoogleDefaultCredentials { +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/insecure/v3/insecure_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/insecure/v3/insecure_credentials.proto new file mode 100644 index 000000000..70d58451e --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/insecure/v3/insecure_credentials.proto @@ -0,0 +1,17 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.channel_credentials.insecure.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.channel_credentials.insecure.v3"; +option java_outer_classname = "InsecureCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/channel_credentials/insecure/v3;insecurev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Insecure Credentials] + +// [#not-implemented-hide:] +message InsecureCredentials { +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/local/v3/local_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/local/v3/local_credentials.proto new file mode 100644 index 000000000..00514a0e8 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/local/v3/local_credentials.proto @@ -0,0 +1,17 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.channel_credentials.local.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.channel_credentials.local.v3"; +option java_outer_classname = "LocalCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/channel_credentials/local/v3;localv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC Local Credentials] + +// [#not-implemented-hide:] +message LocalCredentials { +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/tls/v3/tls_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/tls/v3/tls_credentials.proto new file mode 100644 index 000000000..f64c16bb6 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/tls/v3/tls_credentials.proto @@ -0,0 +1,27 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.channel_credentials.tls.v3; + +import "envoy/extensions/transport_sockets/tls/v3/tls.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.channel_credentials.tls.v3"; +option java_outer_classname = "TlsCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/channel_credentials/tls/v3;tlsv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC TLS Credentials] + +// [#not-implemented-hide:] +message TlsCredentials { + // The certificate provider instance for the root cert. Must be set. + transport_sockets.tls.v3.CommonTlsContext.CertificateProviderInstance root_certificate_provider = + 1; + + // The certificate provider instance for the identity cert. Optional; + // if unset, no identity certificate will be sent to the server. + transport_sockets.tls.v3.CommonTlsContext.CertificateProviderInstance + identity_certificate_provider = 2; +} diff --git a/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/xds/v3/xds_credentials.proto b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/xds/v3/xds_credentials.proto new file mode 100644 index 000000000..ba8d471dd --- /dev/null +++ b/api/src/main/proto/envoy/extensions/grpc_service/channel_credentials/xds/v3/xds_credentials.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +package envoy.extensions.grpc_service.channel_credentials.xds.v3; + +import "google/protobuf/any.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.grpc_service.channel_credentials.xds.v3"; +option java_outer_classname = "XdsCredentialsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/grpc_service/channel_credentials/xds/v3;xdsv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: gRPC xDS Credentials] + +// [#not-implemented-hide:] +message XdsCredentials { + // Fallback credentials. Required. + google.protobuf.Any fallback_credentials = 1; +} diff --git a/api/src/main/proto/envoy/extensions/health_checkers/redis/v3/redis.proto b/api/src/main/proto/envoy/extensions/health_checkers/redis/v3/redis.proto index caa385996..1277c05e0 100644 --- a/api/src/main/proto/envoy/extensions/health_checkers/redis/v3/redis.proto +++ b/api/src/main/proto/envoy/extensions/health_checkers/redis/v3/redis.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.health_checkers.redis.v3; +import "envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto"; + import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; @@ -24,4 +26,7 @@ message Redis { // than 0 is considered a failure. This allows the user to mark a Redis instance for maintenance // by setting the specified key to any value and waiting for traffic to drain. string key = 1; + + // Use AWS IAM for health checker authentication + filters.network.redis_proxy.v3.AwsIam aws_iam = 2; } diff --git a/api/src/main/proto/envoy/extensions/http/cache_v2/file_system_http_cache/v3/file_system_http_cache.proto b/api/src/main/proto/envoy/extensions/http/cache_v2/file_system_http_cache/v3/file_system_http_cache.proto new file mode 100644 index 000000000..f47546bee --- /dev/null +++ b/api/src/main/proto/envoy/extensions/http/cache_v2/file_system_http_cache/v3/file_system_http_cache.proto @@ -0,0 +1,131 @@ +syntax = "proto3"; + +package envoy.extensions.http.cache_v2.file_system_http_cache.v3; + +import "envoy/extensions/common/async_files/v3/async_file_manager.proto"; + +import "google/protobuf/duration.proto"; +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.http.cache_v2.file_system_http_cache.v3"; +option java_outer_classname = "FileSystemHttpCacheProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/cache_v2/file_system_http_cache/v3;file_system_http_cachev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: FileSystemHttpCacheV2Config] +// [#extension: envoy.extensions.http.cache_v2.file_system_http_cache] + +// Configuration for a cache implementation that caches in the local file system. +// +// By default this cache uses a least-recently-used eviction strategy. +// +// For implementation details, see `DESIGN.md `_. +// [#next-free-field: 11] +message FileSystemHttpCacheV2Config { + // Configuration of a manager for how the file system is used asynchronously. + common.async_files.v3.AsyncFileManagerConfig manager_config = 1 + [(validate.rules).message = {required: true}]; + + // Path at which the cache files will be stored. + // + // This also doubles as the unique identifier for a cache, so a cache can be shared + // between different routes, or separate paths can be used to specify separate caches. + // + // If the same ``cache_path`` is used in more than one ``CacheV2Config``, the rest of the + // ``FileSystemHttpCacheV2Config`` must also match, and will refer to the same cache + // instance. + string cache_path = 2 [(validate.rules).string = {min_len: 1}]; + + // The maximum size of the cache in bytes - when reached, cache eviction is triggered. + // + // This is measured as the sum of file sizes, such that it includes headers, trailers, + // and metadata, but does not include e.g. file system overhead and block size padding. + // + // If unset there is no limit except file system failure. + google.protobuf.UInt64Value max_cache_size_bytes = 3; + + // The maximum size of a cache entry in bytes - larger responses will not be cached. + // + // This is measured as the file size for the cache entry, such that it includes + // headers, trailers, and metadata. + // + // If unset there is no limit. + // + // [#not-implemented-hide:] + google.protobuf.UInt64Value max_individual_cache_entry_size_bytes = 4; + + // The maximum number of cache entries - when reached, cache eviction is triggered. + // + // If unset there is no limit. + google.protobuf.UInt64Value max_cache_entry_count = 5; + + // A number of folders into which to subdivide the cache. + // + // Setting this can help with performance in file systems where a large number of inodes + // in a single branch degrades performance. The optimal value in that case would be + // ``sqrt(expected_cache_entry_count)``. + // + // On file systems that perform well with many inodes, the default value of 1 should be used. + // + // [#not-implemented-hide:] + uint32 cache_subdivisions = 6; + + // The amount of the maximum cache size or count to evict when cache eviction is + // triggered. For example, if ``max_cache_size_bytes`` is 10000000 and ``evict_fraction`` + // is 0.2, then when the cache exceeds 10MB, entries will be evicted until the cache size is + // less than or equal to 8MB. + // + // The default value of 0 means when the cache exceeds 10MB, entries will be evicted only + // until the cache is less than or equal to 10MB. + // + // Evicting a larger fraction will mean the eviction thread will run less often (sparing + // CPU load) at the cost of more cache misses due to the extra evicted entries. + // + // [#not-implemented-hide:] + float evict_fraction = 7; + + // The longest amount of time to wait before running a cache eviction pass. An eviction + // pass may not necessarily remove any files, but it will update the cache state to match + // the on-disk state. This can be important if multiple instances are accessing the same + // cache in parallel. (e.g. if two instances each independently added non-overlapping 10MB + // of content to a cache with a 15MB limit, neither instance would be aware that the limit + // was exceeded without this synchronizing pass.) + // + // If an eviction pass has not happened within this duration, the eviction thread will + // be awoken and perform an eviction pass. + // + // If unset, there will be no eviction passes except those triggered by cache limits. + // + // [#not-implemented-hide:] + google.protobuf.Duration max_eviction_period = 8; + + // The shortest amount of time between cache eviction passes. This can be used to reduce + // eviction churn, if your cache max size can be flexible. If a cache eviction pass already + // occurred more recently than this period when another would be triggered, that new + // pass is cancelled. + // + // This means the cache can potentially grow beyond ``max_cache_size_bytes`` by as much as + // can be written within the duration specified. + // + // Generally you would use *either* ``min_eviction_period`` *or* ``evict_fraction`` to + // reduce churn. Both together will work but since they're both aiming for the same goal, + // it's simpler not to. + // + // [#not-implemented-hide:] + google.protobuf.Duration min_eviction_period = 9; + + // If true, and the cache path does not exist, attempt to create the cache path, including + // any missing directories leading up to it. On failure, the config is rejected. + // + // If false, and the cache path does not exist, the config is rejected. + // + // [#not-implemented-hide:] + bool create_cache_path = 10; +} diff --git a/api/src/main/proto/envoy/extensions/http/cache_v2/simple_http_cache/v3/config.proto b/api/src/main/proto/envoy/extensions/http/cache_v2/simple_http_cache/v3/config.proto new file mode 100644 index 000000000..9db3757ba --- /dev/null +++ b/api/src/main/proto/envoy/extensions/http/cache_v2/simple_http_cache/v3/config.proto @@ -0,0 +1,20 @@ +syntax = "proto3"; + +package envoy.extensions.http.cache_v2.simple_http_cache.v3; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.http.cache_v2.simple_http_cache.v3"; +option java_outer_classname = "ConfigProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/cache_v2/simple_http_cache/v3;simple_http_cachev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: SimpleHttpCache CacheFilter storage plugin] + +// [#extension: envoy.extensions.http.cache_v2.simple] +message SimpleHttpCacheV2Config { +} diff --git a/api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto b/api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto new file mode 100644 index 000000000..699dc357d --- /dev/null +++ b/api/src/main/proto/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3/mapped_attribute_builder.proto @@ -0,0 +1,71 @@ +syntax = "proto3"; + +package envoy.extensions.http.ext_proc.processing_request_modifiers.mapped_attribute_builder.v3; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.http.ext_proc.processing_request_modifiers.mapped_attribute_builder.v3"; +option java_outer_classname = "MappedAttributeBuilderProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3;mapped_attribute_builderv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: Mapped Attribute Builder for the external processor] +// [#extension: envoy.http.ext_proc.processing_request_modifiers.mapped_attribute_builder] + +// Extension to build custom attributes in the :ref:`request +// ` based on a configurable mapping. The +// native implementation uses the CEL expression as the key, which is not always desirable. Using this +// extension, one can re-map a CEL expression that references internal filter state into a more +// user-friendly key that decouples the value from the underlying filter implementation. +// +// If a given CEL expression fails to eval, it will not be present in the attributes struct. +// +// If this extension is configured, then the original :ref:`ProcessingRequest +// `'s ``request_attributes`` are ignored, +// and all attributes should be explicitly set via this extension. +// +// An example configuration may look like so: +// +// .. code-block:: yaml +// +// mapped_request_attributes: +// "request.path": "request.path" +// "source.country": "metadata.filter_metadata['com.example.location_filter']['country_code']" +// +// In the above example, the complex filter_metadata expression is evaluated via CEL, and the value +// is stored under the friendlier ``source.country`` key. ``The ProcessingRequest`` would look like: +// +// .. code-block:: text +// +// attributes { +// key: "envoy.filters.http.ext_proc" +// value { +// fields { +// key: "request.path" +// value { +// string_value: "/profile" +// } +// } +// fields { +// key: "source.country" +// value { +// string_value: "US" +// } +// } +// } +// } +// +// .. note:: +// Processing request modifiers are currently in alpha. +// +message MappedAttributeBuilder { + // A map of request attributes to set in the attributes struct. + // The key is the attribute name, the value is the attribute value, + // 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; +} diff --git a/api/src/main/proto/envoy/extensions/http/header_validators/envoy_default/v3/header_validator.proto b/api/src/main/proto/envoy/extensions/http/header_validators/envoy_default/v3/header_validator.proto index b0dc6ce84..0a1e88fb5 100644 --- a/api/src/main/proto/envoy/extensions/http/header_validators/envoy_default/v3/header_validator.proto +++ b/api/src/main/proto/envoy/extensions/http/header_validators/envoy_default/v3/header_validator.proto @@ -15,25 +15,33 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // This extension validates that HTTP request and response headers are well formed according to respective RFCs. // -// #. HTTP/1 header map validity according to `RFC 7230 section 3.2 `_ -// #. Syntax of HTTP/1 request target URI and response status -// #. HTTP/2 header map validity according to `RFC 7540 section 8.1.2 `_ -// #. Syntax of HTTP/2 pseudo headers -// #. HTTP/3 header map validity according to `RFC 9114 section 4.3 `_ -// #. Syntax of HTTP/3 pseudo headers -// #. Syntax of Content-Length and Transfer-Encoding -// #. Validation of HTTP/1 requests with both ``Content-Length`` and ``Transfer-Encoding`` headers +// The validator performs comprehensive HTTP header validation including: +// +// #. HTTP/1 header map validity according to `RFC 7230 section 3.2 `_. +// #. Syntax of HTTP/1 request target URI and response status. +// #. HTTP/2 header map validity according to `RFC 7540 section 8.1.2 `_. +// #. Syntax of HTTP/2 pseudo headers. +// #. HTTP/3 header map validity according to `RFC 9114 section 4.3 `_. +// #. Syntax of HTTP/3 pseudo headers. +// #. Syntax of Content-Length and Transfer-Encoding. +// #. Validation of HTTP/1 requests with both ``Content-Length`` and ``Transfer-Encoding`` headers. // #. Normalization of the URI path according to `Normalization and Comparison `_ -// without `case normalization `_ +// without `case normalization `_. +// +// This validator ensures that HTTP traffic processed by Envoy conforms to established +// standards and helps prevent issues caused by malformed headers or invalid HTTP syntax. // // [#comment:TODO(yanavlasov): Put #extension: envoy.http.header_validators.envoy_default after it is not hidden any more] // [#next-free-field: 6] message HeaderValidatorConfig { // Action to take when Envoy receives client request with header names containing underscore // characters. - // Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented - // as a security measure due to systems that treat '_' and '-' as interchangeable. Envoy by default allows client request headers with underscore - // characters. + // + // Underscore character is allowed in header names by RFC-7230, and this behavior is implemented + // as a security measure due to systems that treat ``_`` and ``-`` as interchangeable. Envoy by + // default allows client request headers with underscore characters. + // + // This setting provides control over how to handle such headers for security and compatibility reasons. enum HeadersWithUnderscoresAction { // Allow headers with underscores. This is the default behavior. ALLOW = 0; @@ -51,102 +59,170 @@ message HeaderValidatorConfig { DROP_HEADER = 2; } + // Configuration options for URI path normalization and transformation. + // + // These options control how Envoy processes and normalizes incoming request URI paths + // to ensure consistent behavior and security. Path normalization helps prevent + // path traversal attacks and ensures that equivalent paths are handled consistently. message UriPathNormalizationOptions { // Determines the action for requests that contain ``%2F``, ``%2f``, ``%5C`` or ``%5c`` sequences in the URI path. // This operation occurs before URL normalization and the merge slashes transformations if they were enabled. + // + // Escaped slash sequences in URLs can be used for path confusion attacks, so proper handling + // is important for security. enum PathWithEscapedSlashesAction { // Default behavior specific to implementation (i.e. Envoy) of this configuration option. // Envoy, by default, takes the ``KEEP_UNCHANGED`` action. - // NOTE: the implementation may change the default behavior at-will. + // + // .. note:: + // + // The implementation may change the default behavior at-will. + // IMPLEMENTATION_SPECIFIC_DEFAULT = 0; - // Keep escaped slashes. + // Keep escaped slashes unchanged in the URI path. + // This preserves the original request path without any modifications to escaped sequences. KEEP_UNCHANGED = 1; // Reject client request with the 400 status. gRPC requests will be rejected with the ``INTERNAL`` (13) error code. - // The ``http#.downstream_rq_failed_path_normalization`` counter is incremented for each rejected request. + // The :ref:`httpN.downstream_rq_failed_path_normalization ` counter is incremented for each rejected request. + // + // This is the safest option when security is a primary concern, as it prevents any potential + // path confusion attacks by rejecting requests with escaped slashes entirely. REJECT_REQUEST = 2; // Unescape ``%2F`` and ``%5C`` sequences and redirect the request to the new path if these sequences were present. // The redirect occurs after path normalization and merge slashes transformations if they were configured. - // NOTE: gRPC requests will be rejected with the ``INTERNAL`` (13) error code. - // This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to - // traverse all parties: downstream client, intermediate proxies, Envoy and upstream server. - // The ``http#.downstream_rq_redirected_with_normalized_path`` counter is incremented for each + // + // .. note:: + // + // gRPC requests will be rejected with the ``INTERNAL`` (13) error code. + // This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to + // traverse all parties: downstream client, intermediate proxies, Envoy and upstream server. + // + // The :ref:`httpN.downstream_rq_redirected_with_normalized_path ` counter is incremented for each // redirected request. UNESCAPE_AND_REDIRECT = 3; // Unescape ``%2F`` and ``%5C`` sequences. - // Note: this option should not be enabled if intermediaries perform path based access control as - // it may lead to path confusion vulnerabilities. + // + // .. attention:: + // + // This option should not be enabled if intermediaries perform path based access control as + // it may lead to path confusion vulnerabilities. + // UNESCAPE_AND_FORWARD = 4; } // Should paths be normalized according to RFC 3986? + // // This operation overwrites the original request URI path and the new path is used for processing of // the request by HTTP filters and proxied to the upstream service. // Envoy will respond with 400 to requests with malformed paths that fail path normalization. // The default behavior is to normalize the path. + // // This value may be overridden by the runtime variable // :ref:`http_connection_manager.normalize_path`. // See `Normalization and Comparison `_ // for details of normalization. - // Note that Envoy does not perform - // `case normalization `_ - // URI path normalization can be applied to a portion of requests by setting the - // ``envoy_default_header_validator.path_normalization`` runtime value. + // + // .. note:: + // + // Envoy does not perform + // `case normalization `_. + // URI path normalization can be applied to a portion of requests by setting the + // ``envoy_default_header_validator.path_normalization`` runtime value. + // bool skip_path_normalization = 1; // Determines if adjacent slashes in the path are merged into one. + // // This operation overwrites the original request URI path and the new path is used for processing of // the request by HTTP filters and proxied to the upstream service. - // Setting this option to true will cause incoming requests with path ``//dir///file`` to not match against - // route with ``prefix`` match set to ``/dir``. Defaults to ``false``. Note that slash merging is not part of - // `HTTP spec `_ and is provided for convenience. - // Merging of slashes in URI path can be applied to a portion of requests by setting the - // ``envoy_default_header_validator.merge_slashes`` runtime value. + // Setting this option to ``true`` will cause incoming requests with path ``//dir///file`` to not match against + // route with ``prefix`` match set to ``/dir``. Defaults to ``false``. + // + // .. note:: + // + // Slash merging is not part of the + // `HTTP spec `_ and is provided for convenience. + // Merging of slashes in URI path can be applied to a portion of requests by setting the + // ``envoy_default_header_validator.merge_slashes`` runtime value. + // bool skip_merging_slashes = 2; // The action to take when request URL path contains escaped slash sequences (``%2F``, ``%2f``, ``%5C`` and ``%5c``). + // // This operation may overwrite the original request URI path and the new path is used for processing of // the request by HTTP filters and proxied to the upstream service. + // + // The handling of escaped slashes is important for security as these sequences can be used + // in path confusion attacks to bypass access controls. PathWithEscapedSlashesAction path_with_escaped_slashes_action = 3 [(validate.rules).enum = {defined_only: true}]; } + // HTTP/1 protocol specific options for header validation. + // + // These options control how Envoy handles HTTP/1 specific behaviors and edge cases + // that may not apply to HTTP/2 or HTTP/3 protocols. message Http1ProtocolOptions { // Allows Envoy to process HTTP/1 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 the ``Content-Length`` header and process the message. + // // See `RFC7230, sec. 3.3.3 `_ for details. // // .. attention:: + // // Enabling this option might lead to request smuggling vulnerabilities, especially if traffic // is proxied via multiple layers of proxies. + // bool allow_chunked_length = 1; } + // HTTP/1 protocol specific options. + // These settings control HTTP/1 specific validation behaviors. Http1ProtocolOptions http1_protocol_options = 1; // The URI path normalization options. + // // By default Envoy normalizes URI path using the default values of the :ref:`UriPathNormalizationOptions // `. // URI path transformations specified by the ``uri_path_normalization_options`` configuration can be applied to a portion // of requests by setting the ``envoy_default_header_validator.uri_path_transformations`` runtime value. - // Caution: disabling path normalization may lead to path confusion vulnerabilities in access control or incorrect service - // selection. + // + // .. attention:: + // + // Disabling path normalization may lead to path confusion vulnerabilities in access control or incorrect service + // selection. + // UriPathNormalizationOptions uri_path_normalization_options = 2; - // Restrict HTTP methods to these defined in the `RFC 7231 section 4.1 `_ + // Restrict HTTP methods to these defined in the `RFC 7231 section 4.1 `_. + // // Envoy will respond with 400 to requests with disallowed methods. // By default methods with arbitrary names are accepted. + // + // This setting helps enforce HTTP compliance and can prevent attacks that rely on + // non-standard HTTP methods. bool restrict_http_methods = 3; // 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``. + // + // This setting provides security control over headers with underscores, which can be a source + // of security issues when different systems interpret underscores and hyphens differently. HeadersWithUnderscoresAction headers_with_underscores_action = 4; // Allow requests with fragment in URL path and strip the fragment before request processing. - // By default Envoy rejects requests with fragment in URL path. + // + // By default Envoy rejects requests with fragment in URL path. When this option is enabled, + // the fragment portion (everything after ``#``) will be removed from the path before + // further processing. + // + // Fragments are typically used by client-side applications and should not normally + // be sent to the server, so stripping them can help normalize requests. bool strip_fragment_from_path = 5; } diff --git a/api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto b/api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto index f81a146f6..7b8a17816 100644 --- a/api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto +++ b/api/src/main/proto/envoy/extensions/http/injected_credentials/generic/v3/generic.proto @@ -4,8 +4,6 @@ package envoy.extensions.http.injected_credentials.generic.v3; import "envoy/extensions/transport_sockets/tls/v3/secret.proto"; -import "xds/annotations/v3/status.proto"; - import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -14,7 +12,6 @@ option java_outer_classname = "GenericProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/injected_credentials/generic/v3;genericv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Generic Credential] // [#extension: envoy.http.injected_credentials.generic] diff --git a/api/src/main/proto/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto b/api/src/main/proto/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto new file mode 100644 index 000000000..79d089e1a --- /dev/null +++ b/api/src/main/proto/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto @@ -0,0 +1,52 @@ +syntax = "proto3"; + +package envoy.extensions.http.stateful_session.envelope.v3; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.http.stateful_session.envelope.v3"; +option java_outer_classname = "EnvelopeProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/stateful_session/envelope/v3;envelopev3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Envelope stateful session extension] + +// The extension allows the session state is tracked via existing session context that initialized +// by the upstream server. It assumes that the upstream server will generate the session context +// (like session id header or cookie) in the initial response of the session and the client will use +// the same session context in the subsequent requests without any modification. +// +// When processing the response from the upstream, Envoy will check if the response contains the +// session context. If the response contains the session context, no matter if it's a new session +// context or an existing one, Envoy will join it and the upstream host as new session context. +// +// When processing the request from the downstream, Envoy will check if the request contains the +// session context. If the request contains the session context, Envoy will strip the +// upstream host from the session context. +// +// [#extension: envoy.http.stateful_session.envelope] +message EnvelopeSessionState { + message Header { + // Iff the header specified by the ``name`` field is present in the response (assume the ``name`` + // is set to ``session-header`` and original header value is ``xxxxxx``), then the upstream host + // address and value of ``name`` field specified header will be encoded in following format and + // the output will be used to update the ``name`` field specified header in the response: + // + // .. code-block:: none + // + // session-header: "MS4yLjMuNDo4MAo=;UV:eHh4eHh4Cg==" # base64(1.2.3.4:80);UV:base64(xxxxxx) + // + // The ``UV`` (upstream value) part is used to store the original upstream header value of + // ``name`` field specified header. + // + // If this mode is used then Envoy will assume that the header in the request will also be in the + // same format and will contain the ``UV`` part. This extension will parse the upstream host + // address and update the ``name`` field specified header in the request to the ``UV`` part. + string name = 1 [(validate.rules).string = {min_len: 1}]; + } + + // Set the header config to track the session state. + Header header = 1 [(validate.rules).message = {required: true}]; +} diff --git a/api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index 9520f6dbd..abaaf4ea8 100644 --- a/api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/api/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; + import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; @@ -32,10 +34,17 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // weights using eps and qps. The weight of a given endpoint is computed as: // ``qps / (utilization + eps/qps * error_utilization_penalty)``. // +// Note that Envoy will forward the ORCA response headers/trailers from the upstream +// cluster to the downstream client. This means that if the downstream client is also +// configured to use ``client_side_weighted_round_robin`` it will load balance against +// Envoy based on upstream weights. This can happen when Envoy is used as a reverse proxy. +// To avoid this issue you can configure the :ref:`header_mutation filter ` to remove +// the ORCA payload from the response headers/trailers. +// // See the :ref:`load balancing architecture // overview` for more information. // -// [#next-free-field: 8] +// [#next-free-field: 9] message ClientSideWeightedRoundRobin { // Whether to enable out-of-band utilization reporting collection from // the endpoints. By default, per-request utilization reporting is used. @@ -75,4 +84,9 @@ message ClientSideWeightedRoundRobin { // For map fields in the ORCA proto, the string will be of the form ``.``. For example, the string ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA :ref:`named_metrics ` field. // If none of the specified metrics are present in the load report, then :ref:`cpu_utilization ` is used instead. repeated string metric_names_for_computing_utilization = 7; + + // 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/api/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto b/api/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto index 7addeb707..22faf11b9 100644 --- a/api/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto +++ b/api/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto @@ -3,11 +3,13 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.common.v3; import "envoy/config/core/v3/base.proto"; +import "envoy/config/route/v3/route_components.proto"; import "envoy/type/v3/percent.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -22,7 +24,34 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; message LocalityLbConfig { // Configuration for :ref:`zone aware routing // `. + // [#next-free-field: 7] message ZoneAwareLbConfig { + // Basis for computing per-locality percentages in zone-aware routing. + enum LocalityBasis { + // Use the number of healthy hosts in each locality. + HEALTHY_HOSTS_NUM = 0; + + // Use the weights of healthy hosts in each locality. + HEALTHY_HOSTS_WEIGHT = 1; + } + + // Configures Envoy to always route requests to the local zone regardless of the + // upstream zone structure. In Envoy's default configuration, traffic is distributed proportionally + // across all upstream hosts while trying to maximize local routing when possible. The approach + // with force_local_zone aims to be more predictable and if there are upstream hosts in the local + // zone, they will receive all traffic. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + message ForceLocalZone { + // Configures the minimum number of upstream hosts in the local zone required when force_local_zone + // is enabled. If the number of upstream hosts in the local zone is less than the specified value, + // Envoy will fall back to the default proportional-based distribution across localities. + // If not specified, the default is 1. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + google.protobuf.UInt32Value min_size = 1; + } + // Configures percentage of requests that will be considered for zone aware routing // if zone aware routing is configured. If not specified, the default is 100%. // * :ref:`runtime values `. @@ -43,7 +72,16 @@ message LocalityLbConfig { bool fail_traffic_on_panic = 3; // If set to true, Envoy will force LocalityDirect routing if a local locality exists. - bool force_locality_direct_routing = 4; + bool force_locality_direct_routing = 4 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; + + ForceLocalZone force_local_zone = 5; + + // Determines how locality percentages are computed: + // - HEALTHY_HOSTS_NUM: proportional to the count of healthy hosts. + // - HEALTHY_HOSTS_WEIGHT: proportional to the weights of healthy hosts. + // Default value is HEALTHY_HOSTS_NUM if unset. + LocalityBasis locality_basis = 6; } // Configuration for :ref:`locality weighted load balancing @@ -114,4 +152,10 @@ message ConsistentHashingLbConfig { // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts // being probed, so use a higher value if you require better performance. google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}]; + + // Specifies a list of hash policies to use for ring hash load balancing. If ``hash_policy`` is + // set, then + // :ref:`route level hash policy ` + // will be ignored. + repeated config.route.v3.RouteAction.HashPolicy hash_policy = 3; } diff --git a/api/src/main/proto/envoy/extensions/load_balancing_policies/override_host/v3/override_host.proto b/api/src/main/proto/envoy/extensions/load_balancing_policies/override_host/v3/override_host.proto new file mode 100644 index 000000000..14f541e74 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/load_balancing_policies/override_host/v3/override_host.proto @@ -0,0 +1,79 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.override_host.v3; + +import "envoy/config/cluster/v3/cluster.proto"; +import "envoy/type/metadata/v3/metadata.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.override_host.v3"; +option java_outer_classname = "OverrideHostProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/override_host/v3;override_hostv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Override Host Load Balancing Policy] +// [#extension: envoy.load_balancing_policies.override_host] + +// Configuration for the Override Host Load Balancing policy. +// +// This policy allows endpoint picking to be implemented in downstream HTTP filters. For example an ext_proc RPC to a service +// that implements k8s proposal for AI gateway inferences extensions +// https://github.com/kubernetes-sigs/gateway-api-inference-extension/tree/main/docs/proposals/004-endpoint-picker-protocol +// can provide hosts for serving a request using Override Host load balancing policy. +// +// This policy extracts selected override hosts from a list of ``OverrideHostSource`` (request headers, metadata, etc.). +// +// The override host source must specify at least one host in ``IP:Port`` format or multiple hosts in ``IP:Port,IP:Port,...`` +// format. For example ``10.0.0.5:8080`` or ``[2600:4040:5204::1574:24ae]:80``. The IPv6 address is enclosed in square brackets. +// +// For specific example, to support k8s gateway inference extensions, which uses the ``x-gateway-destination-endpoint`` +// header or metadata value under the "envoy.lb" key for selected hosts, the Override Host load balancing policy should be +// configured in the following way: +// +// .. code-block:: yaml +// +// override_host_sources: +// - header: "x-gateway-destination-endpoint" +// - metadata: +// key: "envoy.lb" +// path: +// - key: "x-gateway-destination-endpoint" +// +// If no valid host in the override host list, then the specified fallback load balancing policy is used. This allows load +// balancing to degrade to a a built in policy (i.e. Round Robin) in case external endpoint picker fails. +// +// See the :ref:`load balancing architecture +// overview` for more information. +// +message OverrideHost { + message OverrideHostSource { + // The header to get the override host addresses. + // + // Only one of the header or metadata field could be set. + string header = 1 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; + + // The metadata key to get the override host addresses from the request dynamic metadata. If + // set this field then it will take precedence over the header field. + // + // Only one of the header or metadata field could be set. + type.metadata.v3.MetadataKey metadata = 2; + } + + // A list of sources to get host addresses from. The host sources are searched in the order + // specified. The request is forwarded to the first address and subsequent addresses are used + // for request retries or hedging. + // Note that if an overridden host address is not present in the current endpoint set, it is + // skipped and the next found address is used. If there are not enough overridden addresses to + // satisfy all retry attempts the fallback load balancing policy is used to pick a host. + repeated OverrideHostSource override_host_sources = 1 + [(validate.rules).repeated = {min_items: 1}]; + + // The child LB policy to use in case neither header nor metadata with selected + // hosts is present. + config.cluster.v3.LoadBalancingPolicy fallback_policy = 3 + [(validate.rules).message = {required: true}]; +} diff --git a/api/src/main/proto/envoy/extensions/matching/common_inputs/network/v3/network_inputs.proto b/api/src/main/proto/envoy/extensions/matching/common_inputs/network/v3/network_inputs.proto index bea415a71..b62690b4f 100644 --- a/api/src/main/proto/envoy/extensions/matching/common_inputs/network/v3/network_inputs.proto +++ b/api/src/main/proto/envoy/extensions/matching/common_inputs/network/v3/network_inputs.proto @@ -148,3 +148,17 @@ message DynamicMetadataInput { // The path to retrieve the Value from the Struct. repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; } + +// Input that matches by the network namespace of the listener address. +// This input returns the network namespace filepath that was used to create the listening socket. +// On Linux systems, this corresponds to the ``network_namespace_filepath`` field in the +// :ref:`SocketAddress ` configuration. +// +// .. note:: +// +// This input is only meaningful on Linux systems where network namespaces are supported. +// On other platforms, this input will always return an empty value. +// +// [#extension: envoy.matching.inputs.network_namespace] +message NetworkNamespaceInput { +} diff --git a/api/src/main/proto/envoy/extensions/matching/common_inputs/stats/v3/stats.proto b/api/src/main/proto/envoy/extensions/matching/common_inputs/stats/v3/stats.proto new file mode 100644 index 000000000..2db3a6216 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/matching/common_inputs/stats/v3/stats.proto @@ -0,0 +1,17 @@ +syntax = "proto3"; + +package envoy.extensions.matching.common_inputs.stats.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.matching.common_inputs.stats.v3"; +option java_outer_classname = "StatsProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/matching/common_inputs/stats/v3;statsv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Stats matcher] + +// Specifies the way to match stats with full name. +message StatFullNameMatchInput { +} diff --git a/api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto b/api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto index 2bc000e8d..b060bce96 100644 --- a/api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto +++ b/api/src/main/proto/envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto @@ -5,6 +5,7 @@ package envoy.extensions.network.dns_resolver.cares.v3; import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/resolver.proto"; +import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; @@ -20,18 +21,18 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.network.dns_resolver.cares] // Configuration for c-ares DNS resolver. -// [#next-free-field: 9] +// [#next-free-field: 11] message CaresDnsResolverConfig { - // A list of dns resolver addresses. - // :ref:`use_resolvers_as_fallback` + // A list of DNS resolver addresses. + // :ref:`use_resolvers_as_fallback ` // below dictates if the DNS client should override system defaults or only use the provided // resolvers if the system defaults are not available, i.e., as a fallback. repeated config.core.v3.Address resolvers = 1; // If true use the resolvers listed in the - // :ref:`resolvers` + // :ref:`resolvers ` // field only if c-ares is unable to obtain a - // nameserver from the system (e.g., /etc/resolv.conf). + // nameserver from the system (e.g., ``/etc/resolv.conf``). // Otherwise, the resolvers listed in the resolvers list will override the default system // resolvers. Defaults to false. bool use_resolvers_as_fallback = 3; @@ -45,27 +46,57 @@ message CaresDnsResolverConfig { // Configuration of DNS resolver option flags which control the behavior of the DNS resolver. config.core.v3.DnsResolverOptions dns_resolver_options = 2; - // This option allows for number of UDP based DNS queries to be capped. Note, this - // is only applicable to c-ares DNS resolver currently. + // This option allows the number of UDP based DNS queries to be capped. + // + // .. note:: + // This is only applicable to c-ares DNS resolver currently. + // google.protobuf.UInt32Value udp_max_queries = 5; // The number of seconds each name server is given to respond to a query on the first try of any given server. // - // Note: While the c-ares library defaults to 2 seconds, Envoy's default (if this field is unset) is 5 seconds. - // This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times. + // .. note:: + // While the c-ares library defaults to 2 seconds, Envoy's default (if this field is unset) is 5 seconds. + // This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times. + // google.protobuf.UInt64Value query_timeout_seconds = 6 [(validate.rules).uint64 = {gte: 1}]; // The maximum number of query attempts the resolver will make before giving up. // Each attempt may use a different name server. // - // Note: While the c-ares library defaults to 3 attempts, Envoy's default (if this field is unset) is 4 attempts. - // This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times. + // .. note:: + // While the c-ares library defaults to 3 attempts, Envoy's default (if this field is unset) is 4 attempts. + // This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times. + // google.protobuf.UInt32Value query_tries = 7 [(validate.rules).uint32 = {gte: 1}]; // Enable round-robin selection of name servers for DNS resolution. When enabled, the resolver will cycle through the // list of name servers for each resolution request. This can help distribute the query load across multiple name // servers. If disabled (default), the resolver will try name servers in the order they are configured. // - // Note: This setting overrides any system configuration for name server rotation. + // .. note:: + // This setting overrides any system configuration for name server rotation. + // bool rotate_nameservers = 8; + + // Maximum EDNS0 UDP payload size in bytes. + // If set, c-ares will include EDNS0 in DNS queries and use this value as the maximum UDP response size. + // + // Recommended values: + // + // * **1232**: Safe default (avoids fragmentation). + // * **4096**: Maximum allowed. + // + // If unset, c-ares uses its internal default (usually 1232). + google.protobuf.UInt32Value edns0_max_payload_size = 9 + [(validate.rules).uint32 = {lte: 4096 gte: 512}]; + + // The maximum duration for which a UDP channel will be kept alive before being refreshed. + // + // If set, the DNS resolver will periodically reinitialize its c-ares channel after the + // specified duration. This can help with avoiding stale socket states, and providing + // better load distribution across UDP ports. + // + // If not specified, no periodic refresh will be performed. + google.protobuf.Duration max_udp_channel_duration = 10 [(validate.rules).duration = {gte {}}]; } diff --git a/api/src/main/proto/envoy/extensions/network/dns_resolver/getaddrinfo/v3/getaddrinfo_dns_resolver.proto b/api/src/main/proto/envoy/extensions/network/dns_resolver/getaddrinfo/v3/getaddrinfo_dns_resolver.proto index 522888a4c..15d0c6d50 100644 --- a/api/src/main/proto/envoy/extensions/network/dns_resolver/getaddrinfo/v3/getaddrinfo_dns_resolver.proto +++ b/api/src/main/proto/envoy/extensions/network/dns_resolver/getaddrinfo/v3/getaddrinfo_dns_resolver.proto @@ -20,16 +20,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // // .. attention:: // -// This resolver uses a single background thread to do resolutions. As such, it is not currently -// advised for use in situations requiring a high resolution rate. A thread pool can be added -// in the future if needed. -// -// .. attention:: -// // Resolutions currently use a hard coded TTL of 60s because the getaddrinfo() API does not // provide the actual TTL. Configuration for this can be added in the future if needed. message GetAddrInfoDnsResolverConfig { // Specifies the number of retries before the resolver gives up. If not specified, the resolver will // retry indefinitely until it succeeds or the DNS query times out. google.protobuf.UInt32Value num_retries = 1; + + // Specifies the number of threads used to resolve pending DNS queries. If not specified, one thread is used. + google.protobuf.UInt32Value num_resolver_threads = 2; } diff --git a/api/src/main/proto/envoy/extensions/quic/connection_id_generator/quic_lb/v3/quic_lb.proto b/api/src/main/proto/envoy/extensions/quic/connection_id_generator/quic_lb/v3/quic_lb.proto index 446ff959d..fac25959d 100644 --- a/api/src/main/proto/envoy/extensions/quic/connection_id_generator/quic_lb/v3/quic_lb.proto +++ b/api/src/main/proto/envoy/extensions/quic/connection_id_generator/quic_lb/v3/quic_lb.proto @@ -29,22 +29,23 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // // .. warning:: // -// This is still a work in progress. Performance is expected to be poor. Interoperability testing -// has not yet been performed. -// [#next-free-field: 6] +// This is still a work in progress. Interoperability testing has not yet been performed. +// [#next-free-field: 7] message Config { option (xds.annotations.v3.message_status).work_in_progress = true; - // Use the unencrypted mode. This is useful for testing, but allows for linking different CIDs - // for the same connection, and leaks information about the valid server IDs in use. This should - // only be used for testing. - bool unsafe_unencrypted_testing_mode = 1; - // Must be at least 1 octet. // The length of server_id and nonce_length_bytes must be 18 or less. // See https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers#name-server-id-allocation. config.core.v3.DataSource server_id = 2 [(validate.rules).message = {required: true}]; + // If true, indicates that the :ref:`server_id + // ` is base64 encoded. + // + // This can be useful if the ID may contain binary data and must be transmitted as a string, for example in + // an environment variable. + bool server_id_base64_encoded = 6; + // Optional validation of the expected server ID length. If this is non-zero and the value in ``server_id`` // does not have a matching length, a configuration error is generated. This can be useful for validating // that the server ID is valid. @@ -65,4 +66,14 @@ message Config { // See https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers#name-config-rotation. transport_sockets.tls.v3.SdsSecretConfig encryption_parameters = 5 [(validate.rules).message = {required: true}]; + + // Use the unencrypted mode. This is useful for testing or a simplified implementation of the + // downstream load balancer, but allows for linking different CIDs for the same connection, and + // leaks information about the valid server IDs in use. This mode does not comply with the RFC. + // + // Note that in this mode, :ref:`encryption_parameters + // ` + // is still required because it contains ``configuration_version``, which is still + // needed. ``encryption_key`` can be set to ``inline_string: '0000000000000000'``. + bool unencrypted_mode = 1; } diff --git a/api/src/main/proto/envoy/extensions/quic/server_preferred_address/v3/fixed_server_preferred_address_config.proto b/api/src/main/proto/envoy/extensions/quic/server_preferred_address/v3/fixed_server_preferred_address_config.proto index 43072fd50..35326c1dc 100644 --- a/api/src/main/proto/envoy/extensions/quic/server_preferred_address/v3/fixed_server_preferred_address_config.proto +++ b/api/src/main/proto/envoy/extensions/quic/server_preferred_address/v3/fixed_server_preferred_address_config.proto @@ -21,19 +21,24 @@ message FixedServerPreferredAddressConfig { message AddressFamilyConfig { // The server preferred address sent to clients. // - // Note: Envoy currently must receive all packets for a QUIC connection on the same port, so unless - // :ref:`dnat_address ` - // is configured, the port for this address must be zero, and the listener's - // port will be used instead. + // .. note:: + // + // Envoy currently requires all packets for a QUIC connection to arrive on the same port. Therefore, unless a + // :ref:`dnat_address ` + // is explicitly configured, the port specified here must be set to zero. In such cases, Envoy will automatically + // use the listener's port. + // config.core.v3.SocketAddress address = 1; - // If there is a DNAT between the client and Envoy, the address that Envoy will observe - // server preferred address packets being sent to. If this is not specified, it is assumed - // there is no DNAT and the server preferred address packets will be sent to the address advertised - // to clients for server preferred address. + // If a DNAT exists between the client and Envoy, this is the address where Envoy will observe incoming server + // preferred address packets. If unspecified, Envoy assumes there is no DNAT, and packets will be sent directly + // to the address advertised to clients as the server preferred address. + // + // .. note:: + // + // Envoy currently requires all packets for a QUIC connection to arrive on the same port. Consequently, the + // port for this address must be set to zero, with Envoy defaulting to the listener's port instead. // - // Note: Envoy currently must receive all packets for a QUIC connection on the same port, so the - // port for this address must be zero, and the listener's port will be used instead. config.core.v3.SocketAddress dnat_address = 2; } diff --git a/api/src/main/proto/envoy/extensions/resource_monitors/cgroup_memory/v3/cgroup_memory.proto b/api/src/main/proto/envoy/extensions/resource_monitors/cgroup_memory/v3/cgroup_memory.proto new file mode 100644 index 000000000..45751be1d --- /dev/null +++ b/api/src/main/proto/envoy/extensions/resource_monitors/cgroup_memory/v3/cgroup_memory.proto @@ -0,0 +1,22 @@ +syntax = "proto3"; + +package envoy.extensions.resource_monitors.cgroup_memory.v3; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.resource_monitors.cgroup_memory.v3"; +option java_outer_classname = "CgroupMemoryProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/resource_monitors/cgroup_memory/v3;cgroup_memoryv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Cgroup Memory] +// [#extension: envoy.resource_monitors.cgroup_memory] + +message CgroupMemoryConfig { + // Optional max memory limit in bytes used for memory pressure calculations. + // If set, this value is used as an upper bound on the memory limit, taking the minimum + // between this value and the system's cgroup memory limit. If not set, the system's + // cgroup memory limit is always used. + uint64 max_memory_bytes = 1; +} diff --git a/api/src/main/proto/envoy/extensions/router/cluster_specifiers/matcher/v3/matcher.proto b/api/src/main/proto/envoy/extensions/router/cluster_specifiers/matcher/v3/matcher.proto new file mode 100644 index 000000000..87851b1d1 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/router/cluster_specifiers/matcher/v3/matcher.proto @@ -0,0 +1,75 @@ +syntax = "proto3"; + +package envoy.extensions.router.cluster_specifiers.matcher.v3; + +import "xds/type/matcher/v3/matcher.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.router.cluster_specifiers.matcher.v3"; +option java_outer_classname = "MatcherProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/router/cluster_specifiers/matcher/v3;matcherv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Matcher Based Cluster Specifier] +// [#extension: envoy.router.cluster_specifier_plugin.matcher] + +message ClusterAction { + // Indicates the upstream cluster to which the request should be routed + // to. + string cluster = 1 [(validate.rules).string = {min_len: 1}]; +} + +message MatcherClusterSpecifier { + // The matcher for cluster selection after the route has been selected. This is used when the + // route has multiple clusters (like multiple clusters for different users) and the matcher + // is used to select the cluster to use for the request. + // + // The match tree to use for grouping incoming requests into buckets. + // + // Example: + // + // .. validated-code-block:: yaml + // :type-name: xds.type.matcher.v3.Matcher + // + // matcher_list: + // matchers: + // - predicate: + // single_predicate: + // input: + // typed_config: + // '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput + // header_name: env + // value_match: + // exact: staging + // on_match: + // action: + // typed_config: + // '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction + // cluster: "staging-cluster" + // + // - predicate: + // single_predicate: + // input: + // typed_config: + // '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput + // header_name: env + // value_match: + // exact: prod + // on_match: + // action: + // typed_config: + // '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction + // cluster: "prod-cluster" + // + // # Catch-all with a default cluster. + // on_no_match: + // action: + // typed_config: + // '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction + // cluster: "default-cluster" + // + xds.type.matcher.v3.Matcher cluster_matcher = 1 [(validate.rules).message = {required: true}]; +} diff --git a/api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto b/api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto index eb7232297..cd71bc31c 100644 --- a/api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto +++ b/api/src/main/proto/envoy/extensions/stat_sinks/open_telemetry/v3/open_telemetry.proto @@ -2,10 +2,14 @@ syntax = "proto3"; package envoy.extensions.stat_sinks.open_telemetry.v3; +import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/grpc_service.proto"; import "google/protobuf/wrappers.proto"; +import "opentelemetry/proto/common/v1/common.proto"; +import "xds/type/matcher/v3/matcher.proto"; + import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -19,8 +23,20 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Stats configuration proto schema for ``envoy.stat_sinks.open_telemetry`` sink. // [#extension: envoy.stat_sinks.open_telemetry] -// [#next-free-field: 7] +// [#next-free-field: 9] message SinkConfig { + // ConversionAction is used to convert a stat to a metric. If a stat matches, + // the metric_name and static_metric_labels will be + // used to create the metric. This can be used to rename a + // stat, add static labels, and aggregate multiple stats into a single metric. + message ConversionAction { + // The metric name to use for the stat. + string metric_name = 2; + + // Static metric labels to use for the metric. + repeated opentelemetry.proto.common.v1.KeyValue static_metric_labels = 3; + } + oneof protocol_specifier { option (validate.required) = true; @@ -28,6 +44,10 @@ message SinkConfig { config.core.v3.GrpcService grpc_service = 1 [(validate.rules).message = {required: true}]; } + // Attributes to be associated with the resource in the OTLP message. + // [#extension-category: envoy.tracers.opentelemetry.resource_detectors] + repeated config.core.v3.TypedExtensionConfig resource_detectors = 7; + // If set to true, counters will be emitted as deltas, and the OTLP message will have // ``AGGREGATION_TEMPORALITY_DELTA`` set as AggregationTemporality. bool report_counters_as_deltas = 2; @@ -50,4 +70,9 @@ message SinkConfig { // "pre", the full stat name will be "pre.foo.bar". If this field is not set, there is no // prefix added. According to the example, the full stat name will remain "foo.bar". 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``. + xds.type.matcher.v3.Matcher custom_metric_conversions = 8; } diff --git a/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/parent_based_sampler.proto b/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/parent_based_sampler.proto new file mode 100644 index 000000000..d5b5d1a12 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/parent_based_sampler.proto @@ -0,0 +1,31 @@ +syntax = "proto3"; + +package envoy.extensions.tracers.opentelemetry.samplers.v3; + +import "envoy/config/core/v3/extension.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.tracers.opentelemetry.samplers.v3"; +option java_outer_classname = "ParentBasedSamplerProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/tracers/opentelemetry/samplers/v3;samplersv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Parent Based Sampler config] +// Configuration for the "ParentBased" Sampler extension. +// The sampler follows the "ParentBased" implementation from the OpenTelemetry +// SDK specification. +// +// See: +// `ParentBased sampler specification `_ +// [#extension: envoy.tracers.opentelemetry.samplers.parent_based] + +message ParentBasedSamplerConfig { + // Specifies the sampler to be used by this sampler. + // The configured sampler will be used if the parent trace ID is not passed to Envoy + // + // required + // [#extension-category: envoy.tracers.opentelemetry.samplers] + config.core.v3.TypedExtensionConfig wrapped_sampler = 1; +} diff --git a/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/trace_id_ratio_based_sampler.proto b/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/trace_id_ratio_based_sampler.proto new file mode 100644 index 000000000..0a97da627 --- /dev/null +++ b/api/src/main/proto/envoy/extensions/tracers/opentelemetry/samplers/v3/trace_id_ratio_based_sampler.proto @@ -0,0 +1,30 @@ +syntax = "proto3"; + +package envoy.extensions.tracers.opentelemetry.samplers.v3; + +import "envoy/type/v3/percent.proto"; + +import "udpa/annotations/status.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.tracers.opentelemetry.samplers.v3"; +option java_outer_classname = "TraceIdRatioBasedSamplerProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/tracers/opentelemetry/samplers/v3;samplersv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Trace Id Ratio Based Sampler config] +// Configuration for the "TraceIdRatioBased" Sampler extension. +// The sampler follows the "TraceIdRatioBased" implementation from the OpenTelemetry +// SDK specification. +// +// See: +// `TraceIdRatioBased sampler specification `_ +// [#extension: envoy.tracers.opentelemetry.samplers.trace_id_ratio_based] + +message TraceIdRatioBasedSamplerConfig { + // If the given trace_id falls into a given percentage of all possible + // trace_id values, ShouldSample will return RECORD_AND_SAMPLE. + // required + // [#extension-category: envoy.tracers.opentelemetry.samplers] + type.v3.FractionalPercent sampling_percentage = 1; +} diff --git a/api/src/main/proto/envoy/extensions/transport_sockets/tap/v3/tap.proto b/api/src/main/proto/envoy/extensions/transport_sockets/tap/v3/tap.proto index aaede4a2a..972bd4457 100644 --- a/api/src/main/proto/envoy/extensions/transport_sockets/tap/v3/tap.proto +++ b/api/src/main/proto/envoy/extensions/transport_sockets/tap/v3/tap.proto @@ -40,4 +40,7 @@ message SocketTapConfig { // Indicates to whether output the connection information per event // This is only applicable if the streamed trace is enabled bool set_connection_per_event = 1; + + // The contents of the transport tap's statistics prefix. + string stats_prefix = 2; } diff --git a/api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto b/api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto index ff90cdde5..517f532f1 100644 --- a/api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto +++ b/api/src/main/proto/envoy/extensions/upstreams/http/v3/http_protocol_options.proto @@ -2,6 +2,7 @@ syntax = "proto3"; 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/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"; @@ -59,7 +60,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // http2_protocol_options: // max_concurrent_streams: 100 // .... [further cluster config] -// [#next-free-field: 8] +// [#next-free-field: 9] 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. @@ -129,6 +130,13 @@ message HttpProtocolOptions { config.core.v3.AlternateProtocolsCacheOptions alternate_protocols_cache_options = 4; } + message OutlierDetection { + // If specified, only responses matching the matcher will be treated by outlier detection as errors. + // If not specified, only 5xx codes are treated by outlier detection as errors. + config.common.matcher.v3.MatchPredicate error_matcher = 1 + [(validate.rules).message = {required: true}]; + } + // This contains options common across HTTP/1 and HTTP/2 config.core.v3.HttpProtocolOptions common_http_protocol_options = 1; @@ -174,4 +182,7 @@ message HttpProtocolOptions { // [#not-implemented-hide:] // [#extension-category: envoy.http.header_validators] config.core.v3.TypedExtensionConfig header_validation_config = 7; + + // Defines http specific outlier detection parameters. + OutlierDetection outlier_detection = 8; } diff --git a/api/src/main/proto/envoy/extensions/wasm/v3/wasm.proto b/api/src/main/proto/envoy/extensions/wasm/v3/wasm.proto index 6ad19ee03..e8fea6725 100644 --- a/api/src/main/proto/envoy/extensions/wasm/v3/wasm.proto +++ b/api/src/main/proto/envoy/extensions/wasm/v3/wasm.proto @@ -6,6 +6,7 @@ import "envoy/config/core/v3/backoff.proto"; import "envoy/config/core/v3/base.proto"; import "google/protobuf/any.proto"; +import "google/protobuf/wrappers.proto"; import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; @@ -19,12 +20,12 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Wasm] // [#extension: envoy.bootstrap.wasm] -// If there is a fatal error on the VM (e.g. exception, abort()), then the policy will be applied. +// If there is a fatal error on the VM (e.g. exception, ``abort()``), then the policy will be applied. enum FailurePolicy { // No policy is specified. The default policy will be used. The default policy is ``FAIL_CLOSED``. UNSPECIFIED = 0; - // New plugin instance will be created for the new request if the VM is failed. Note this only + // New plugin instance will be created for the new request if the VM is failed. Note this will only // be applied to the following failures: // // * ``proxy_wasm::FailState::RuntimeError`` @@ -64,7 +65,8 @@ message CapabilityRestrictionConfig { // Configuration for sanitization of inputs to an allowed capability. // -// NOTE: This is currently unimplemented. +// .. note:: +// This is currently unimplemented. message SanitizationConfig { } @@ -109,14 +111,16 @@ message VmConfig { config.core.v3.AsyncDataSource code = 3; // The Wasm configuration used in initialization of a new VM - // (proxy_on_start). ``google.protobuf.Struct`` is serialized as JSON before + // (``proxy_on_start``). ``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.Any configuration = 4; // Allow the wasm file to include pre-compiled code on VMs which support it. - // Warning: this should only be enable for trusted sources as the precompiled code is not - // verified. + // + // .. warning:: + // This should only be enabled for trusted sources as the precompiled code is not + // verified. bool allow_precompiled = 5; // If true and the code needs to be remotely fetched and it is not in the cache then NACK the configuration @@ -129,7 +133,9 @@ message VmConfig { // are generally called implicitly by your language's standard library. Therefore, you do not // need to call them directly. You can access environment variables in the same way you would // on native platforms. - // Warning: Envoy rejects the configuration if there's conflict of key space. + // + // .. warning:: + // Envoy rejects the configuration if there's conflict of key space. EnvironmentVariables environment_variables = 7; } @@ -143,7 +149,7 @@ message EnvironmentVariables { } // Base Configuration for Wasm Plugins e.g. filters and services. -// [#next-free-field: 9] +// [#next-free-field: 10] message PluginConfig { // A unique name for a filters/services in a VM for use in identifying the filter/service if // multiple filters/services are handled by the same ``vm_id`` and ``root_id`` and for @@ -168,11 +174,14 @@ message PluginConfig { // ``google.protobuf.StringValue`` are passed directly without the wrapper. google.protobuf.Any configuration = 4; - // If there is a fatal error on the VM (e.g. exception, abort(), on_start or on_configure return false), + // If there is a fatal error on the VM (e.g. exception, ``abort()``, ``on_start`` or ``on_configure`` return false), // then all plugins associated with the VM will either fail closed (by default), e.g. by returning an HTTP 503 error, - // or fail open (if 'fail_open' is set to true) by bypassing the filter. Note: when on_start or on_configure return false - // during xDS updates the xDS configuration will be rejected and when on_start or on_configuration return false on initial - // startup the proxy will not start. + // or fail open (if 'fail_open' is set to true) by bypassing the filter. + // + // .. note:: + // When ``on_start`` or ``on_configure`` return ``false`` during xDS updates the xDS configuration will be rejected and when ``on_start`` or ``on_configure`` return ``false`` on + // initial startup the proxy will not start. + // // This field is deprecated in favor of the ``failure_policy`` field. bool fail_open = 5 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; @@ -184,6 +193,10 @@ message PluginConfig { // Configuration for restricting Proxy-Wasm capabilities available to modules. CapabilityRestrictionConfig capability_restriction_config = 6; + + // Whether or not to allow plugin onRequestHeaders and onResponseHeaders callbacks to return + // FilterHeadersStatus::StopIteration. + google.protobuf.BoolValue allow_on_headers_stop_iteration = 9; } // WasmService is configured as a built-in ``envoy.wasm_service`` :ref:`WasmService diff --git a/api/src/main/proto/envoy/service/discovery/v3/discovery.proto b/api/src/main/proto/envoy/service/discovery/v3/discovery.proto index 6f3b12356..e1ce827a4 100644 --- a/api/src/main/proto/envoy/service/discovery/v3/discovery.proto +++ b/api/src/main/proto/envoy/service/discovery/v3/discovery.proto @@ -58,12 +58,12 @@ message ResourceError { message DiscoveryRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DiscoveryRequest"; - // The version_info provided in the request messages will be the version_info + // The ``version_info`` provided in the request messages will be the ``version_info`` // received with the most recent successfully processed response or empty on // the first request. It is expected that no new request is sent after a // response is received until the Envoy instance is ready to ACK/NACK the new // configuration. ACK/NACK takes place by returning the new API config version - // as applied or the previous API config version respectively. Each type_url + // as applied or the previous API config version respectively. Each ``type_url`` // (see below) has an independent version associated with it. string version_info = 1; @@ -72,10 +72,10 @@ message DiscoveryRequest { // List of resources to subscribe to, e.g. list of cluster names or a route // configuration name. If this is empty, all resources for the API are - // returned. LDS/CDS may have empty resource_names, which will cause all + // returned. LDS/CDS may have empty ``resource_names``, which will cause all // resources for the Envoy instance to be returned. The LDS and CDS responses // will then imply a number of resources that need to be fetched via EDS/RDS, - // which will be explicitly enumerated in resource_names. + // which will be explicitly enumerated in ``resource_names``. repeated string resource_names = 3; // [#not-implemented-hide:] @@ -83,21 +83,27 @@ message DiscoveryRequest { // parameters along with each resource name. Clients that populate this // field must be able to handle responses from the server where resources // are wrapped in a Resource message. - // Note that it is legal for a request to have some resources listed - // in ``resource_names`` and others in ``resource_locators``. + // + // .. note:: + // It is legal for a request to have some resources listed + // in ``resource_names`` and others in ``resource_locators``. + // repeated ResourceLocator resource_locators = 7; // Type of the resource that is being requested, e.g. - // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit + // ``type.googleapis.com/envoy.api.v2.ClusterLoadAssignment``. This is implicit // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is // required for ADS. string type_url = 4; - // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above - // discussion on version_info and the DiscoveryResponse nonce comment. This - // may be empty only if 1) this is a non-persistent-stream xDS such as HTTP, - // or 2) the client has not yet accepted an update in this xDS stream (unlike - // delta, where it is populated only for new explicit ACKs). + // nonce corresponding to ``DiscoveryResponse`` being ACK/NACKed. See above + // discussion on ``version_info`` and the ``DiscoveryResponse`` nonce comment. This + // may be empty only if: + // + // * This is a non-persistent-stream xDS such as HTTP, or + // * The client has not yet accepted an update in this xDS stream (unlike + // delta, where it is populated only for new explicit ACKs). + // string response_nonce = 5; // This is populated when the previous :ref:`DiscoveryResponse ` @@ -120,30 +126,34 @@ message DiscoveryResponse { // [#not-implemented-hide:] // Canary is used to support two Envoy command line flags: // - // * --terminate-on-canary-transition-failure. When set, Envoy is able to + // * ``--terminate-on-canary-transition-failure``. When set, Envoy is able to // terminate if it detects that configuration is stuck at canary. Consider // this example sequence of updates: - // - Management server applies a canary config successfully. - // - Management server rolls back to a production config. - // - Envoy rejects the new production config. + // + // * Management server applies a canary config successfully. + // * Management server rolls back to a production config. + // * Envoy rejects the new production config. + // // Since there is no sensible way to continue receiving configuration // updates, Envoy will then terminate and apply production config from a // clean slate. - // * --dry-run-canary. When set, a canary response will never be applied, only + // + // * ``--dry-run-canary``. When set, a canary response will never be applied, only // validated via a dry run. + // bool canary = 3; // Type URL for resources. Identifies the xDS API when muxing over ADS. - // Must be consistent with the type_url in the 'resources' repeated Any (if non-empty). + // Must be consistent with the ``type_url`` in the 'resources' repeated Any (if non-empty). string type_url = 4; // For gRPC based subscriptions, the nonce provides a way to explicitly ack a - // specific DiscoveryResponse in a following DiscoveryRequest. Additional + // specific ``DiscoveryResponse`` in a following ``DiscoveryRequest``. Additional // messages may have been sent by Envoy to the management server for the - // previous version on the stream prior to this DiscoveryResponse, that were + // previous version on the stream prior to this ``DiscoveryResponse``, that were // unprocessed at response send time. The nonce allows the management server - // to ignore any further DiscoveryRequests for the previous version until a - // DiscoveryRequest bearing the nonce. The nonce is optional and is not + // to ignore any further ``DiscoveryRequests`` for the previous version until a + // ``DiscoveryRequest`` bearing the nonce. The nonce is optional and is not // required for non-stream based xDS implementations. string nonce = 5; @@ -171,25 +181,28 @@ message DiscoveryResponse { // connected to it. // // In Delta xDS the nonce field is required and used to pair -// DeltaDiscoveryResponse to a DeltaDiscoveryRequest ACK or NACK. -// Optionally, a response message level system_version_info is present for +// ``DeltaDiscoveryResponse`` to a ``DeltaDiscoveryRequest`` ACK or NACK. +// Optionally, a response message level ``system_version_info`` is present for // debugging purposes only. // -// DeltaDiscoveryRequest plays two independent roles. Any DeltaDiscoveryRequest -// can be either or both of: [1] informing the server of what resources the -// client has gained/lost interest in (using resource_names_subscribe and -// resource_names_unsubscribe), or [2] (N)ACKing an earlier resource update from -// the server (using response_nonce, with presence of error_detail making it a NACK). -// Additionally, the first message (for a given type_url) of a reconnected gRPC stream +// ``DeltaDiscoveryRequest`` plays two independent roles. Any ``DeltaDiscoveryRequest`` +// can be either or both of: +// +// * Informing the server of what resources the client has gained/lost interest in +// (using ``resource_names_subscribe`` and ``resource_names_unsubscribe``), or +// * (N)ACKing an earlier resource update from the server (using ``response_nonce``, +// with presence of ``error_detail`` making it a NACK). +// +// Additionally, the first message (for a given ``type_url``) of a reconnected gRPC stream // has a third role: informing the server of the resources (and their versions) -// that the client already possesses, using the initial_resource_versions field. +// that the client already possesses, using the ``initial_resource_versions`` field. // // As with state-of-the-world, when multiple resource types are multiplexed (ADS), -// all requests/acknowledgments/updates are logically walled off by type_url: +// all requests/acknowledgments/updates are logically walled off by ``type_url``: // a Cluster ACK exists in a completely separate world from a prior Route NACK. -// In particular, initial_resource_versions being sent at the "start" of every -// gRPC stream actually entails a message for each type_url, each with its own -// initial_resource_versions. +// In particular, ``initial_resource_versions`` being sent at the "start" of every +// gRPC stream actually entails a message for each ``type_url``, each with its own +// ``initial_resource_versions``. // [#next-free-field: 10] message DeltaDiscoveryRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DeltaDiscoveryRequest"; @@ -205,23 +218,24 @@ message DeltaDiscoveryRequest { // DeltaDiscoveryRequests allow the client to add or remove individual // resources to the set of tracked resources in the context of a stream. - // All resource names in the resource_names_subscribe list are added to the - // set of tracked resources and all resource names in the resource_names_unsubscribe + // All resource names in the ``resource_names_subscribe`` list are added to the + // set of tracked resources and all resource names in the ``resource_names_unsubscribe`` // list are removed from the set of tracked resources. // - // *Unlike* state-of-the-world xDS, an empty resource_names_subscribe or - // resource_names_unsubscribe list simply means that no resources are to be + // *Unlike* state-of-the-world xDS, an empty ``resource_names_subscribe`` or + // ``resource_names_unsubscribe`` list simply means that no resources are to be // added or removed to the resource list. // *Like* state-of-the-world xDS, the server must send updates for all tracked // resources, but can also send updates for resources the client has not subscribed to. // - // NOTE: the server must respond with all resources listed in resource_names_subscribe, - // even if it believes the client has the most recent version of them. The reason: - // the client may have dropped them, but then regained interest before it had a chance - // to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd. + // .. note:: + // The server must respond with all resources listed in ``resource_names_subscribe``, + // even if it believes the client has the most recent version of them. The reason: + // the client may have dropped them, but then regained interest before it had a chance + // to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd. // - // These two fields can be set in any DeltaDiscoveryRequest, including ACKs - // and initial_resource_versions. + // These two fields can be set in any ``DeltaDiscoveryRequest``, including ACKs + // and ``initial_resource_versions``. // // A list of Resource names to add to the list of tracked resources. repeated string resource_names_subscribe = 3; @@ -232,31 +246,40 @@ message DeltaDiscoveryRequest { // [#not-implemented-hide:] // Alternative to ``resource_names_subscribe`` field that allows specifying dynamic parameters // along with each resource name. - // Note that it is legal for a request to have some resources listed - // in ``resource_names_subscribe`` and others in ``resource_locators_subscribe``. + // + // .. note:: + // It is legal for a request to have some resources listed + // in ``resource_names_subscribe`` and others in ``resource_locators_subscribe``. + // repeated ResourceLocator resource_locators_subscribe = 8; // [#not-implemented-hide:] // Alternative to ``resource_names_unsubscribe`` field that allows specifying dynamic parameters // along with each resource name. - // Note that it is legal for a request to have some resources listed - // in ``resource_names_unsubscribe`` and others in ``resource_locators_unsubscribe``. + // + // .. note:: + // It is legal for a request to have some resources listed + // in ``resource_names_unsubscribe`` and others in ``resource_locators_unsubscribe``. + // repeated ResourceLocator resource_locators_unsubscribe = 9; // Informs the server of the versions of the resources the xDS client knows of, to enable the // client to continue the same logical xDS session even in the face of gRPC stream reconnection. - // It will not be populated: [1] in the very first stream of a session, since the client will - // not yet have any resources, [2] in any message after the first in a stream (for a given - // type_url), since the server will already be correctly tracking the client's state. - // (In ADS, the first message *of each type_url* of a reconnected stream populates this map.) + // It will not be populated: + // + // * In the very first stream of a session, since the client will not yet have any resources. + // * In any message after the first in a stream (for a given ``type_url``), since the server will + // already be correctly tracking the client's state. + // + // (In ADS, the first message ``of each type_url`` of a reconnected stream populates this map.) // The map's keys are names of xDS resources known to the xDS client. // The map's values are opaque resource versions. map initial_resource_versions = 5; - // When the DeltaDiscoveryRequest is a ACK or NACK message in response - // to a previous DeltaDiscoveryResponse, the response_nonce must be the - // nonce in the DeltaDiscoveryResponse. - // Otherwise (unlike in DiscoveryRequest) response_nonce must be omitted. + // When the ``DeltaDiscoveryRequest`` is a ACK or NACK message in response + // to a previous ``DeltaDiscoveryResponse``, the ``response_nonce`` must be the + // nonce in the ``DeltaDiscoveryResponse``. + // Otherwise (unlike in ``DiscoveryRequest``) ``response_nonce`` must be omitted. string response_nonce = 6; // This is populated when the previous :ref:`DiscoveryResponse ` @@ -274,26 +297,26 @@ message DeltaDiscoveryResponse { string system_version_info = 1; // The response resources. These are typed resources, whose types must match - // the type_url field. + // the ``type_url`` field. repeated Resource resources = 2; // field id 3 IS available! // Type URL for resources. Identifies the xDS API when muxing over ADS. - // Must be consistent with the type_url in the Any within 'resources' if 'resources' is non-empty. + // Must be consistent with the ``type_url`` in the Any within 'resources' if 'resources' is non-empty. string type_url = 4; - // Resources names of resources that have be deleted and to be removed from the xDS Client. + // Resource names of resources that have been deleted and to be removed from the xDS Client. // Removed resources for missing resources can be ignored. repeated string removed_resources = 6; - // Alternative to removed_resources that allows specifying which variant of + // Alternative to ``removed_resources`` that allows specifying which variant of // a resource is being removed. This variant must be used for any resource // for which dynamic parameter constraints were sent to the client. repeated ResourceName removed_resource_names = 8; - // The nonce provides a way for DeltaDiscoveryRequests to uniquely - // reference a DeltaDiscoveryResponse when (N)ACKing. The nonce is required. + // The nonce provides a way for ``DeltaDiscoveryRequests`` to uniquely + // reference a ``DeltaDiscoveryResponse`` when (N)ACKing. The nonce is required. string nonce = 5; // [#not-implemented-hide:] @@ -301,17 +324,19 @@ message DeltaDiscoveryResponse { config.core.v3.ControlPlane control_plane = 7; // [#not-implemented-hide:] - // Errors associated with specific resources. Note that a resource in - // this field with a status of NOT_FOUND should be treated the same as - // a resource listed in the 'removed_resources' or 'removed_resource_names' - // fields. + // Errors associated with specific resources. + // + // .. note:: + // A resource in this field with a status of NOT_FOUND should be treated the same as + // a resource listed in the ``removed_resources`` or ``removed_resource_names`` fields. + // repeated ResourceError resource_errors = 9; } // A set of dynamic parameter constraints associated with a variant of an individual xDS resource. // These constraints determine whether the resource matches a subscription based on the set of // dynamic parameters in the subscription, as specified in the -// :ref:`ResourceLocator.dynamic_parameters` +// :ref:`ResourceLocator.dynamic_parameters ` // field. This allows xDS implementations (clients, servers, and caching proxies) to determine // which variant of a resource is appropriate for a given client. message DynamicParameterConstraints { @@ -365,8 +390,11 @@ message Resource { // [#not-implemented-hide:] message CacheControl { // If true, xDS proxies may not cache this resource. - // Note that this does not apply to clients other than xDS proxies, which must cache resources - // for their own use, regardless of the value of this field. + // + // .. note:: + // This does not apply to clients other than xDS proxies, which must cache resources + // for their own use, regardless of the value of this field. + // bool do_not_cache = 1; } @@ -396,7 +424,7 @@ message Resource { // configuration for the resource will be removed. // // The TTL can be refreshed or changed by sending a response that doesn't change the resource - // version. In this case the resource field does not need to be populated, which allows for + // version. In this case the ``resource`` field does not need to be populated, which allows for // light-weight "heartbeat" updates to keep a resource with a TTL alive. // // The TTL feature is meant to support configurations that should be removed in the event of diff --git a/api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto b/api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto index e77d60d0b..406c5c195 100644 --- a/api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto +++ b/api/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto @@ -27,29 +27,31 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // as part of a filter chain. // The overall external processing protocol works like this: // -// 1. Envoy sends to the service information about the HTTP request. -// 2. The service sends back a ProcessingResponse message that directs Envoy -// to either stop processing, continue without it, or send it the -// next chunk of the message body. -// 3. If so requested, Envoy sends the server the message body in chunks, -// or the entire body at once. In either case, the server may send back -// a ProcessingResponse for each message it receives, or wait for certain amount -// of body chunks received before streams back the ProcessingResponse messages. -// 4. If so requested, Envoy sends the server the HTTP trailers, +// 1. The data plane sends to the service information about the HTTP request. +// 2. The service sends back a ProcessingResponse message that directs +// the data plane to either stop processing, continue without it, or send +// it the next chunk of the message body. +// 3. If so requested, the data plane sends the server the message body in +// chunks, or the entire body at once. In either case, the server may send +// back a ProcessingResponse for each message it receives, or wait for +// a certain amount of body chunks received before streaming back the +// ProcessingResponse messages. +// 4. If so requested, the data plane sends the server the HTTP trailers, // and the server sends back a ProcessingResponse. // 5. At this point, request processing is done, and we pick up again -// at step 1 when Envoy receives a response from the upstream server. +// at step 1 when the data plane receives a response from the upstream +// server. // 6. At any point above, if the server closes the gRPC stream cleanly, -// then Envoy proceeds without consulting the server. +// then the data plane proceeds without consulting the server. // 7. At any point above, if the server closes the gRPC stream with an error, -// then Envoy returns a 500 error to the client, unless the filter +// then the data plane returns a 500 error to the client, unless the filter // was configured to ignore errors. // // In other words, the process is a request/response conversation, but // using a gRPC stream to make it easier for the server to // maintain state. service ExternalProcessor { - // This begins the bidirectional stream that Envoy will use to + // This begins the bidirectional stream that the data plane will use to // give the server control over what the filter does. The actual // protocol is described by the ProcessingRequest and ProcessingResponse // messages below. @@ -79,7 +81,7 @@ message ProtocolConfiguration { bool send_body_without_waiting_for_header_response = 3; } -// This represents the different types of messages that Envoy can send +// This represents the different types of messages that the data plane can send // to an external processing server. // [#next-free-field: 12] message ProcessingRequest { @@ -132,7 +134,7 @@ message ProcessingRequest { // The values of properties selected by the ``request_attributes`` // or ``response_attributes`` list in the configuration. Each entry // in the list is populated from the standard - // :ref:`attributes ` supported across Envoy. + // :ref:`attributes ` supported in the data plane. map attributes = 9; // Specify whether the filter that sent this request is running in :ref:`observability_mode @@ -153,7 +155,7 @@ message ProcessingRequest { ProtocolConfiguration protocol_config = 11; } -// This represents the different types of messages the server may send back to Envoy +// This represents the different types of messages the server may send back to the data plane // when the ``observability_mode`` field in the received ProcessingRequest is set to false. // // * If the corresponding ``BodySendMode`` in the @@ -212,8 +214,8 @@ message ProcessingResponse { // may use this to intelligently control how requests are processed // based on the headers and other metadata that they see. // This field is only applicable when servers responding to the header requests. - // If it is set in the response to the body or trailer requests, it will be ignored by Envoy. - // It is also ignored by Envoy when the ext_proc filter config + // If it is set in the response to the body or trailer requests, it will be ignored by the data plane. + // It is also ignored by the data plane when the ext_proc filter config // :ref:`allow_mode_override // ` // is set to false, or @@ -224,16 +226,16 @@ message ProcessingResponse { // 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 Envoy receives this response message, - // it ignores other fields in the response, just stop the original timer, - // which has the timeout value specified in + // with a new timeout value. When the data plane receives this response + // message, it ignores other fields in the response, just stop the original + // timer, which has the timeout value specified in // :ref:`message_timeout // ` // and start a new timer with this ``override_message_timeout`` value and keep the - // Envoy ext_proc filter state machine intact. + // data plane ext_proc filter state machine intact. // Has to be >= 1ms and <= // :ref:`max_message_timeout ` - // Such message can be sent at most once in a particular Envoy ext_proc filter processing state. + // Such message can be sent at most once in a particular data plane ext_proc filter processing state. // To enable this API, one has to set ``max_message_timeout`` to a number >= 1ms. google.protobuf.Duration override_message_timeout = 10; } @@ -283,26 +285,26 @@ message HttpTrailers { // The following are messages that may be sent back by the server. -// This message is sent by the external server to Envoy after ``HttpHeaders`` was +// This message is sent by the external server to the data plane after ``HttpHeaders`` was // sent to it. message HeadersResponse { - // Details the modifications (if any) to be made by Envoy to the current + // Details the modifications (if any) to be made by the data plane to the current // request/response. CommonResponse response = 1; } -// This message is sent by the external server to Envoy after ``HttpBody`` was +// This message is sent by the external server to the data plane after ``HttpBody`` was // sent to it. message BodyResponse { - // Details the modifications (if any) to be made by Envoy to the current + // Details the modifications (if any) to be made by the data plane to the current // request/response. CommonResponse response = 1; } -// This message is sent by the external server to Envoy after ``HttpTrailers`` was +// This message is sent by the external server to the data plane after ``HttpTrailers`` was // sent to it. message TrailersResponse { - // Details the modifications (if any) to be made by Envoy to the current + // Details the modifications (if any) to be made by the data plane to the current // request/response trailers. HeaderMutation header_mutation = 1; } @@ -332,7 +334,7 @@ message CommonResponse { CONTINUE_AND_REPLACE = 1; } - // If set, provide additional direction on how the Envoy proxy should + // If set, provide additional direction on how the data plane should // handle the rest of the HTTP filter chain. ResponseStatus status = 1 [(validate.rules).enum = {defined_only: true}]; @@ -361,7 +363,7 @@ message CommonResponse { // Clear the route cache for the current client request. This is necessary // if the remote server modified headers that are used to calculate the route. // This field is ignored in the response direction. This field is also ignored - // if the Envoy ext_proc filter is in the upstream filter chain. + // if the data plane ext_proc filter is in the upstream filter chain. bool clear_route_cache = 5; } @@ -415,7 +417,7 @@ message HeaderMutation { // The body response message corresponding to FULL_DUPLEX_STREAMED body mode. message StreamedBodyResponse { - // The body response chunk that will be passed to the upstream/downstream by Envoy. + // The body response chunk that will 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 @@ -424,7 +426,7 @@ message StreamedBodyResponse { bool end_of_stream = 2; } -// This message specifies the body mutation the server sends to Envoy. +// This message specifies the body mutation the server sends to the data plane. message BodyMutation { // The type of mutation for the body. oneof mutation { diff --git a/api/src/main/proto/envoy/service/extension/v3/config_discovery.proto b/api/src/main/proto/envoy/service/extension/v3/config_discovery.proto index 8948555c7..0100bcffb 100644 --- a/api/src/main/proto/envoy/service/extension/v3/config_discovery.proto +++ b/api/src/main/proto/envoy/service/extension/v3/config_discovery.proto @@ -18,27 +18,29 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Extension config discovery service (ECDS)] // A service that supports dynamic configuration updates for a specific filter. -// Currently, ECDS is supported for network filters, HTTP filters, UDP session filters and Listener filters. +// Currently, ECDS is supported for network filters, HTTP filters, UDP session filters, and listener filters. // Please check :ref:`Extension Config Discovery Service (ECDS) API `. +// // The overall extension config discovery service works as follows: // -// 1. A filter (:ref:`Downstream Network `, +// #. A filter (:ref:`Downstream Network `, // :ref:`Upstream Network `, // :ref:`Listener `, // :ref:`UDP Session `, // or :ref:`HTTP `) -// contains a :ref:`config_discovery ` configuration. This configuration +// contains a (:ref:`ExtensionConfigSource config discovery `) configuration. This configuration // includes a :ref:`config_source `, // from which the filter configuration will be fetched. -// 2. The client then registers for a resource using the filter name as the resource_name. -// 3. The xDS server sends back the filter's configuration. -// 4. The client stores the configuration that will be used in the next instantiation of the filter chain, +// #. The client then registers for a resource using the filter name as the ``resource_name``. +// #. The xDS server sends back the filter's configuration. +// #. The client stores the configuration that will be used in the next instantiation of the filter chain, // i.e., for the next requests. Whenever an updated filter configuration arrives, it will be taken into // account in the following instantiation of the filter chain. // -// Note: Filters that are configured using ECDS are warmed. For more details see -// :ref:`ExtensionConfigSource `. - +// .. note:: +// Filters that are configured using ECDS are warmed. For more details see +// :ref:`ExtensionConfigSource `. +// // Return extension configurations. service ExtensionConfigDiscoveryService { option (envoy.annotations.resource).type = "envoy.config.core.v3.TypedExtensionConfig"; diff --git a/api/src/main/proto/envoy/service/network_ext_proc/v3/network_external_processor.proto b/api/src/main/proto/envoy/service/network_ext_proc/v3/network_external_processor.proto index 2cba2bea7..c148baf31 100644 --- a/api/src/main/proto/envoy/service/network_ext_proc/v3/network_external_processor.proto +++ b/api/src/main/proto/envoy/service/network_ext_proc/v3/network_external_processor.proto @@ -25,15 +25,17 @@ option (xds.annotations.v3.file_status).work_in_progress = true; // providing access to raw network data. // // The filter communicates with an external gRPC service that can: -// * Inspect network traffic in both directions (client->server and server->client) -// * Modify the payload data -// * Control connection lifecycle (continue, close gracefully, or reset) +// +// 1. Inspect network traffic in both directions (client->server and server->client) +// 2. Modify the payload data +// 3. Control connection lifecycle (continue, close gracefully, or reset) // // Use cases include: -// * Custom protocol inspection and modification -// * Advanced traffic manipulation -// * Security scanning and filtering -// * Dynamic connection management +// +// 1. Custom protocol inspection and modification +// 2. Advanced traffic manipulation +// 3. Security scanning and filtering +// 4. Dynamic connection management // // The service uses a bidirectional gRPC stream, maintaining state throughout // the connection lifetime while allowing asynchronous processing. diff --git a/api/src/main/proto/envoy/type/http/v3/cookie.proto b/api/src/main/proto/envoy/type/http/v3/cookie.proto index 0ceda999d..a7e7e9c4d 100644 --- a/api/src/main/proto/envoy/type/http/v3/cookie.proto +++ b/api/src/main/proto/envoy/type/http/v3/cookie.proto @@ -28,4 +28,20 @@ message Cookie { // Path of cookie. This will be used to set the path of a new cookie when it is generated. // If no path is specified here, no path will be set for the cookie. string path = 3; + + // Additional attributes for the cookie. They will be used when generating a new cookie. + repeated CookieAttribute attributes = 4; +} + +// CookieAttribute defines an API for adding additional attributes for a HTTP cookie. +message CookieAttribute { + // The name of the cookie attribute. + string name = 1 + [(validate.rules).string = + {min_len: 1 max_bytes: 16384 well_known_regex: HTTP_HEADER_NAME strict: false}]; + + // The optional value of the cookie attribute. + string value = 2 [ + (validate.rules).string = {max_bytes: 16384 well_known_regex: HTTP_HEADER_VALUE strict: false} + ]; } diff --git a/api/src/main/proto/envoy/type/matcher/v3/metadata.proto b/api/src/main/proto/envoy/type/matcher/v3/metadata.proto index d3316e88a..30abde97c 100644 --- a/api/src/main/proto/envoy/type/matcher/v3/metadata.proto +++ b/api/src/main/proto/envoy/type/matcher/v3/metadata.proto @@ -16,11 +16,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Metadata matcher] -// MetadataMatcher provides a general interface to check if a given value is matched in -// :ref:`Metadata `. It uses `filter` and `path` to retrieve the value -// from the Metadata and then check if it's matched to the specified value. +// ``MetadataMatcher`` provides a general interface to check if a given value is matched in +// :ref:`Metadata `. It uses ``filter`` and ``path`` to retrieve the value +// from the ``Metadata`` and then check if it's matched to the specified value. // -// For example, for the following Metadata: +// For example, for the following ``Metadata``: // // .. code-block:: yaml // @@ -41,8 +41,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // - string_value: m // - string_value: n // -// The following MetadataMatcher is matched as the path [a, b, c] will retrieve a string value "pro" -// from the Metadata which is matched to the specified prefix match. +// The following ``MetadataMatcher`` is matched as the path ``[a, b, c]`` will retrieve a string value ``pro`` +// from the ``Metadata`` which is matched to the specified prefix match. // // .. code-block:: yaml // @@ -55,7 +55,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // string_match: // prefix: pr // -// The following MetadataMatcher is matched as the code will match one of the string values in the +// The following ``MetadataMatcher`` is matched as the code will match one of the string values in the // list at the path [a, t]. // // .. code-block:: yaml @@ -70,7 +70,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // string_match: // exact: m // -// An example use of MetadataMatcher is specifying additional metadata in envoy.filters.http.rbac to +// An example use of ``MetadataMatcher`` is specifying additional metadata in ``envoy.filters.http.rbac`` to // enforce access control based on dynamic metadata in a request. See :ref:`Permission // ` and :ref:`Principal // `. @@ -79,9 +79,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; message MetadataMatcher { option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.MetadataMatcher"; - // 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. + // 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 { option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.MetadataMatcher.PathSegment"; @@ -89,18 +91,18 @@ message MetadataMatcher { oneof segment { option (validate.required) = true; - // If specified, use the key to retrieve the value in a Struct. + // 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 Metadata. + // The filter name to retrieve the ``Struct`` from the ``Metadata``. string filter = 1 [(validate.rules).string = {min_len: 1}]; - // The path to retrieve the Value from the Struct. + // The path to retrieve the ``Value`` from the ``Struct``. repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; - // The MetadataMatcher is matched if the value retrieved by path is matched to this value. + // The ``MetadataMatcher`` is matched if the value retrieved by path is matched to this value. ValueMatcher value = 3 [(validate.rules).message = {required: true}]; // If true, the match result will be inverted. diff --git a/api/src/main/proto/envoy/type/matcher/v3/string.proto b/api/src/main/proto/envoy/type/matcher/v3/string.proto index 10033749a..56d39565c 100644 --- a/api/src/main/proto/envoy/type/matcher/v3/string.proto +++ b/api/src/main/proto/envoy/type/matcher/v3/string.proto @@ -38,7 +38,10 @@ message StringMatcher { string exact = 1; // The input string must have the prefix specified here. - // Note: empty prefix is not allowed, please use regex instead. + // + // .. note:: + // + // Empty prefix match is not allowed, please use ``safe_regex`` instead. // // Examples: // @@ -46,7 +49,10 @@ message StringMatcher { string prefix = 2 [(validate.rules).string = {min_len: 1}]; // The input string must have the suffix specified here. - // Note: empty prefix is not allowed, please use regex instead. + // + // .. note:: + // + // Empty suffix match is not allowed, please use ``safe_regex`` instead. // // Examples: // @@ -57,7 +63,10 @@ message StringMatcher { RegexMatcher safe_regex = 5 [(validate.rules).message = {required: true}]; // The input string must have the substring specified here. - // Note: empty contains match is not allowed, please use regex instead. + // + // .. note:: + // + // Empty contains match is not allowed, please use ``safe_regex`` instead. // // Examples: // @@ -69,9 +78,10 @@ message StringMatcher { xds.core.v3.TypedExtensionConfig custom = 8; } - // If true, indicates the exact/prefix/suffix/contains matching should be case insensitive. This - // has no effect for the safe_regex match. - // For example, the matcher ``data`` will match both input string ``Data`` and ``data`` if set to true. + // If ``true``, indicates the exact/prefix/suffix/contains matching should be case insensitive. This + // has no effect for the ``safe_regex`` match. + // For example, the matcher ``data`` will match both input string ``Data`` and ``data`` if this option + // is set to ``true``. bool ignore_case = 6; } diff --git a/api/src/main/proto/envoy/type/matcher/v3/value.proto b/api/src/main/proto/envoy/type/matcher/v3/value.proto index d773c6057..8d65c457c 100644 --- a/api/src/main/proto/envoy/type/matcher/v3/value.proto +++ b/api/src/main/proto/envoy/type/matcher/v3/value.proto @@ -17,7 +17,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Value matcher] -// Specifies the way to match a ProtobufWkt::Value. Primitive values and ListValue are supported. +// Specifies the way to match a Protobuf::Value. Primitive values and ListValue are supported. // StructValue is not supported and is always not matched. // [#next-free-field: 8] message ValueMatcher { diff --git a/api/src/main/proto/envoy/type/matcher/value.proto b/api/src/main/proto/envoy/type/matcher/value.proto index 89d341bbb..6452fcede 100644 --- a/api/src/main/proto/envoy/type/matcher/value.proto +++ b/api/src/main/proto/envoy/type/matcher/value.proto @@ -16,7 +16,7 @@ option (udpa.annotations.file_status).package_version_status = FROZEN; // [#protodoc-title: Value matcher] -// Specifies the way to match a ProtobufWkt::Value. Primitive values and ListValue are supported. +// Specifies the way to match a Protobuf::Value. Primitive values and ListValue are supported. // StructValue is not supported and is always not matched. // [#next-free-field: 7] message ValueMatcher { diff --git a/api/src/main/proto/envoy/type/metadata/v3/metadata.proto b/api/src/main/proto/envoy/type/metadata/v3/metadata.proto index 207585775..d131635bf 100644 --- a/api/src/main/proto/envoy/type/metadata/v3/metadata.proto +++ b/api/src/main/proto/envoy/type/metadata/v3/metadata.proto @@ -14,10 +14,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Metadata] -// MetadataKey provides a general interface using ``key`` and ``path`` to retrieve value from -// :ref:`Metadata `. +// MetadataKey provides a way to retrieve values from +// :ref:`Metadata ` using a ``key`` and a ``path``. // -// For example, for the following Metadata: +// For example, consider the following Metadata: // // .. code-block:: yaml // @@ -28,7 +28,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // xyz: // hello: envoy // -// The following MetadataKey will retrieve a string value "bar" from the Metadata. +// The following MetadataKey would retrieve the string value "bar" from the Metadata: // // .. code-block:: yaml // @@ -40,8 +40,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; message MetadataKey { option (udpa.annotations.versioning).previous_message_type = "envoy.type.metadata.v2.MetadataKey"; - // Specifies the segment in a path to retrieve value from Metadata. - // Currently it is only supported to specify the key, i.e. field name, as one segment of a path. + // Specifies a segment in a path for retrieving values from Metadata. + // Currently, only key-based segments (field names) are supported. message PathSegment { option (udpa.annotations.versioning).previous_message_type = "envoy.type.metadata.v2.MetadataKey.PathSegment"; @@ -49,25 +49,27 @@ message MetadataKey { oneof segment { option (validate.required) = true; - // If specified, use the key to retrieve the value in a Struct. + // If specified, use this key to retrieve the value in a Struct. string key = 1 [(validate.rules).string = {min_len: 1}]; } } - // The key name of Metadata to retrieve the Struct from the metadata. - // Typically, it represents a builtin subsystem or custom extension. + // The key name of the Metadata from which to retrieve the Struct. + // This typically represents a builtin subsystem or custom extension. string key = 1 [(validate.rules).string = {min_len: 1}]; - // The path to retrieve the Value from the Struct. It can be a prefix or a full path, - // e.g. ``[prop, xyz]`` for a struct or ``[prop, foo]`` for a string in the example, - // which depends on the particular scenario. + // The path used to retrieve a specific Value from the Struct. + // This can be either a prefix or a full path, depending on the use case. + // For example, ``[prop, xyz]`` would retrieve a struct or ``[prop, foo]`` would retrieve a string + // in the example above. // - // Note: Due to that only the key type segment is supported, the path can not specify a list - // unless the list is the last segment. + // .. note:: + // Since only key-type segments are supported, a path cannot specify a list + // unless the list is the last segment. repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; } -// Describes what kind of metadata. +// Describes different types of metadata sources. message MetadataKind { option (udpa.annotations.versioning).previous_message_type = "envoy.type.metadata.v2.MetadataKind"; diff --git a/api/src/main/proto/opentelemetry/proto/collector/logs/v1/logs_service.proto b/api/src/main/proto/opentelemetry/proto/collector/logs/v1/logs_service.proto index 8260d8aae..8be5cf75e 100644 --- a/api/src/main/proto/opentelemetry/proto/collector/logs/v1/logs_service.proto +++ b/api/src/main/proto/opentelemetry/proto/collector/logs/v1/logs_service.proto @@ -28,8 +28,6 @@ option go_package = "go.opentelemetry.io/proto/otlp/collector/logs/v1"; // OpenTelemetry and an collector, or between an collector and a central collector (in this // case logs are sent/received to/from multiple Applications). service LogsService { - // For performance reasons, it is recommended to keep this RPC - // alive for the entire life of the application. rpc Export(ExportLogsServiceRequest) returns (ExportLogsServiceResponse) {} } diff --git a/api/src/main/proto/opentelemetry/proto/collector/metrics/v1/metrics_service.proto b/api/src/main/proto/opentelemetry/proto/collector/metrics/v1/metrics_service.proto index dd48f1ad3..bc0242844 100644 --- a/api/src/main/proto/opentelemetry/proto/collector/metrics/v1/metrics_service.proto +++ b/api/src/main/proto/opentelemetry/proto/collector/metrics/v1/metrics_service.proto @@ -28,8 +28,6 @@ option go_package = "go.opentelemetry.io/proto/otlp/collector/metrics/v1"; // instrumented with OpenTelemetry and a collector, or between a collector and a // central collector. service MetricsService { - // For performance reasons, it is recommended to keep this RPC - // alive for the entire life of the application. rpc Export(ExportMetricsServiceRequest) returns (ExportMetricsServiceResponse) {} } diff --git a/api/src/main/proto/opentelemetry/proto/collector/profiles/v1development/profiles_service.proto b/api/src/main/proto/opentelemetry/proto/collector/profiles/v1development/profiles_service.proto index ab2433ed2..81bb21064 100644 --- a/api/src/main/proto/opentelemetry/proto/collector/profiles/v1development/profiles_service.proto +++ b/api/src/main/proto/opentelemetry/proto/collector/profiles/v1development/profiles_service.proto @@ -27,8 +27,6 @@ option go_package = "go.opentelemetry.io/proto/otlp/collector/profiles/v1develop // Service that can be used to push profiles between one Application instrumented with // OpenTelemetry and a collector, or between a collector and a central collector. service ProfilesService { - // For performance reasons, it is recommended to keep this RPC - // alive for the entire life of the application. rpc Export(ExportProfilesServiceRequest) returns (ExportProfilesServiceResponse) {} } @@ -39,6 +37,9 @@ message ExportProfilesServiceRequest { // data from multiple origins typically batch the data before forwarding further and // in that case this array will contain multiple elements. repeated opentelemetry.proto.profiles.v1development.ResourceProfiles resource_profiles = 1; + + // The reference table containing all data shared by profiles across the message being sent. + opentelemetry.proto.profiles.v1development.ProfilesDictionary dictionary = 2; } message ExportProfilesServiceResponse { diff --git a/api/src/main/proto/opentelemetry/proto/collector/trace/v1/trace_service.proto b/api/src/main/proto/opentelemetry/proto/collector/trace/v1/trace_service.proto index d6fe67f9e..efbbedbe4 100644 --- a/api/src/main/proto/opentelemetry/proto/collector/trace/v1/trace_service.proto +++ b/api/src/main/proto/opentelemetry/proto/collector/trace/v1/trace_service.proto @@ -28,8 +28,6 @@ option go_package = "go.opentelemetry.io/proto/otlp/collector/trace/v1"; // OpenTelemetry and a collector, or between a collector and a central collector (in this // case spans are sent/received to/from multiple Applications). service TraceService { - // For performance reasons, it is recommended to keep this RPC - // alive for the entire life of the application. rpc Export(ExportTraceServiceRequest) returns (ExportTraceServiceResponse) {} } diff --git a/api/src/main/proto/opentelemetry/proto/common/v1/common.proto b/api/src/main/proto/opentelemetry/proto/common/v1/common.proto index ff8a21a1f..57c9f86e0 100644 --- a/api/src/main/proto/opentelemetry/proto/common/v1/common.proto +++ b/api/src/main/proto/opentelemetry/proto/common/v1/common.proto @@ -79,3 +79,37 @@ message InstrumentationScope { repeated KeyValue attributes = 3; uint32 dropped_attributes_count = 4; } + +// A reference to an Entity. +// Entity represents an object of interest associated with produced telemetry: e.g spans, metrics, profiles, or logs. +// +// Status: [Development] +message EntityRef { + // The Schema URL, if known. This is the identifier of the Schema that the entity data + // is recorded in. To learn more about Schema URL see + // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url + // + // This schema_url applies to the data in this message and to the Resource attributes + // referenced by id_keys and description_keys. + // TODO: discuss if we are happy with this somewhat complicated definition of what + // the schema_url applies to. + // + // This field obsoletes the schema_url field in ResourceMetrics/ResourceSpans/ResourceLogs. + string schema_url = 1; + + // Defines the type of the entity. MUST not change during the lifetime of the entity. + // For example: "service" or "host". This field is required and MUST not be empty + // for valid entities. + string type = 2; + + // Attribute Keys that identify the entity. + // MUST not change during the lifetime of the entity. The Id must contain at least one attribute. + // These keys MUST exist in the containing {message}.attributes. + repeated string id_keys = 3; + + // Descriptive (non-identifying) attribute keys of the entity. + // MAY change over the lifetime of the entity. MAY be empty. + // These attribute keys are not part of entity's identity. + // These keys MUST exist in the containing {message}.attributes. + repeated string description_keys = 4; +} \ No newline at end of file diff --git a/api/src/main/proto/opentelemetry/proto/logs/v1/logs.proto b/api/src/main/proto/opentelemetry/proto/logs/v1/logs.proto index 261d22916..4fe113086 100644 --- a/api/src/main/proto/opentelemetry/proto/logs/v1/logs.proto +++ b/api/src/main/proto/opentelemetry/proto/logs/v1/logs.proto @@ -221,7 +221,5 @@ message LogRecord { // as an event. // // [Optional]. - // - // Status: [Development] string event_name = 12; } diff --git a/api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto b/api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto index 00c5112ce..8915e3c16 100644 --- a/api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto +++ b/api/src/main/proto/opentelemetry/proto/metrics/v1/metrics.proto @@ -194,7 +194,7 @@ message Metric { string description = 2; // unit in which the metric value is reported. Follows the format - // described by http://unitsofmeasure.org/ucum.html. + // described by https://unitsofmeasure.org/ucum.html. string unit = 3; // Data determines the aggregation type (if any) of the metric, what is the @@ -266,7 +266,7 @@ message ExponentialHistogram { // Summary metric data are used to convey quantile summaries, // a Prometheus (see: https://prometheus.io/docs/concepts/metric_types/#summary) -// and OpenMetrics (see: https://github.com/OpenObservability/OpenMetrics/blob/4dbf6075567ab43296eed941037c12951faafb92/protos/prometheus.proto#L45) +// and OpenMetrics (see: https://github.com/prometheus/OpenMetrics/blob/4dbf6075567ab43296eed941037c12951faafb92/protos/prometheus.proto#L45) // data type. These data points cannot always be merged in a meaningful way. // While they can be useful in some applications, histogram data points are // recommended for new applications. @@ -377,6 +377,16 @@ 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 7; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -425,6 +435,16 @@ 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 9; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -461,7 +481,9 @@ message HistogramDataPoint { // The sum of the bucket_counts must equal the value in the count field. // // The number of elements in bucket_counts array must be by one greater than - // the number of elements in explicit_bounds array. + // the number of elements in explicit_bounds array. The exception to this rule + // is when the length of bucket_counts is 0, then the length of explicit_bounds + // must also be 0. repeated fixed64 bucket_counts = 6; // explicit_bounds specifies buckets with explicitly defined bounds for values. @@ -477,6 +499,9 @@ message HistogramDataPoint { // Histogram buckets are inclusive of their upper boundary, except the last // bucket where the boundary is at infinity. This format is intentionally // compatible with the OpenMetrics histogram definition. + // + // If bucket_counts length is 0 then explicit_bounds length must also be 0, + // otherwise the data point is invalid. repeated double explicit_bounds = 7; // (Optional) List of exemplars collected from @@ -504,6 +529,16 @@ 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 1; // StartTimeUnixNano is optional but strongly encouraged, see the @@ -533,7 +568,7 @@ message ExponentialHistogramDataPoint { // doing so. This is specifically to enforce compatibility w/ OpenMetrics, // see: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram optional double sum = 5; - + // scale describes the resolution of the histogram. Boundaries are // located at powers of the base, where: // @@ -571,7 +606,7 @@ message ExponentialHistogramDataPoint { // of counts. message Buckets { // Offset is 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; @@ -585,7 +620,7 @@ message ExponentialHistogramDataPoint { // especially zeros, so uint64 has been selected to ensure // varint encoding. repeated uint64 bucket_counts = 2; - } + } // Flags that apply to this specific data point. See DataPointFlags // for the available flags and their meaning. @@ -620,6 +655,16 @@ 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 7; // StartTimeUnixNano is optional but strongly encouraged, see the diff --git a/api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto b/api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto index 1cb20b05c..dc101770d 100644 --- a/api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto +++ b/api/src/main/proto/opentelemetry/proto/profiles/v1development/profiles.proto @@ -43,15 +43,15 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // Relationships Diagram // -// ┌──────────────────┐ LEGEND -// │ ProfilesData │ -// └──────────────────┘ ─────▶ embedded -// │ -// │ 1-n ─────▷ referenced by index -// ▼ -// ┌──────────────────┐ -// │ ResourceProfiles │ -// └──────────────────┘ +// ┌──────────────────┐ LEGEND +// │ ProfilesData │ ─────┐ +// └──────────────────┘ │ ─────▶ embedded +// │ │ +// │ 1-n │ ─────▷ referenced by index +// ▼ ▼ +// ┌──────────────────┐ ┌────────────────────┐ +// │ ResourceProfiles │ │ ProfilesDictionary │ +// └──────────────────┘ └────────────────────┘ // │ // │ 1-n // ▼ @@ -59,7 +59,7 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // │ ScopeProfiles │ // └──────────────────┘ // │ -// │ 1-1 +// │ 1-n // ▼ // ┌──────────────────┐ // │ Profile │ @@ -67,15 +67,21 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // │ n-1 // │ 1-n ┌───────────────────────────────────────┐ // ▼ │ ▽ -// ┌──────────────────┐ 1-n ┌──────────────┐ ┌──────────┐ -// │ Sample │ ──────▷ │ KeyValue │ │ Link │ -// └──────────────────┘ └──────────────┘ └──────────┘ -// │ 1-n △ △ -// │ 1-n ┌─────────────────┘ │ 1-n -// ▽ │ │ -// ┌──────────────────┐ n-1 ┌──────────────┐ -// │ Location │ ──────▷ │ Mapping │ -// └──────────────────┘ └──────────────┘ +// ┌──────────────────┐ 1-n ┌─────────────────┐ ┌──────────┐ +// │ Sample │ ──────▷ │ KeyValueAndUnit │ │ Link │ +// └──────────────────┘ └─────────────────┘ └──────────┘ +// │ △ △ +// │ n-1 │ │ 1-n +// ▽ │ │ +// ┌──────────────────┐ │ │ +// │ Stack │ │ │ +// └──────────────────┘ │ │ +// │ 1-n │ │ +// │ 1-n ┌────────────────┘ │ +// ▽ │ │ +// ┌──────────────────┐ n-1 ┌─────────────┐ +// │ Location │ ──────▷ │ Mapping │ +// └──────────────────┘ └─────────────┘ // │ // │ 1-n // ▼ @@ -90,6 +96,55 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // └──────────────────┘ // +// ProfilesDictionary represents the profiles data shared across the +// entire message being sent. +// +// 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. + repeated Mapping mapping_table = 1; + + // Locations referenced by samples via Stack.location_indices. + repeated Location location_table = 2; + + // Functions referenced by locations via Line.function_index. + repeated Function function_table = 3; + + // Links referenced by samples via Sample.link_index. + repeated Link link_table = 4; + + // A common table for strings referenced by various messages. + // string_table[0] must always be "". + 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: + // + // "/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 + // + // 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. + repeated KeyValueAndUnit attribute_table = 6; + + // Stacks referenced by samples via Sample.stack_index. + repeated Stack stack_table = 7; +} + // ProfilesData represents the profiles data that can be stored in persistent storage, // OR can be embedded by other protocols that transfer OTLP profiles data but do not // implement the OTLP protocol. @@ -102,11 +157,18 @@ option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development"; // as well. message ProfilesData { // An array of ResourceProfiles. - // For data coming from a single resource this array will typically contain - // one element. Intermediary nodes that receive data from multiple origins - // typically batch the data before forwarding further and in that case this - // array will contain multiple elements. + // For data coming from an SDK profiler, this array will typically contain one + // element. Host-level profilers will usually create one ResourceProfile per + // container, as well as one additional ResourceProfile grouping all samples + // from non-containerized processes. + // Other resource groupings are possible as well and clarified via + // Resource.attributes and semantic conventions. + // Tools that visualize profiles should prefer displaying + // resources_profiles[0].scope_profiles[0].profiles[0] by default. repeated ResourceProfiles resource_profiles = 1; + + // One instance of ProfilesDictionary + ProfilesDictionary dictionary = 2; } @@ -160,95 +222,68 @@ message ScopeProfiles { // that is most useful to humans. There should be enough // information present to determine the original sampled values. // -// - On-disk, the serialized proto must be gzip-compressed. -// // - The profile is represented as a set of samples, where each sample -// references a sequence of locations, and where each location belongs +// references a stack trace which is a list of locations, each belonging // to a mapping. -// - There is a N->1 relationship from sample.location_id entries to -// locations. For every sample.location_id entry there must be a +// - There is a N->1 relationship from Stack.location_indices entries to +// locations. For every Stack.location_indices entry there must be a // unique Location with that index. // - There is an optional N->1 relationship from locations to // mappings. For every nonzero Location.mapping_id there must be a // unique Mapping with that index. -// Represents a complete profile, including sample types, samples, -// mappings to binaries, locations, functions, string table, and additional metadata. -// It modifies and annotates pprof Profile with OpenTelemetry specific fields. +// Represents a complete profile, including sample types, samples, mappings to +// binaries, stacks, locations, functions, string table, and additional +// metadata. It modifies and annotates pprof Profile with OpenTelemetry +// specific fields. // // Note that whilst fields in this message retain the name and field id from pprof in most cases // for ease of understanding data migration, it is not intended that pprof:Profile and // OpenTelemetry:Profile encoding be wire compatible. message Profile { - - // A description of the samples associated with each Sample.value. - // For a cpu profile this might be: - // [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]] + // The type and unit of all Sample.values in this profile. + // For a cpu or off-cpu profile this might be: + // ["cpu","nanoseconds"] or ["off_cpu","nanoseconds"] // For a heap profile, this might be: - // [["allocations","count"], ["space","bytes"]], - // If one of the values represents the number of events represented - // by the sample, by convention it should be at index 0 and use - // sample_type.unit == "count". - repeated ValueType sample_type = 1; + // ["allocated_objects","count"] or ["allocated_space","bytes"], + ValueType sample_type = 1; // The set of samples recorded in this profile. repeated Sample sample = 2; - // Mapping from address ranges to the image/binary/library mapped - // into that address range. mapping[0] will be the main binary. - // If multiple binaries contribute to the Profile and no main - // binary can be identified, mapping[0] has no special meaning. - repeated Mapping mapping_table = 3; - // Locations referenced by samples via location_indices. - repeated Location location_table = 4; - // Array of locations referenced by samples. - repeated int32 location_indices = 5; - // Functions referenced by locations. - repeated Function function_table = 6; - // Lookup table for attributes. - repeated opentelemetry.proto.common.v1.KeyValue attribute_table = 7; - // Represents a mapping between Attribute Keys and Units. - repeated AttributeUnit attribute_units = 8; - // Lookup table for links. - repeated Link link_table = 9; - // A common table for strings referenced by various messages. - // string_table[0] must always be "". - repeated string string_table = 10; - // The following fields 9-14 are informational, do not affect + // The following fields 3-12 are informational, do not affect // interpretation of results. // Time of collection (UTC) represented as nanoseconds past the epoch. - int64 time_nanos = 11; + fixed64 time_unix_nano = 3; // Duration of the profile, if a duration makes sense. - int64 duration_nanos = 12; + uint64 duration_nano = 4; // The kind of events between sampled occurrences. // e.g [ "cpu","cycles" ] or [ "heap","bytes" ] - ValueType period_type = 13; + ValueType period_type = 5; // The number of events between sampled occurrences. - int64 period = 14; + 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 = 15; // Indices into string table. - // Index into the string table of the type of the preferred sample - // value. If unset, clients should default to the last sample value. - int32 default_sample_type_strindex = 16; - + 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. - // - // This field is required. - bytes profile_id = 17; + // all zeroes is considered invalid. It may be used for deduplication and signal + // correlation purposes. It is acceptable to treat two profiles with different values + // 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; // dropped_attributes_count is 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 = 19; + 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 = 20; + string original_payload_format = 10; // 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. @@ -256,30 +291,10 @@ message Profile { // 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 = 21; + bytes original_payload = 11; // References to attributes in attribute_table. [optional] - // It is 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" - // "/http/server_latency": 300 - // "abc.com/myattribute": true - // "abc.com/score": 10.239 - // - // The OpenTelemetry API specification further restricts the allowed value types: - // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute - // Attribute keys MUST be unique (it is not allowed to have more than one - // attribute with the same key). - repeated int32 attribute_indices = 22; -} - -// Represents a mapping between Attribute Keys and Units. -message AttributeUnit { - // Index into string table. - int32 attribute_key_strindex = 1; - // Index into string table. - int32 unit_strindex = 2; + repeated int32 attribute_indices = 12; } // A pointer from a profile Sample to a trace Span. @@ -363,38 +378,49 @@ enum AggregationTemporality { // ValueType describes the type and units of a value, with an optional aggregation temporality. message ValueType { - int32 type_strindex = 1; // Index into string table. - int32 unit_strindex = 2; // Index into string table. + int32 type_strindex = 1; // Index into ProfilesDictionary.string_table. + int32 unit_strindex = 2; // Index into ProfilesDictionary.string_table. AggregationTemporality aggregation_temporality = 3; } -// Each Sample records values encountered in some program -// context. The program context is typically a stack trace, perhaps -// augmented with auxiliary information like the thread-id, some -// indicator of a higher level request being handled etc. +// Each Sample records values encountered in some program context. The program +// context is typically a stack trace, perhaps augmented with auxiliary +// information like the thread-id, some indicator of a higher level request +// being handled etc. +// +// A Sample MUST have have at least one values or timestamps_unix_nano entry. If +// both fields are populated, they MUST contain the same number of elements, and +// the elements at the same index MUST refer to the same event. +// +// Examples of different ways of representing a sample with the total value of 10: +// +// Report of a stacktrace at 10 timestamps (consumers must assume the value is 1 for each point): +// values: [] +// timestamps_unix_nano: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] +// +// Report of a stacktrace with an aggregated value without timestamps: +// values: [10] +// timestamps_unix_nano: [] +// +// Report of a stacktrace at 4 timestamps where each point records a specific value: +// values: [2, 2, 3, 3] +// timestamps_unix_nano: [1, 2, 3, 4] message Sample { - // locations_start_index along with locations_length refers to to a slice of locations in Profile.location_indices. - int32 locations_start_index = 1; - // locations_length along with locations_start_index refers to a slice of locations in Profile.location_indices. - // Supersedes location_index. - int32 locations_length = 2; - // The type and unit of each value is defined by the corresponding - // entry in Profile.sample_type. All samples must have the same - // number of values, the same as the length of Profile.sample_type. - // When aggregating multiple samples into a single sample, the - // result has a list of values that is the element-wise sum of the - // lists of the originals. - repeated int64 value = 3; - // References to attributes in Profile.attribute_table. [optional] - repeated int32 attribute_indices = 4; - - // Reference to link in Profile.link_table. [optional] - optional int32 link_index = 5; - - // Timestamps associated with Sample represented in nanoseconds. These timestamps are expected - // to fall within the Profile's time range. [optional] - repeated uint64 timestamps_unix_nano = 6; + // Reference to stack in ProfilesDictionary.stack_table. + int32 stack_index = 1; + // The type and unit of each value is defined by Profile.sample_type. + repeated int64 values = 2; + // References to attributes in ProfilesDictionary.attribute_table. [optional] + repeated int32 attribute_indices = 3; + + // Reference to link in ProfilesDictionary.link_table. [optional] + // It can be unset / set to 0 if no link exists, as link_table[0] is always a 'null' default value. + int32 link_index = 4; + + // Timestamps associated with Sample represented in nanoseconds. These + // timestamps should fall within the Profile's time range. + repeated fixed64 timestamps_unix_nano = 5; } // Describes the mapping of a binary in memory, including its address range, @@ -409,22 +435,24 @@ message Mapping { // The object this entry is loaded from. This can be a filename on // disk for the main binary and shared libraries, or virtual // abstractions like "[vdso]". - int32 filename_strindex = 4; // Index into string table - // References to attributes in Profile.attribute_table. [optional] + int32 filename_strindex = 4; // Index into ProfilesDictionary.string_table. + // References to attributes in ProfilesDictionary.attribute_table. [optional] repeated int32 attribute_indices = 5; - // The following fields indicate the resolution of symbolic info. - bool has_functions = 6; - bool has_filenames = 7; - bool has_line_numbers = 8; - bool has_inline_frames = 9; +} + +// A Stack represents a stack trace as a list of locations. +message Stack { + // References to locations in ProfilesDictionary.location_table. + // The first location is the leaf frame. + repeated int32 location_indices = 1; } // Describes function and line table debug information. message Location { - // Reference to mapping in Profile.mapping_table. - // It can be unset if the mapping is unknown or not applicable for - // this profile type. - optional int32 mapping_index = 1; + // Reference to mapping in ProfilesDictionary.mapping_table. + // It can be unset / set to 0 if the mapping is unknown or not applicable for + // this profile type, as mapping_table[0] is always a 'null' default mapping. + int32 mapping_index = 1; // The instruction address for this location, if available. It // should be within [Mapping.memory_start...Mapping.memory_limit] // for the corresponding mapping. A non-leaf address may be in the @@ -439,37 +467,39 @@ message Location { // line[0].function_name == "memcpy" // line[1].function_name == "printf" repeated Line line = 3; - // Provides an indication that multiple symbols map to this location's - // address, for example due to identical code folding by the linker. In that - // case the line information above represents one of the multiple - // symbols. This field must be recomputed when the symbolization state of the - // profile changes. - bool is_folded = 4; - - // References to attributes in Profile.attribute_table. [optional] - repeated int32 attribute_indices = 5; + // References to attributes in ProfilesDictionary.attribute_table. [optional] + repeated int32 attribute_indices = 4; } // Details a specific line in a source code, linked to a function. message Line { - // Reference to function in Profile.function_table. + // Reference to function in ProfilesDictionary.function_table. int32 function_index = 1; - // Line number in source code. + // Line number in source code. 0 means unset. int64 line = 2; - // Column number in source code. + // Column number in source code. 0 means unset. int64 column = 3; } // Describes a function, including its human-readable name, system name, // source file, and starting line number in the source. message Function { - // Name of the function, in human-readable form if available. - int32 name_strindex = 1; // Index into string table - // Name of the function, as identified by the system. - // For instance, it can be a C++ mangled name. - int32 system_name_strindex = 2; // Index into string table - // Source file containing the function. - int32 filename_strindex = 3; // Index into string table - // Line number in source file. + // 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. + int32 system_name_strindex = 2; + // Source file containing the function. Empty string if not available. + int32 filename_strindex = 3; + // Line number in source file. 0 means unset. int64 start_line = 4; } + +// A custom 'dictionary native' style of encoding attributes which is more convenient +// for profiles than opentelemetry.proto.common.v1.KeyValue +// Specifically, uses the string table for keys and allows optional unit information. +message KeyValueAndUnit { + int32 key_strindex = 1; + opentelemetry.proto.common.v1.AnyValue value = 2; + int32 unit_strindex = 3; // zero indicates implicit (by semconv) or non-defined unit. +} diff --git a/api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto b/api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto index 6637560bc..8affbe332 100644 --- a/api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto +++ b/api/src/main/proto/opentelemetry/proto/resource/v1/resource.proto @@ -29,9 +29,26 @@ 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 1; // dropped_attributes_count is the number of dropped attributes. If the value is 0, then // no attributes were dropped. uint32 dropped_attributes_count = 2; + + // Set of entities that participate in this Resource. + // + // Note: keys in the references MUST exist in attributes of this message. + // + // Status: [Development] + repeated opentelemetry.proto.common.v1.EntityRef entity_refs = 3; } diff --git a/api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto b/api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto index 24442853e..fec6f9e3a 100644 --- a/api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto +++ b/api/src/main/proto/opentelemetry/proto/trace/v1/trace.proto @@ -206,10 +206,18 @@ message Span { // "example.com/myattribute": true // "example.com/score": 10.239 // - // The OpenTelemetry API specification further restricts the allowed value types: - // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute // 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 9; // dropped_attributes_count is the number of attributes that were discarded. Attributes @@ -230,6 +238,16 @@ message Span { // attributes is 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 3; // dropped_attributes_count is the number of dropped attributes. If the value is 0, @@ -262,6 +280,16 @@ message Span { // attributes is 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. repeated opentelemetry.proto.common.v1.KeyValue attributes = 4; // dropped_attributes_count is the number of dropped attributes. If the value is 0, diff --git a/api/src/main/proto/xds/type/matcher/v3/cel.proto b/api/src/main/proto/xds/type/matcher/v3/cel.proto index a9a4e01ab..a45af9534 100644 --- a/api/src/main/proto/xds/type/matcher/v3/cel.proto +++ b/api/src/main/proto/xds/type/matcher/v3/cel.proto @@ -20,7 +20,7 @@ option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3"; // // The match is ``true``, iff the result of the evaluation is a bool AND true. // In all other cases, the match is ``false``, including but not limited to: non-bool types, -// ``false``, ``null``,`` int(1)``, etc. +// ``false``, ``null``, ``int(1)``, etc. // In case CEL expression raises an error, the result of the evaluation is interpreted "no match". // // Refer to :ref:`Unified Matcher API ` documentation diff --git a/api/src/main/proto/xds/type/matcher/v3/matcher.proto b/api/src/main/proto/xds/type/matcher/v3/matcher.proto index da7c1f91d..cc03ff6e9 100644 --- a/api/src/main/proto/xds/type/matcher/v3/matcher.proto +++ b/api/src/main/proto/xds/type/matcher/v3/matcher.proto @@ -35,6 +35,14 @@ message Matcher { // Protocol-specific action to take. core.v3.TypedExtensionConfig action = 2; } + + // If true and the Matcher matches, the action will be taken but the caller + // will behave as if the Matcher did not match. A subsequent matcher or + // on_no_match action will be used instead. + // This field is not supported in all contexts in which the matcher API is + // used. If this field is set in a context in which it's not supported, + // the resource will be rejected. + bool keep_matching = 3; } // A linear list of field matchers. diff --git a/api/src/main/proto/xds/type/v3/cel.proto b/api/src/main/proto/xds/type/v3/cel.proto index df4f81d90..043990401 100644 --- a/api/src/main/proto/xds/type/v3/cel.proto +++ b/api/src/main/proto/xds/type/v3/cel.proto @@ -47,6 +47,13 @@ message CelExpression { // // If set, takes precedence over ``cel_expr_parsed``. cel.expr.CheckedExpr cel_expr_checked = 4; + + // Unparsed expression in string form. For example, ``request.headers['x-env'] == 'prod'`` will + // get ``x-env`` header value and compare it with ``prod``. + // Check the `Common Expression Language `_ for more details. + // + // If set, takes precedence over ``cel_expr_parsed`` and ``cel_expr_checked``. + string cel_expr_string = 5; } // Extracts a string by evaluating a `Common Expression Language diff --git a/server/src/test/java/io/envoyproxy/controlplane/server/EnvoyContainer.java b/server/src/test/java/io/envoyproxy/controlplane/server/EnvoyContainer.java index e4ce480cc..2eaa1783c 100644 --- a/server/src/test/java/io/envoyproxy/controlplane/server/EnvoyContainer.java +++ b/server/src/test/java/io/envoyproxy/controlplane/server/EnvoyContainer.java @@ -24,7 +24,7 @@ class EnvoyContainer extends GenericContainer { EnvoyContainer(String config, Supplier controlPlanePortSupplier) { // this version is changed automatically by /tools/update-sha.sh:57 // if you change it make sure to reflect changes there - super("envoyproxy/envoy:v1.34.0"); + super("envoyproxy/envoy:v1.36.0"); this.config = config; this.controlPlanePortSupplier = controlPlanePortSupplier; } diff --git a/tools/API_SHAS b/tools/API_SHAS index 68e448f87..c6f67b39f 100644 --- a/tools/API_SHAS +++ b/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="d7809ba2b07fd869d49bfb122b27f6a7977b4d94" +ENVOY_SHA="63ee0dc79dce88117c6bd2df5a742f8eb67ea980" -# dependencies (source: https://github.com/envoyproxy/envoy/blob/d7809ba2b07fd869d49bfb122b27f6a7977b4d94/api/bazel/repository_locations.bzl) +# dependencies (source: https://github.com/envoyproxy/envoy/blob/63ee0dc79dce88117c6bd2df5a742f8eb67ea980/api/bazel/repository_locations.bzl) GOOGLEAPIS_SHA="fd52b5754b2b268bc3a22a10f29844f206abb327" # 2024-09-16 PGV_VERSION="1.0.4" # 2024-01-17 -PROMETHEUS_SHA="0.6.1" # 2024-04-03 -OPENTELEMETRY_VERSION="1.5.0" # 2024-12-17 -CEL_VERSION="0.22.1" # 2025-03-24 -XDS_SHA="b4127c9b8d78b77423fd25169f05b7476b6ea932" # 2024-09-05 +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 diff --git a/tools/envoy_release b/tools/envoy_release index 995ab8e3f..1ff1dd5d8 100644 --- a/tools/envoy_release +++ b/tools/envoy_release @@ -1 +1 @@ -v1.34.0 +v1.36.0