diff --git a/BUILD b/BUILD index 8c28c87d..1a3f3083 100644 --- a/BUILD +++ b/BUILD @@ -5,11 +5,10 @@ load("@rules_proto//proto:defs.bzl", "proto_library") licenses(["notice"]) # Apache 2 proto_library( - name = "protos", + name = "v2_protos", visibility = ["//visibility:public"], deps = [ "//envoy/admin/v2alpha:pkg", - "//envoy/admin/v3:pkg", "//envoy/api/v2:pkg", "//envoy/api/v2/auth:pkg", "//envoy/api/v2/cluster:pkg", @@ -19,17 +18,12 @@ proto_library( "//envoy/api/v2/ratelimit:pkg", "//envoy/api/v2/route:pkg", "//envoy/config/accesslog/v2:pkg", - "//envoy/config/accesslog/v3:pkg", "//envoy/config/bootstrap/v2:pkg", - "//envoy/config/bootstrap/v3:pkg", "//envoy/config/cluster/aggregate/v2alpha:pkg", "//envoy/config/cluster/dynamic_forward_proxy/v2alpha:pkg", "//envoy/config/cluster/redis:pkg", - "//envoy/config/cluster/v3:pkg", "//envoy/config/common/dynamic_forward_proxy/v2alpha:pkg", "//envoy/config/common/tap/v2alpha:pkg", - "//envoy/config/core/v3:pkg", - "//envoy/config/endpoint/v3:pkg", "//envoy/config/filter/accesslog/v2:pkg", "//envoy/config/filter/dubbo/router/v2alpha1:pkg", "//envoy/config/filter/fault/v2:pkg", @@ -84,37 +78,70 @@ proto_library( "//envoy/config/filter/thrift/router/v2alpha1:pkg", "//envoy/config/filter/udp/udp_proxy/v2alpha:pkg", "//envoy/config/grpc_credential/v2alpha:pkg", - "//envoy/config/grpc_credential/v3:pkg", "//envoy/config/health_checker/redis/v2:pkg", "//envoy/config/listener/v2:pkg", - "//envoy/config/listener/v3:pkg", "//envoy/config/metrics/v2:pkg", - "//envoy/config/metrics/v3:pkg", "//envoy/config/overload/v2alpha:pkg", - "//envoy/config/overload/v3:pkg", "//envoy/config/ratelimit/v2:pkg", - "//envoy/config/ratelimit/v3:pkg", "//envoy/config/rbac/v2:pkg", - "//envoy/config/rbac/v3:pkg", "//envoy/config/resource_monitor/fixed_heap/v2alpha:pkg", "//envoy/config/resource_monitor/injected_resource/v2alpha:pkg", "//envoy/config/retry/omit_canary_hosts/v2:pkg", "//envoy/config/retry/previous_hosts/v2:pkg", "//envoy/config/retry/previous_priorities:pkg", - "//envoy/config/route/v3:pkg", - "//envoy/config/tap/v3:pkg", "//envoy/config/trace/v2:pkg", "//envoy/config/trace/v2alpha:pkg", - "//envoy/config/trace/v3:pkg", "//envoy/config/transport_socket/alts/v2alpha:pkg", "//envoy/config/transport_socket/raw_buffer/v2:pkg", "//envoy/config/transport_socket/tap/v2alpha:pkg", "//envoy/data/accesslog/v2:pkg", - "//envoy/data/accesslog/v3:pkg", "//envoy/data/cluster/v2alpha:pkg", "//envoy/data/core/v2alpha:pkg", - "//envoy/data/core/v3:pkg", "//envoy/data/tap/v2alpha:pkg", + "//envoy/service/accesslog/v2:pkg", + "//envoy/service/auth/v2:pkg", + "//envoy/service/discovery/v2:pkg", + "//envoy/service/load_stats/v2:pkg", + "//envoy/service/metrics/v2:pkg", + "//envoy/service/ratelimit/v2:pkg", + "//envoy/service/tap/v2alpha:pkg", + "//envoy/service/trace/v2:pkg", + "//envoy/type:pkg", + "//envoy/type/matcher:pkg", + "//envoy/type/metadata/v2:pkg", + "//envoy/type/tracing/v2:pkg", + ], +) + +proto_library( + name = "v3_protos", + visibility = ["//visibility:public"], + deps = [ + "//envoy/admin/v3:pkg", + "//envoy/config/accesslog/v3:pkg", + "//envoy/config/bootstrap/v3:pkg", + "//envoy/config/cluster/v3:pkg", + "//envoy/config/core/v3:pkg", + "//envoy/config/endpoint/v3:pkg", + "//envoy/config/filter/thrift/router/v2alpha1:pkg", + "//envoy/config/filter/udp/udp_proxy/v2alpha:pkg", + "//envoy/config/grpc_credential/v3:pkg", + "//envoy/config/health_checker/redis/v2:pkg", + "//envoy/config/listener/v3:pkg", + "//envoy/config/metrics/v3:pkg", + "//envoy/config/overload/v3:pkg", + "//envoy/config/ratelimit/v3:pkg", + "//envoy/config/rbac/v3:pkg", + "//envoy/config/resource_monitor/fixed_heap/v2alpha:pkg", + "//envoy/config/resource_monitor/injected_resource/v2alpha:pkg", + "//envoy/config/retry/omit_canary_hosts/v2:pkg", + "//envoy/config/retry/previous_hosts/v2:pkg", + "//envoy/config/route/v3:pkg", + "//envoy/config/tap/v3:pkg", + "//envoy/config/trace/v3:pkg", + "//envoy/data/accesslog/v3:pkg", + "//envoy/data/cluster/v3:pkg", + "//envoy/data/core/v3:pkg", "//envoy/data/tap/v3:pkg", "//envoy/extensions/access_loggers/file/v3:pkg", "//envoy/extensions/access_loggers/grpc/v3:pkg", @@ -179,34 +206,33 @@ proto_library( "//envoy/extensions/transport_sockets/raw_buffer/v3:pkg", "//envoy/extensions/transport_sockets/tap/v3:pkg", "//envoy/extensions/transport_sockets/tls/v3:pkg", - "//envoy/service/accesslog/v2:pkg", "//envoy/service/accesslog/v3:pkg", - "//envoy/service/auth/v2:pkg", "//envoy/service/auth/v3:pkg", "//envoy/service/cluster/v3:pkg", - "//envoy/service/discovery/v2:pkg", "//envoy/service/discovery/v3:pkg", "//envoy/service/endpoint/v3:pkg", "//envoy/service/health/v3:pkg", "//envoy/service/listener/v3:pkg", - "//envoy/service/load_stats/v2:pkg", "//envoy/service/load_stats/v3:pkg", - "//envoy/service/metrics/v2:pkg", "//envoy/service/metrics/v3:pkg", - "//envoy/service/ratelimit/v2:pkg", "//envoy/service/ratelimit/v3:pkg", "//envoy/service/route/v3:pkg", "//envoy/service/runtime/v3:pkg", "//envoy/service/secret/v3:pkg", - "//envoy/service/tap/v2alpha:pkg", "//envoy/service/tap/v3:pkg", - "//envoy/service/trace/v2:pkg", "//envoy/service/trace/v3:pkg", - "//envoy/type:pkg", - "//envoy/type/matcher:pkg", "//envoy/type/matcher/v3:pkg", - "//envoy/type/metadata/v2:pkg", - "//envoy/type/tracing/v2:pkg", + "//envoy/type/metadata/v3:pkg", + "//envoy/type/tracing/v3:pkg", "//envoy/type/v3:pkg", ], ) + +proto_library( + name = "all_protos", + visibility = ["//visibility:public"], + deps = [ + ":v2_protos", + ":v3_protos", + ], +) diff --git a/envoy/admin/v3/config_dump.proto b/envoy/admin/v3/config_dump.proto index 506d070a..8a527f6f 100644 --- a/envoy/admin/v3/config_dump.proto +++ b/envoy/admin/v3/config_dump.proto @@ -91,9 +91,9 @@ message ListenersConfigDump { "envoy.admin.v2alpha.ListenersConfigDump.DynamicListenerState"; // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` - // field at the time that the listener was loaded. In the future, discrete per-listener versions - // may be supported by the API. + // :ref:`version_info ` field at the time + // that the listener was loaded. In the future, discrete per-listener versions may be supported + // by the API. string version_info = 1; // The listener config. @@ -132,9 +132,9 @@ message ListenersConfigDump { UpdateFailureState error_state = 5; } - // This is the :ref:`version_info - // ` in the last processed - // LDS discovery response. If there are only static bootstrap listeners, this field will be "". + // This is the :ref:`version_info ` in the + // last processed LDS discovery response. If there are only static bootstrap listeners, this field + // will be "". string version_info = 1; // The statically loaded listener configs. @@ -169,9 +169,9 @@ message ClustersConfigDump { "envoy.admin.v2alpha.ClustersConfigDump.DynamicCluster"; // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` - // field at the time that the cluster was loaded. In the future, discrete per-cluster versions - // may be supported by the API. + // :ref:`version_info ` field at the time + // that the cluster was loaded. In the future, discrete per-cluster versions may be supported by + // the API. string version_info = 1; // The cluster config. @@ -181,9 +181,9 @@ message ClustersConfigDump { google.protobuf.Timestamp last_updated = 3; } - // This is the :ref:`version_info - // ` in the last processed - // CDS discovery response. If there are only static bootstrap clusters, this field will be "". + // This is the :ref:`version_info ` in the + // last processed CDS discovery response. If there are only static bootstrap clusters, this field + // will be "". string version_info = 1; // The statically loaded cluster configs. @@ -225,8 +225,8 @@ message RoutesConfigDump { "envoy.admin.v2alpha.RoutesConfigDump.DynamicRouteConfig"; // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` - // field at the time that the route configuration was loaded. + // :ref:`version_info ` field at the time that + // the route configuration was loaded. string version_info = 1; // The route config. @@ -273,8 +273,8 @@ message ScopedRoutesConfigDump { string name = 1; // This is the per-resource version information. This version is currently taken from the - // :ref:`version_info ` - // field at the time that the scoped routes configuration was loaded. + // :ref:`version_info ` field at the time that + // the scoped routes configuration was loaded. string version_info = 2; // The scoped route configurations. diff --git a/envoy/api/v2/auth/cert.proto b/envoy/api/v2/auth/cert.proto index 0daf5aca..e2302b26 100644 --- a/envoy/api/v2/auth/cert.proto +++ b/envoy/api/v2/auth/cert.proto @@ -192,8 +192,8 @@ message CertificateValidationContext { // `, // :ref:`verify_certificate_hash // `, or - // :ref:`verify_subject_alt_name - // `) is also + // :ref:`match_subject_alt_names + // `) is also // specified. // // It can optionally contain certificate revocation lists, in which case Envoy will verify diff --git a/envoy/api/v2/cluster.proto b/envoy/api/v2/cluster.proto index 7616d1fe..2d61ef3f 100644 --- a/envoy/api/v2/cluster.proto +++ b/envoy/api/v2/cluster.proto @@ -558,15 +558,12 @@ message Cluster { // :ref:`STATIC`, // :ref:`STRICT_DNS` // or :ref:`LOGICAL_DNS` clusters. - // This field supersedes :ref:`hosts` field. - // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` - // once load_assignment is implemented.] + // This field supersedes the *hosts* field in the v2 API. // // .. attention:: // // Setting this allows non-EDS cluster types to contain embedded EDS equivalent // :ref:`endpoint assignments`. - // Setting this overrides :ref:`hosts` values. // ClusterLoadAssignment load_assignment = 33; diff --git a/envoy/api/v2/core/base.proto b/envoy/api/v2/core/base.proto index c3b99ae8..67a97dd6 100644 --- a/envoy/api/v2/core/base.proto +++ b/envoy/api/v2/core/base.proto @@ -134,7 +134,8 @@ message Node { // Defines the local service cluster name where Envoy is running. Though // optional, it should be set if any of the following features are used: // :ref:`statsd `, :ref:`health check cluster - // verification `, + // verification + // `, // :ref:`runtime override directory `, // :ref:`user agent addition // `, diff --git a/envoy/api/v2/core/health_check.proto b/envoy/api/v2/core/health_check.proto index 806d263e..91aeb76b 100644 --- a/envoy/api/v2/core/health_check.proto +++ b/envoy/api/v2/core/health_check.proto @@ -116,10 +116,7 @@ message HealthCheck { // range are required. Only statuses in the range [100, 600) are allowed. repeated type.Int64Range expected_statuses = 9; - // Use specified application protocol for health checks. This is to replace - // :ref:`use_http2 - // ` in light of - // HTTP3. + // Use specified application protocol for health checks. type.CodecClientType codec_client_type = 10 [(validate.rules).enum = {defined_only: true}]; // An optional service name parameter which is used to validate the identity of diff --git a/envoy/api/v2/route/route_components.proto b/envoy/api/v2/route/route_components.proto index b386ca87..d6c18b50 100644 --- a/envoy/api/v2/route/route_components.proto +++ b/envoy/api/v2/route/route_components.proto @@ -508,7 +508,7 @@ message CorsPolicy { // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS // filter will be enabled for 100% of the requests. // - // If :ref:`runtime_key ` is + // If :ref:`runtime_key ` is // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. core.RuntimeFractionalPercent filter_enabled = 9; } @@ -519,7 +519,7 @@ message CorsPolicy { // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those // fields have to explicitly disable the filter in order for this setting to take effect. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate // and track the request's *Origin* to determine if it's valid but will not enforce any policies. core.RuntimeFractionalPercent shadow_enabled = 10; @@ -568,12 +568,13 @@ message RouteAction { // // **This field is deprecated**. Set the // :ref:`runtime_fraction - // ` field instead. + // ` + // field instead. Mirroring occurs if both this and + // ` + // are not set. string runtime_key = 2 [deprecated = true, (envoy.annotations.disallowed_by_default) = true]; - // If both :ref:`runtime_key - // ` and this field are not - // specified, all requests to the target cluster will be mirrored. + // If not specified, all requests to the target cluster will be mirrored. // // If specified, this field takes precedence over the `runtime_key` field and requests must also // fall under the percentage of matches indicated by this field. @@ -1148,7 +1149,7 @@ message Tracing { // A list of custom tags with unique tag name to create tags for the active span. // It will take effect after merging with the :ref:`corresponding configuration - // ` + // ` // configured in the HTTP connection manager. If two tags with the same name are configured // each in the HTTP connection manager and the route level, the one configured here takes // priority. diff --git a/envoy/config/bootstrap/v2/bootstrap.proto b/envoy/config/bootstrap/v2/bootstrap.proto index cc12345e..f4e47afe 100644 --- a/envoy/config/bootstrap/v2/bootstrap.proto +++ b/envoy/config/bootstrap/v2/bootstrap.proto @@ -26,9 +26,9 @@ option java_multiple_files = true; // [#protodoc-title: Bootstrap] // This proto is supplied via the :option:`-c` CLI flag and acts as the root // of the Envoy v2 configuration. See the :ref:`v2 configuration overview -// ` for more detail. +// ` for more detail. -// Bootstrap :ref:`configuration overview `. +// Bootstrap :ref:`configuration overview `. // [#next-free-field: 21] message Bootstrap { message StaticResources { @@ -61,7 +61,7 @@ message Bootstrap { // configuration source. api.v2.core.ConfigSource cds_config = 2; - // A single :ref:`ADS ` source may be optionally + // A single :ref:`ADS ` source may be optionally // specified. This must have :ref:`api_type // ` :ref:`GRPC // `. Only diff --git a/envoy/config/bootstrap/v3/bootstrap.proto b/envoy/config/bootstrap/v3/bootstrap.proto index f77b41e2..e7ebeb12 100644 --- a/envoy/config/bootstrap/v3/bootstrap.proto +++ b/envoy/config/bootstrap/v3/bootstrap.proto @@ -28,9 +28,9 @@ option java_multiple_files = true; // [#protodoc-title: Bootstrap] // This proto is supplied via the :option:`-c` CLI flag and acts as the root // of the Envoy v2 configuration. See the :ref:`v2 configuration overview -// ` for more detail. +// ` for more detail. -// Bootstrap :ref:`configuration overview `. +// Bootstrap :ref:`configuration overview `. // [#next-free-field: 21] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = @@ -72,7 +72,7 @@ message Bootstrap { // configuration source. core.v3.ConfigSource cds_config = 2; - // A single :ref:`ADS ` source may be optionally + // A single :ref:`ADS ` source may be optionally // specified. This must have :ref:`api_type // ` :ref:`GRPC // `. Only @@ -168,8 +168,8 @@ message Bootstrap { // Always use TCP queries instead of UDP queries for DNS lookups. // This may be overridden on a per-cluster basis in cds_config, // when :ref:`dns_resolvers ` and - // :ref:`use_tcp_for_dns_lookups - // ` are specified. + // :ref:`use_tcp_for_dns_lookups ` are + // specified. bool use_tcp_for_dns_lookups = 20; } diff --git a/envoy/config/cluster/v3/circuit_breaker.proto b/envoy/config/cluster/v3/circuit_breaker.proto index 1b6c1c99..42de29b0 100644 --- a/envoy/config/cluster/v3/circuit_breaker.proto +++ b/envoy/config/cluster/v3/circuit_breaker.proto @@ -96,9 +96,8 @@ message CircuitBreakers { } // If multiple :ref:`Thresholds` - // are defined with the same - // :ref:`RoutingPriority`, the first one in the - // list is used. If no Thresholds is defined for a given + // are defined with the same :ref:`RoutingPriority`, + // the first one in the list is used. If no Thresholds is defined for a given // :ref:`RoutingPriority`, the default values // are used. repeated Thresholds thresholds = 1; diff --git a/envoy/config/cluster/v3/cluster.proto b/envoy/config/cluster/v3/cluster.proto index 74f5f0ba..3a71f8f1 100644 --- a/envoy/config/cluster/v3/cluster.proto +++ b/envoy/config/cluster/v3/cluster.proto @@ -98,8 +98,7 @@ message Cluster { CLUSTER_PROVIDED = 6; // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy - // ` field to determine the LB - // policy. + // ` field to determine the LB policy. // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field // and instead using the new load_balancing_policy field as the one and only mechanism for // configuring this.] @@ -124,9 +123,8 @@ message Cluster { enum ClusterProtocolSelection { // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). - // If :ref:`http2_protocol_options - // ` are present, HTTP2 will - // be used, otherwise HTTP1.1 will be used. + // If :ref:`http2_protocol_options ` are + // present, HTTP2 will be used, otherwise HTTP1.1 will be used. USE_CONFIGURED_PROTOCOL = 0; // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. @@ -236,15 +234,14 @@ message Cluster { [(validate.rules).enum = {defined_only: true}]; // Subset of - // :ref:`keys` - // used by + // :ref:`keys` used by // :ref:`KEYS_SUBSET` // fallback policy. // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. // For any other fallback policy the parameter is not used and should not be set. // Only values also present in - // :ref:`keys` - // are allowed, but `fallback_keys_subset` cannot be equal to `keys`. + // :ref:`keys` are allowed, but + // `fallback_keys_subset` cannot be equal to `keys`. repeated string fallback_keys_subset = 3; } @@ -483,9 +480,8 @@ message Cluster { // Specifies the maximum interval between refreshes. This parameter is optional, but must be // greater than or equal to the - // :ref:`base_interval ` if - // set. The default is 10 times the :ref:`base_interval - // `. + // :ref:`base_interval ` if set. The default + // is 10 times the :ref:`base_interval `. google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}]; } @@ -517,9 +513,9 @@ message Cluster { // Connections to the endpoints whose metadata value under *envoy.transport_socket* // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. // - // If a :ref:`socket match ` with - // empty match criteria is provided, that always match any endpoint. For example, the - // "defaultToPlaintext" socket match in case above. + // If a :ref:`socket match ` with empty match + // criteria is provided, that always match any endpoint. For example, the "defaultToPlaintext" + // socket match in case above. // // If an endpoint metadata's value under *envoy.transport_socket* does not match any // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or @@ -579,17 +575,13 @@ message Cluster { // Setting this is required for specifying members of // :ref:`STATIC`, // :ref:`STRICT_DNS` - // or :ref:`LOGICAL_DNS` - // clusters. This field supersedes :ref:`hosts` - // field. - // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` - // once load_assignment is implemented.] + // or :ref:`LOGICAL_DNS` clusters. + // This field supersedes the *hosts* field in the v2 API. // // .. attention:: // // Setting this allows non-EDS cluster types to contain embedded EDS equivalent // :ref:`endpoint assignments`. - // Setting this overrides :ref:`hosts` values. // endpoint.v3.ClusterLoadAssignment load_assignment = 33; @@ -635,28 +627,24 @@ message Cluster { // If the DNS refresh rate is specified and the cluster type is either // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, + // or :ref:`LOGICAL_DNS`, // this value is used as the cluster’s DNS refresh // rate. The value configured must be at least 1ms. If this setting is not specified, the // value defaults to 5000ms. For cluster types other than // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS` + // and :ref:`LOGICAL_DNS` // this setting is ignored. google.protobuf.Duration dns_refresh_rate = 16 [(validate.rules).duration = {gt {nanos: 1000000}}]; // If the DNS failure refresh rate is specified and the cluster type is either // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, + // or :ref:`LOGICAL_DNS`, // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types - // other than - // :ref:`STRICT_DNS` and - // :ref:`LOGICAL_DNS` - // this setting is ignored. + // other than :ref:`STRICT_DNS` and + // :ref:`LOGICAL_DNS` this setting is + // ignored. // // Note: Currently, DNS failures and empty DNS responses are not treated differently and this // configuration is applied in both situations. @@ -674,15 +662,13 @@ message Cluster { // If DNS resolvers are specified and the cluster type is either // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, + // or :ref:`LOGICAL_DNS`, // this value is used to specify the cluster’s dns resolvers. // If this setting is not specified, the value defaults to the default // resolver, which uses /etc/resolv.conf for configuration. For cluster types // other than // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS` + // and :ref:`LOGICAL_DNS` // this setting is ignored. repeated core.v3.Address dns_resolvers = 18; @@ -741,8 +727,7 @@ message Cluster { // Optional custom transport socket implementation to use for upstream connections. // To setup TLS, set a transport socket with name `tls` and - // :ref:`UpstreamTlsContexts - // ` in the `typed_config`. + // :ref:`UpstreamTlsContexts ` in the `typed_config`. // If no transport socket configuration is specified, new connections // will be set up with plaintext. core.v3.TransportSocket transport_socket = 24; diff --git a/envoy/config/core/v3/base.proto b/envoy/config/core/v3/base.proto index a07c8cd4..85218a90 100644 --- a/envoy/config/core/v3/base.proto +++ b/envoy/config/core/v3/base.proto @@ -67,10 +67,9 @@ message Locality { // Defines the local service zone where Envoy is running. Though optional, it // should be set if discovery service routing is used and the discovery - // service exposes :ref:`zone data - // `, either in this message or - // via :option:`--service-zone`. The meaning of zone is context dependent, e.g. `Availability Zone - // (AZ) + // service exposes :ref:`zone data `, + // either in this message or via :option:`--service-zone`. The meaning of zone + // is context dependent, e.g. `Availability Zone (AZ) // `_ // on AWS, `Zone `_ on // GCP, etc. @@ -147,7 +146,8 @@ message Node { // Defines the local service cluster name where Envoy is running. Though // optional, it should be set if any of the following features are used: // :ref:`statsd `, :ref:`health check cluster - // verification `, + // verification + // `, // :ref:`runtime override directory `, // :ref:`user agent addition // `, @@ -392,10 +392,10 @@ message SocketOption { // .. note:: // // Parsing of the runtime key's data is implemented such that it may be represented as a -// :ref:`FractionalPercent ` proto represented as -// JSON/YAML and may also be represented as an integer with the assumption that the value is an -// integral percentage out of 100. For instance, a runtime key lookup returning the value "42" -// would parse as a `FractionalPercent` whose numerator is 42 and denominator is HUNDRED. +// :ref:`FractionalPercent ` proto represented as JSON/YAML +// and may also be represented as an integer with the assumption that the value is an integral +// percentage out of 100. For instance, a runtime key lookup returning the value "42" would parse +// as a `FractionalPercent` whose numerator is 42 and denominator is HUNDRED. message RuntimeFractionalPercent { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.RuntimeFractionalPercent"; diff --git a/envoy/config/core/v3/grpc_service.proto b/envoy/config/core/v3/grpc_service.proto index 06d76098..0c3be242 100644 --- a/envoy/config/core/v3/grpc_service.proto +++ b/envoy/config/core/v3/grpc_service.proto @@ -203,8 +203,7 @@ message GrpcService { // The target URI when using the `Google C++ gRPC client // `_. SSL credentials will be supplied in - // :ref:`channel_credentials - // `. + // :ref:`channel_credentials `. string target_uri = 1 [(validate.rules).string = {min_bytes: 1}]; ChannelCredentials channel_credentials = 2; diff --git a/envoy/config/core/v3/health_check.proto b/envoy/config/core/v3/health_check.proto index a1e39dee..624b7f6e 100644 --- a/envoy/config/core/v3/health_check.proto +++ b/envoy/config/core/v3/health_check.proto @@ -113,10 +113,7 @@ message HealthCheck { // range are required. Only statuses in the range [100, 600) are allowed. repeated type.v3.Int64Range expected_statuses = 9; - // Use specified application protocol for health checks. This is to replace - // :ref:`use_http2 - // ` in light of - // HTTP3. + // Use specified application protocol for health checks. type.v3.CodecClientType codec_client_type = 10 [(validate.rules).enum = {defined_only: true}]; // An optional service name parameter which is used to validate the identity of @@ -200,9 +197,8 @@ message HealthCheck { // Specifies the ALPN protocols for health check connections. This is useful if the // corresponding upstream is using ALPN-based :ref:`FilterChainMatch - // ` along with different protocols for - // health checks versus data connections. If empty, no ALPN protocols will be set on health - // check connections. + // ` along with different protocols for health checks + // versus data connections. If empty, no ALPN protocols will be set on health check connections. repeated string alpn_protocols = 1; } diff --git a/envoy/config/filter/http/csrf/v2/csrf.proto b/envoy/config/filter/http/csrf/v2/csrf.proto index f1463066..ce38714b 100644 --- a/envoy/config/filter/http/csrf/v2/csrf.proto +++ b/envoy/config/filter/http/csrf/v2/csrf.proto @@ -21,7 +21,7 @@ option (udpa.annotations.file_migrate).move_to_package = "envoy.extensions.filte message CsrfPolicy { // Specifies the % of requests for which the CSRF filter is enabled. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests to filter. // // .. note:: @@ -35,7 +35,7 @@ message CsrfPolicy { // // This is intended to be used when ``filter_enabled`` is off and will be ignored otherwise. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate // and track the request's *Origin* and *Destination* to determine if it's valid, but will not // enforce any policies. diff --git a/envoy/config/filter/http/ext_authz/v2/ext_authz.proto b/envoy/config/filter/http/ext_authz/v2/ext_authz.proto index 064040fd..d80ca7f4 100644 --- a/envoy/config/filter/http/ext_authz/v2/ext_authz.proto +++ b/envoy/config/filter/http/ext_authz/v2/ext_authz.proto @@ -90,7 +90,7 @@ message ExtAuthz { // Specifies if the filter is enabled. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests to filter. // // If this field is not specified, the filter will be enabled for all requests. diff --git a/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto b/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto index 3eac388c..f0996392 100644 --- a/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto +++ b/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto @@ -235,8 +235,8 @@ message RedisProxy { } // RedisProtocolOptions specifies Redis upstream protocol options. This object is used in -// :ref:`extension_protocol_options`, keyed -// by the name `envoy.redis_proxy`. +// :ref:`typed_extension_protocol_options`, +// keyed by the name `envoy.redis_proxy`. message RedisProtocolOptions { // Upstream server password as defined by the `requirepass` directive // `_ in the server's configuration file. diff --git a/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto b/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto index 7430ec88..91ac5da3 100644 --- a/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto +++ b/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto @@ -101,8 +101,9 @@ message ThriftFilter { } // ThriftProtocolOptions specifies Thrift upstream protocol options. This object is used in -// in :ref:`extension_protocol_options`, keyed -// by the name `envoy.filters.network.thrift_proxy`. +// in +// :ref:`typed_extension_protocol_options`, +// keyed by the name `envoy.filters.network.thrift_proxy`. message ThriftProtocolOptions { // Supplies the type of transport that the Thrift proxy should use for upstream connections. // Selecting diff --git a/envoy/config/listener/v3/listener.proto b/envoy/config/listener/v3/listener.proto index 9ea16084..bd81a9ef 100644 --- a/envoy/config/listener/v3/listener.proto +++ b/envoy/config/listener/v3/listener.proto @@ -96,8 +96,8 @@ message Listener { // A list of filter chains to consider for this listener. The // :ref:`FilterChain ` with the most specific - // :ref:`FilterChainMatch ` criteria is used on - // a connection. + // :ref:`FilterChainMatch ` criteria is used on a + // connection. // // Example using SNI for filter chain selection can be found in the // :ref:`FAQ entry `. @@ -118,11 +118,11 @@ message Listener { // Listener filters have the opportunity to manipulate and augment the connection metadata that // is used in connection filter chain matching, for example. These filters are run before any in - // :ref:`filter_chains `. Order matters - // as the filters are processed sequentially right after a socket has been accepted by the - // listener, and before a connection is created. UDP Listener filters can be specified when the - // protocol in the listener socket address in :ref:`protocol - // ` is :ref:`UDP + // :ref:`filter_chains `. Order matters as the + // filters are processed sequentially right after a socket has been accepted by the listener, and + // before a connection is created. + // UDP Listener filters can be specified when the protocol in the listener socket address in + // :ref:`protocol ` is :ref:`UDP // `. // UDP listeners currently support a single filter. repeated ListenerFilter listener_filters = 9; @@ -147,14 +147,15 @@ message Listener { // *iptables* *TPROXY* target, in which case the original source and destination addresses and // ports are preserved on accepted connections. This flag should be used in combination with // :ref:`an original_dst ` :ref:`listener filter - // ` to mark the connections' local - // addresses as "restored." This can be used to hand off each redirected connection to another - // listener associated with the connection's destination address. Direct connections to the socket - // without using *TPROXY* cannot be distinguished from connections redirected using *TPROXY* and - // are therefore treated as if they were redirected. When this flag is set to false, the - // listener's socket is explicitly reset as non-transparent. Setting this flag requires Envoy to - // run with the *CAP_NET_ADMIN* capability. When this flag is not set (default), the socket is not - // modified, i.e. the transparent option is neither set nor reset. + // ` to mark the connections' local addresses as + // "restored." This can be used to hand off each redirected connection to another listener + // associated with the connection's destination address. Direct connections to the socket without + // using *TPROXY* cannot be distinguished from connections redirected using *TPROXY* and are + // therefore treated as if they were redirected. + // When this flag is set to false, the listener's socket is explicitly reset as non-transparent. + // Setting this flag requires Envoy to run with the *CAP_NET_ADMIN* capability. + // When this flag is not set (default), the socket is not modified, i.e. the transparent option + // is neither set nor reset. google.protobuf.BoolValue transparent = 10; // Whether the listener should set the *IP_FREEBIND* socket option. When this @@ -190,16 +191,16 @@ message Listener { // If the protocol in the listener socket address in :ref:`protocol // ` is :ref:`UDP - // `, this field specifies the - // actual udp listener to create, i.e. :ref:`udp_listener_name - // ` = "raw_udp_listener" - // for creating a packet-oriented UDP listener. If not present, treat it as "raw_udp_listener". + // `, this field specifies the actual udp + // listener to create, i.e. :ref:`udp_listener_name + // ` = "raw_udp_listener" for + // creating a packet-oriented UDP listener. If not present, treat it as "raw_udp_listener". UdpListenerConfig udp_listener_config = 18; // Used to represent an API listener, which is used in non-proxy clients. The type of API // exposed to the non-proxy application depends on the type of API listener. - // When this field is set, no other field except for - // :ref:`name` should be set. + // When this field is set, no other field except for :ref:`name` + // should be set. // // .. note:: // diff --git a/envoy/config/listener/v3/listener_components.proto b/envoy/config/listener/v3/listener_components.proto index 9b6f4b8b..afdfb59d 100644 --- a/envoy/config/listener/v3/listener_components.proto +++ b/envoy/config/listener/v3/listener_components.proto @@ -195,10 +195,9 @@ message FilterChain { // Optional custom transport socket implementation to use for downstream connections. // To setup TLS, set a transport socket with name `tls` and - // :ref:`DownstreamTlsContext - // ` in the - // `typed_config`. If no transport socket configuration is specified, new connections will be set - // up with plaintext. + // :ref:`DownstreamTlsContext ` in the `typed_config`. + // If no transport socket configuration is specified, new connections + // will be set up with plaintext. core.v3.TransportSocket transport_socket = 6; // [#not-implemented-hide:] The unique name (or empty) by which this filter chain is known. If no diff --git a/envoy/config/rbac/v3/rbac.proto b/envoy/config/rbac/v3/rbac.proto index 355b072a..3320c86a 100644 --- a/envoy/config/rbac/v3/rbac.proto +++ b/envoy/config/rbac/v3/rbac.proto @@ -158,9 +158,9 @@ message Permission { // // * If the :ref:`TLS Inspector ` // filter is not added, and if a `FilterChainMatch` is not defined for - // the :ref:`server name - // `, a TLS connection's - // requested SNI server name will be treated as if it wasn't present. + // the :ref:`server name `, + // a TLS connection's requested SNI server name will be treated as if it + // wasn't present. // // * A :ref:`listener filter ` may // overwrite a connection's requested server name within Envoy. diff --git a/envoy/config/route/v3/BUILD b/envoy/config/route/v3/BUILD index e96fada4..019cf275 100644 --- a/envoy/config/route/v3/BUILD +++ b/envoy/config/route/v3/BUILD @@ -11,7 +11,7 @@ api_proto_package( "//envoy/api/v2/route:pkg", "//envoy/config/core/v3:pkg", "//envoy/type/matcher/v3:pkg", - "//envoy/type/tracing/v2:pkg", + "//envoy/type/tracing/v3:pkg", "//envoy/type/v3:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], diff --git a/envoy/config/route/v3/route.proto b/envoy/config/route/v3/route.proto index ef3ab0e1..96faec71 100644 --- a/envoy/config/route/v3/route.proto +++ b/envoy/config/route/v3/route.proto @@ -26,8 +26,8 @@ message RouteConfiguration { // The name of the route configuration. For example, it might match // :ref:`route_config_name - // ` - // in :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.Rds`. + // ` in + // :ref:`envoy_api_msg_extensions.filters.network.http_connection_manager.v3.Rds`. string name = 1; // An array of virtual hosts that make up the route table. @@ -49,8 +49,8 @@ message RouteConfiguration { // Specifies a list of HTTP headers that should be added to each response that // the connection manager encodes. Headers specified at this level are applied - // after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on + // after headers from any enclosed :ref:`envoy_api_msg_config.route.v3.VirtualHost` or + // :ref:`envoy_api_msg_config.route.v3.RouteAction`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption response_headers_to_add = 4 @@ -62,8 +62,8 @@ message RouteConfiguration { // Specifies a list of HTTP headers that should be added to each request // routed by the HTTP connection manager. Headers specified at this level are - // applied after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on + // applied after headers from any enclosed :ref:`envoy_api_msg_config.route.v3.VirtualHost` or + // :ref:`envoy_api_msg_config.route.v3.RouteAction`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption request_headers_to_add = 6 diff --git a/envoy/config/route/v3/route_components.proto b/envoy/config/route/v3/route_components.proto index 3f6fc1f3..f28ab12d 100644 --- a/envoy/config/route/v3/route_components.proto +++ b/envoy/config/route/v3/route_components.proto @@ -5,7 +5,7 @@ package envoy.config.route.v3; import "envoy/config/core/v3/base.proto"; import "envoy/type/matcher/v3/regex.proto"; import "envoy/type/matcher/v3/string.proto"; -import "envoy/type/tracing/v2/custom_tag.proto"; +import "envoy/type/tracing/v3/custom_tag.proto"; import "envoy/type/v3/percent.proto"; import "envoy/type/v3/range.proto"; @@ -93,8 +93,8 @@ message VirtualHost { // Specifies a list of HTTP headers that should be added to each request // handled by this virtual host. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // after headers from enclosed :ref:`envoy_api_msg_config.route.v3.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including // details on header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption request_headers_to_add = 7 @@ -106,8 +106,8 @@ message VirtualHost { // Specifies a list of HTTP headers that should be added to each response // handled by this virtual host. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // after headers from enclosed :ref:`envoy_api_msg_config.route.v3.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including // details on header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption response_headers_to_add = 10 @@ -218,8 +218,8 @@ message Route { // Specifies a set of headers that will be added to requests matching this // route. Headers specified at this level are applied before headers from the - // enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // enclosing :ref:`envoy_api_msg_config.route.v3.VirtualHost` and + // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption request_headers_to_add = 9 @@ -231,8 +231,8 @@ message Route { // Specifies a set of headers that will be added to responses to requests // matching this route. Headers specified at this level are applied before - // headers from the enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // headers from the enclosing :ref:`envoy_api_msg_config.route.v3.VirtualHost` and + // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including // details on header value syntax, see the documentation on // :ref:`custom request headers `. repeated core.v3.HeaderValueOption response_headers_to_add = 10 @@ -252,11 +252,12 @@ message Route { google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; } -// Compared to the :ref:`cluster ` field that -// specifies a single upstream cluster as the target of a request, the :ref:`weighted_clusters -// ` option 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 the weights. +// Compared to the :ref:`cluster ` field that specifies a +// single upstream cluster as the target of a request, the :ref:`weighted_clusters +// ` option 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 the +// weights. message WeightedCluster { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.WeightedCluster"; @@ -274,46 +275,44 @@ message WeightedCluster { string name = 1 [(validate.rules).string = {min_bytes: 1}]; // An integer between 0 and :ref:`total_weight - // `. When a request matches the - // route, the choice of an upstream cluster is determined by its weight. The sum of weights - // across all entries in the clusters array must add up to the total_weight, which defaults to - // 100. + // `. When a request matches the route, + // the choice of an upstream cluster is determined by its weight. The sum of weights across all + // entries in the clusters array must add up to the total_weight, which defaults to 100. google.protobuf.UInt32Value weight = 2; // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in // the upstream cluster with metadata matching what is set in this field will be considered for // load balancing. Note that this will be merged with what's provided in - // :ref:`RouteAction.metadata_match - // `, with values here taking - // precedence. The filter name should be specified as *envoy.lb*. + // :ref:`RouteAction.metadata_match `, with + // values here taking precedence. The filter name should be specified as *envoy.lb*. core.v3.Metadata metadata_match = 3; // Specifies a list of headers to be added to requests when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`. // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.VirtualHost`, and + // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption request_headers_to_add = 4 [(validate.rules).repeated = {max_items: 1000}]; // Specifies a list of HTTP headers that should be removed from each request when - // this cluster is selected through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // this cluster is selected through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`. repeated string request_headers_to_remove = 9; // Specifies a list of headers to be added to responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`. // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.VirtualHost`, and + // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. repeated core.v3.HeaderValueOption response_headers_to_add = 5 [(validate.rules).repeated = {max_items: 1000}]; // Specifies a list of headers to be removed from responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`. repeated string response_headers_to_remove = 6; // The per_filter_config field can be used to provide weighted cluster-specific @@ -470,7 +469,7 @@ message CorsPolicy { // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS // filter will be enabled for 100% of the requests. // - // If :ref:`runtime_key ` is + // If :ref:`runtime_key ` is // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. core.v3.RuntimeFractionalPercent filter_enabled = 9; } @@ -481,7 +480,7 @@ message CorsPolicy { // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those // fields have to explicitly disable the filter in order for this setting to take effect. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate // and track the request's *Origin* to determine if it's valid but will not enforce any policies. core.v3.RuntimeFractionalPercent shadow_enabled = 10; @@ -528,9 +527,7 @@ message RouteAction { // exist in the cluster manager configuration. string cluster = 1 [(validate.rules).string = {min_bytes: 1}]; - // If both :ref:`runtime_key - // ` and this field - // are not specified, all requests to the target cluster will be mirrored. + // If not specified, all requests to the target cluster will be mirrored. // // If specified, this field takes precedence over the `runtime_key` field and requests must also // fall under the percentage of matches indicated by this field. @@ -703,8 +700,8 @@ message RouteAction { // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints // in the upstream cluster with metadata matching what's set in this field will be considered // for load balancing. If using :ref:`weighted_clusters - // `, metadata will be merged, with - // values provided there taking precedence. The filter name should be specified as *envoy.lb*. + // `, metadata will be merged, with values + // provided there taking precedence. The filter name should be specified as *envoy.lb*. core.v3.Metadata metadata_match = 4; // Indicates that during forwarding, the matched prefix (or path) should be @@ -809,8 +806,8 @@ message RouteAction { // Specifies if the rate limit filter should include the virtual host rate // limits. By default, if the route configured rate limits, the virtual host - // :ref:`rate_limits ` are not applied to - // the request. + // :ref:`rate_limits ` are not applied to the + // request. google.protobuf.BoolValue include_vh_rate_limits = 14; // Specifies a list of hash policies to use for ring hash load balancing. Each @@ -833,9 +830,9 @@ message RouteAction { // If present, and the request is a gRPC request, use the // `grpc-timeout header `_, // or its default value (infinity) instead of - // :ref:`timeout `, but limit the applied - // timeout to the maximum value specified here. If configured as 0, the maximum allowed timeout - // for gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used + // :ref:`timeout `, but limit the applied timeout + // to the maximum value specified here. If configured as 0, the maximum allowed timeout for + // gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used // and gRPC requests time out like any other requests using // :ref:`timeout ` or its default. // This can be used to prevent unexpected upstream request timeouts due to potentially long @@ -857,14 +854,13 @@ message RouteAction { // An internal redirect is handled, iff the number of previous internal redirects that a // downstream request has encountered is lower than this value, and - // :ref:`internal_redirect_action - // ` is set to - // :ref:`HANDLE_INTERNAL_REDIRECT + // :ref:`internal_redirect_action ` + // is set to :ref:`HANDLE_INTERNAL_REDIRECT // ` // In the case where a downstream request is bounced among multiple routes by internal redirect, // the first route that hits this threshold, or has - // :ref:`internal_redirect_action - // ` set to + // :ref:`internal_redirect_action ` + // set to // :ref:`PASS_THROUGH_INTERNAL_REDIRECT // ` // will pass the redirect back to downstream. @@ -1069,8 +1065,7 @@ message RedirectAction { // .. attention:: // // Pay attention to the use of trailing slashes as mentioned in - // :ref:`RouteAction's prefix_rewrite - // `. + // :ref:`RouteAction's prefix_rewrite `. string prefix_rewrite = 5; } @@ -1096,8 +1091,8 @@ message DirectResponseAction { // .. note:: // // Headers can be specified using *response_headers_to_add* in the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_RouteConfiguration` or - // :ref:`envoy_api_msg_route.VirtualHost`. + // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.RouteConfiguration` or + // :ref:`envoy_api_msg_config.route.v3.VirtualHost`. core.v3.DataSource body = 2; } @@ -1145,11 +1140,11 @@ message Tracing { // A list of custom tags with unique tag name to create tags for the active span. // It will take effect after merging with the :ref:`corresponding configuration - // ` + // ` // configured in the HTTP connection manager. If two tags with the same name are configured // each in the HTTP connection manager and the route level, the one configured here takes // priority. - repeated type.tracing.v2.CustomTag custom_tags = 4; + repeated type.tracing.v3.CustomTag custom_tags = 4; } // A virtual cluster is a way of specifying a regex matching rule against @@ -1215,16 +1210,14 @@ message RateLimit { // ("destination_cluster", "") // // Once a request matches against a route table rule, a routed cluster is determined by one of - // the following :ref:`route table configuration - // ` settings: + // the following :ref:`route table configuration ` + // settings: // - // * :ref:`cluster ` indicates the upstream - // cluster + // * :ref:`cluster ` indicates the upstream cluster // to route to. // * :ref:`weighted_clusters ` // chooses a cluster randomly from a set of clusters with attributed weight. - // * :ref:`cluster_header ` - // indicates which + // * :ref:`cluster_header ` indicates which // header in the request contains the target cluster. message DestinationCluster { option (udpa.annotations.versioning).previous_message_type = @@ -1363,9 +1356,9 @@ message RateLimit { // // .. attention:: // In the absence of any header match specifier, match will default to :ref:`present_match -// `. i.e, a request that has the -// :ref:`name ` header will match, regardless -// of the header's value. +// `. i.e, a request that has the :ref:`name +// ` header will match, regardless of the header's +// value. // // [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] // [#next-free-field: 12] diff --git a/envoy/config/route/v3/scoped_route.proto b/envoy/config/route/v3/scoped_route.proto index 257d87f7..fee88e86 100644 --- a/envoy/config/route/v3/scoped_route.proto +++ b/envoy/config/route/v3/scoped_route.proto @@ -15,7 +15,7 @@ option java_multiple_files = true; // Specifies a routing scope, which associates a // :ref:`Key` to a -// :ref:`envoy_api_msg_RouteConfiguration` (identified by its resource name). +// :ref:`envoy_api_msg_config.route.v3.RouteConfiguration` (identified by its resource name). // // The HTTP connection manager builds up a table consisting of these Key to // RouteConfiguration mappings, and looks up the RouteConfiguration to use per @@ -106,8 +106,8 @@ message ScopedRouteConfiguration { // The name assigned to the routing scope. string name = 1 [(validate.rules).string = {min_bytes: 1}]; - // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an - // RDS server to fetch the :ref:`envoy_api_msg_RouteConfiguration` associated + // The resource name to use for a :ref:`envoy_api_msg_service.discovery.v3.DiscoveryRequest` to an + // RDS server to fetch the :ref:`envoy_api_msg_config.route.v3.RouteConfiguration` associated // with this scope. string route_configuration_name = 2 [(validate.rules).string = {min_bytes: 1}]; diff --git a/envoy/data/cluster/v2alpha/BUILD b/envoy/data/cluster/v2alpha/BUILD index 5dc095ad..ef3541eb 100644 --- a/envoy/data/cluster/v2alpha/BUILD +++ b/envoy/data/cluster/v2alpha/BUILD @@ -4,4 +4,6 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") licenses(["notice"]) # Apache 2 -api_proto_package() +api_proto_package( + deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], +) diff --git a/envoy/data/cluster/v2alpha/outlier_detection_event.proto b/envoy/data/cluster/v2alpha/outlier_detection_event.proto index abbf57cd..cec29bcc 100644 --- a/envoy/data/cluster/v2alpha/outlier_detection_event.proto +++ b/envoy/data/cluster/v2alpha/outlier_detection_event.proto @@ -5,11 +5,13 @@ package envoy.data.cluster.v2alpha; import "google/protobuf/timestamp.proto"; import "google/protobuf/wrappers.proto"; +import "udpa/annotations/migrate.proto"; import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.data.cluster.v2alpha"; option java_outer_classname = "OutlierDetectionEventProto"; option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.data.cluster.v3"; // [#protodoc-title: Outlier detection logging events] // :ref:`Outlier detection logging `. diff --git a/envoy/data/cluster/v3/BUILD b/envoy/data/cluster/v3/BUILD new file mode 100644 index 00000000..33355e7e --- /dev/null +++ b/envoy/data/cluster/v3/BUILD @@ -0,0 +1,12 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "//envoy/data/cluster/v2alpha:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], +) diff --git a/envoy/data/cluster/v3/outlier_detection_event.proto b/envoy/data/cluster/v3/outlier_detection_event.proto new file mode 100644 index 00000000..6e9d59b0 --- /dev/null +++ b/envoy/data/cluster/v3/outlier_detection_event.proto @@ -0,0 +1,144 @@ +syntax = "proto3"; + +package envoy.data.cluster.v3; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.data.cluster.v3"; +option java_outer_classname = "OutlierDetectionEventProto"; +option java_multiple_files = true; + +// [#protodoc-title: Outlier detection logging events] +// :ref:`Outlier detection logging `. + +// Type of ejection that took place +enum OutlierEjectionType { + // In case upstream host returns certain number of consecutive 5xx. + // If + // :ref:`outlier_detection.split_external_local_origin_errors` + // is *false*, all type of errors are treated as HTTP 5xx errors. + // See :ref:`Cluster outlier detection ` documentation for + // details. + CONSECUTIVE_5XX = 0; + + // In case upstream host returns certain number of consecutive gateway errors + CONSECUTIVE_GATEWAY_FAILURE = 1; + + // Runs over aggregated success rate statistics from every host in cluster + // and selects hosts for which ratio of successful replies deviates from other hosts + // in the cluster. + // If + // :ref:`outlier_detection.split_external_local_origin_errors` + // is *false*, all errors (externally and locally generated) are used to calculate success rate + // statistics. See :ref:`Cluster outlier detection ` + // documentation for details. + SUCCESS_RATE = 2; + + // Consecutive local origin failures: Connection failures, resets, timeouts, etc + // This type of ejection happens only when + // :ref:`outlier_detection.split_external_local_origin_errors` + // is set to *true*. + // See :ref:`Cluster outlier detection ` documentation for + CONSECUTIVE_LOCAL_ORIGIN_FAILURE = 3; + + // Runs over aggregated success rate statistics for local origin failures + // for all hosts in the cluster and selects hosts for which success rate deviates from other + // hosts in the cluster. This type of ejection happens only when + // :ref:`outlier_detection.split_external_local_origin_errors` + // is set to *true*. + // See :ref:`Cluster outlier detection ` documentation for + SUCCESS_RATE_LOCAL_ORIGIN = 4; + + // Runs over aggregated success rate statistics from every host in cluster and selects hosts for + // which ratio of failed replies is above configured value. + FAILURE_PERCENTAGE = 5; + + // Runs over aggregated success rate statistics for local origin failures from every host in + // cluster and selects hosts for which ratio of failed replies is above configured value. + FAILURE_PERCENTAGE_LOCAL_ORIGIN = 6; +} + +// Represents possible action applied to upstream host +enum Action { + // In case host was excluded from service + EJECT = 0; + + // In case host was brought back into service + UNEJECT = 1; +} + +// [#next-free-field: 12] +message OutlierDetectionEvent { + option (udpa.annotations.versioning).previous_message_type = + "envoy.data.cluster.v2alpha.OutlierDetectionEvent"; + + // In case of eject represents type of ejection that took place. + OutlierEjectionType type = 1 [(validate.rules).enum = {defined_only: true}]; + + // Timestamp for event. + google.protobuf.Timestamp timestamp = 2; + + // The time in seconds since the last action (either an ejection or unejection) took place. + google.protobuf.UInt64Value secs_since_last_action = 3; + + // The :ref:`cluster ` that owns the ejected host. + string cluster_name = 4 [(validate.rules).string = {min_bytes: 1}]; + + // The URL of the ejected host. E.g., ``tcp://1.2.3.4:80``. + string upstream_url = 5 [(validate.rules).string = {min_bytes: 1}]; + + // The action that took place. + Action action = 6 [(validate.rules).enum = {defined_only: true}]; + + // If ``action`` is ``eject``, specifies the number of times the host has been ejected (local to + // that Envoy and gets reset if the host gets removed from the upstream cluster for any reason and + // then re-added). + uint32 num_ejections = 7; + + // If ``action`` is ``eject``, specifies if the ejection was enforced. ``true`` means the host was + // ejected. ``false`` means the event was logged but the host was not actually ejected. + bool enforced = 8; + + oneof event { + option (validate.required) = true; + + OutlierEjectSuccessRate eject_success_rate_event = 9; + + OutlierEjectConsecutive eject_consecutive_event = 10; + + OutlierEjectFailurePercentage eject_failure_percentage_event = 11; + } +} + +message OutlierEjectSuccessRate { + option (udpa.annotations.versioning).previous_message_type = + "envoy.data.cluster.v2alpha.OutlierEjectSuccessRate"; + + // Host’s success rate at the time of the ejection event on a 0-100 range. + uint32 host_success_rate = 1 [(validate.rules).uint32 = {lte: 100}]; + + // Average success rate of the hosts in the cluster at the time of the ejection event on a 0-100 + // range. + uint32 cluster_average_success_rate = 2 [(validate.rules).uint32 = {lte: 100}]; + + // Success rate ejection threshold at the time of the ejection event. + uint32 cluster_success_rate_ejection_threshold = 3 [(validate.rules).uint32 = {lte: 100}]; +} + +message OutlierEjectConsecutive { + option (udpa.annotations.versioning).previous_message_type = + "envoy.data.cluster.v2alpha.OutlierEjectConsecutive"; +} + +message OutlierEjectFailurePercentage { + option (udpa.annotations.versioning).previous_message_type = + "envoy.data.cluster.v2alpha.OutlierEjectFailurePercentage"; + + // Host's success rate at the time of the ejection event on a 0-100 range. + uint32 host_success_rate = 1 [(validate.rules).uint32 = {lte: 100}]; +} diff --git a/envoy/data/core/v3/health_check_event.proto b/envoy/data/core/v3/health_check_event.proto index 6de8c692..7ad27887 100644 --- a/envoy/data/core/v3/health_check_event.proto +++ b/envoy/data/core/v3/health_check_event.proto @@ -77,9 +77,8 @@ message HealthCheckAddHealthy { "envoy.data.core.v2alpha.HealthCheckAddHealthy"; // Whether this addition is the result of the first ever health check on a host, in which case - // the configured :ref:`healthy threshold - // ` is bypassed and the host is - // immediately added. + // the configured :ref:`healthy threshold ` + // is bypassed and the host is immediately added. bool first_check = 1; } diff --git a/envoy/extensions/filters/http/csrf/v3/csrf.proto b/envoy/extensions/filters/http/csrf/v3/csrf.proto index 988ed1bd..7748abf8 100644 --- a/envoy/extensions/filters/http/csrf/v3/csrf.proto +++ b/envoy/extensions/filters/http/csrf/v3/csrf.proto @@ -24,7 +24,7 @@ message CsrfPolicy { // Specifies the % of requests for which the CSRF filter is enabled. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests to filter. // // .. note:: @@ -38,7 +38,7 @@ message CsrfPolicy { // // This is intended to be used when ``filter_enabled`` is off and will be ignored otherwise. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate // and track the request's *Origin* and *Destination* to determine if it's valid, but will not // enforce any policies. diff --git a/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto b/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto index bb9a8583..35e8a608 100644 --- a/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto +++ b/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto @@ -40,9 +40,9 @@ message PerRouteConfig { // // 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. + // :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. string host_rewrite_literal = 1; // Indicates that before DNS lookup, the host header will be swapped with @@ -51,10 +51,9 @@ message PerRouteConfig { // // 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. + // :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. string host_rewrite_header = 2; } } diff --git a/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 06e3125e..f855a9e7 100644 --- a/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto @@ -90,7 +90,7 @@ message ExtAuthz { // Specifies if the filter is enabled. // - // If :ref:`runtime_key ` is specified, + // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests to filter. // // If this field is not specified, the filter will be enabled for all requests. @@ -169,8 +169,8 @@ message AuthorizationRequest { "envoy.config.filter.http.ext_authz.v2.AuthorizationRequest"; // Authorization request will include the client request headers that have a correspondent match - // in the :ref:`list `. Note that in addition to - // the user's supplied matchers: + // in the :ref:`list `. Note that in addition to the + // user's supplied matchers: // // 1. *Host*, *Method*, *Path* and *Content-Length* are automatically included to the list. // diff --git a/envoy/extensions/filters/network/http_connection_manager/v3/BUILD b/envoy/extensions/filters/network/http_connection_manager/v3/BUILD index 249b1c74..7a860896 100644 --- a/envoy/extensions/filters/network/http_connection_manager/v3/BUILD +++ b/envoy/extensions/filters/network/http_connection_manager/v3/BUILD @@ -11,7 +11,7 @@ api_proto_package( "//envoy/config/core/v3:pkg", "//envoy/config/filter/network/http_connection_manager/v2:pkg", "//envoy/config/route/v3:pkg", - "//envoy/type/tracing/v2:pkg", + "//envoy/type/tracing/v3:pkg", "//envoy/type/v3:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], diff --git a/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index af3925c4..7515a89b 100644 --- a/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -7,7 +7,7 @@ import "envoy/config/core/v3/config_source.proto"; import "envoy/config/core/v3/protocol.proto"; import "envoy/config/route/v3/route.proto"; import "envoy/config/route/v3/scoped_route.proto"; -import "envoy/type/tracing/v2/custom_tag.proto"; +import "envoy/type/tracing/v3/custom_tag.proto"; import "envoy/type/v3/percent.proto"; import "google/protobuf/any.proto"; @@ -143,7 +143,7 @@ message HttpConnectionManager { google.protobuf.UInt32Value max_path_tag_length = 7; // A list of custom tags with unique tag name to create tags for the active span. - repeated type.tracing.v2.CustomTag custom_tags = 8; + repeated type.tracing.v3.CustomTag custom_tags = 8; } message InternalAddressConfig { @@ -506,16 +506,14 @@ message ScopedRoutes { "envoy.config.filter.network.http_connection_manager.v2.ScopedRoutes"; // Specifies the mechanism for constructing "scope keys" based on HTTP request attributes. These - // keys are matched against a set of - // :ref:`Key` objects assembled from - // :ref:`ScopedRouteConfiguration` + // keys are matched against a set of :ref:`Key` + // objects assembled from :ref:`ScopedRouteConfiguration` // messages distributed via SRDS (the Scoped Route Discovery Service) or assigned statically via // :ref:`scoped_route_configurations_list`. // // Upon receiving a request's headers, the Router will build a key using the algorithm specified // by this message. This key will be used to look up the routing table (i.e., the - // :ref:`RouteConfiguration`) to use for the - // request. + // :ref:`RouteConfiguration`) to use for the request. message ScopeKeyBuilder { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.ScopedRoutes.ScopeKeyBuilder"; diff --git a/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto b/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto index 9b2d30c3..4b1b97de 100644 --- a/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto +++ b/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto @@ -236,7 +236,7 @@ message RedisProxy { } // RedisProtocolOptions specifies Redis upstream protocol options. This object is used in -// :ref:`extension_protocol_options`, +// :ref:`typed_extension_protocol_options`, // keyed by the name `envoy.redis_proxy`. message RedisProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto b/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto index eefcbfae..5707a8ed 100644 --- a/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto +++ b/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto @@ -50,8 +50,8 @@ message TcpProxy { // in the upstream cluster with metadata matching what is set in this field will be considered // for load balancing. Note that this will be merged with what's provided in // :ref:`TcpProxy.metadata_match - // `, with - // values here taking precedence. The filter name should be specified as *envoy.lb*. + // `, with values + // here taking precedence. The filter name should be specified as *envoy.lb*. config.core.v3.Metadata metadata_match = 3; } diff --git a/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto b/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto index 8b4d93ba..13015666 100644 --- a/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto +++ b/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto @@ -28,7 +28,7 @@ message RateLimit { // Specifies the rate limit configuration stage. Each configured rate limit filter performs a // rate limit check using descriptors configured in the - // :ref:`envoy_api_msg_config.filter.network.thrift_proxy.v2alpha1.RouteAction` for the request. + // :ref:`envoy_api_msg_extensions.filters.network.thrift_proxy.v3.RouteAction` for the request. // Only those entries with a matching stage number are used for a given filter. If not set, the // default stage number is 0. // diff --git a/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto b/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto index 7224637d..5308b0d5 100644 --- a/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto +++ b/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto @@ -109,7 +109,7 @@ message ThriftFilter { // ThriftProtocolOptions specifies Thrift upstream protocol options. This object is used in // in -// :ref:`extension_protocol_options`, +// :ref:`typed_extension_protocol_options`, // keyed by the name `envoy.filters.network.thrift_proxy`. message ThriftProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/envoy/extensions/transport_sockets/tls/v3/cert.proto b/envoy/extensions/transport_sockets/tls/v3/cert.proto index eaa29e59..e9fa044f 100644 --- a/envoy/extensions/transport_sockets/tls/v3/cert.proto +++ b/envoy/extensions/transport_sockets/tls/v3/cert.proto @@ -140,12 +140,12 @@ message TlsCertificate { config.core.v3.DataSource private_key = 2 [(udpa.annotations.sensitive) = true]; // BoringSSL private key method provider. This is an alternative to :ref:`private_key - // ` field. This - // can't be marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key + // ` field. This can't be + // marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key // ` and // :ref:`private_key_provider - // ` - // fields will result in an error. + // ` fields will result in an + // error. PrivateKeyProvider private_key_provider = 6; // The password to decrypt the TLS private key. If this field is not set, it is assumed that the @@ -168,8 +168,7 @@ message TlsSessionTicketKeys { // All keys are candidates for decrypting received tickets. This allows for easy rotation of keys // by, for example, putting the new key first, and the previous key second. // - // If :ref:`session_ticket_keys - // ` + // If :ref:`session_ticket_keys ` // is not specified, the TLS library will still support resuming sessions via tickets, but it will // use an internally-generated and managed key, so sessions cannot be resumed across hot restarts // or on different hosts. @@ -209,10 +208,10 @@ message CertificateValidationContext { // :ref:`verify_certificate_spki // `, // :ref:`verify_certificate_hash - // `, - // or :ref:`verify_subject_alt_name - // `) - // is also specified. + // `, or + // :ref:`match_subject_alt_names + // `) is also + // specified. // // It can optionally contain certificate revocation lists, in which case Envoy will verify // that the presented peer certificate has not been revoked by one of the included CRLs. @@ -240,11 +239,10 @@ message CertificateValidationContext { // // When both: // :ref:`verify_certificate_hash - // ` - // and :ref:`verify_certificate_spki - // ` - // are specified, a hash matching value from either of the lists will result in the certificate - // being accepted. + // ` and + // :ref:`verify_certificate_spki + // ` are specified, + // a hash matching value from either of the lists will result in the certificate being accepted. // // .. attention:: // @@ -277,11 +275,10 @@ message CertificateValidationContext { // // When both: // :ref:`verify_certificate_hash - // ` - // and :ref:`verify_certificate_spki - // ` - // are specified, a hash matching value from either of the lists will result in the certificate - // being accepted. + // ` and + // :ref:`verify_certificate_spki + // ` are specified, + // a hash matching value from either of the lists will result in the certificate being accepted. repeated string verify_certificate_hash = 2 [(validate.rules).repeated = {items {string {min_bytes: 64 max_bytes: 95}}}]; @@ -386,8 +383,8 @@ message UpstreamTlsContext { // .. attention:: // // Server certificate verification is not enabled by default. Configure - // :ref:`trusted_ca` - // to enable verification. + // :ref:`trusted_ca` to enable + // verification. CommonTlsContext common_tls_context = 1; // SNI string to use when creating TLS backend connections. diff --git a/envoy/service/discovery/v3/discovery.proto b/envoy/service/discovery/v3/discovery.proto index 1c29b82d..02997a51 100644 --- a/envoy/service/discovery/v3/discovery.proto +++ b/envoy/service/discovery/v3/discovery.proto @@ -54,11 +54,10 @@ message DiscoveryRequest { // delta, where it is populated only for new explicit ACKs). string response_nonce = 5; - // This is populated when the previous :ref:`DiscoveryResponse - // ` failed to update configuration. The - // *message* field in *error_details* provides the Envoy internal exception related to the - // failure. It is only intended for consumption during manual debugging, the string provided is - // not guaranteed to be stable across Envoy versions. + // This is populated when the previous :ref:`DiscoveryResponse ` + // failed to update configuration. The *message* field in *error_details* provides the Envoy + // internal exception related to the failure. It is only intended for consumption during manual + // debugging, the string provided is not guaranteed to be stable across Envoy versions. google.rpc.Status error_detail = 6; } @@ -192,10 +191,9 @@ message DeltaDiscoveryRequest { // Otherwise (unlike in DiscoveryRequest) response_nonce must be omitted. string response_nonce = 6; - // This is populated when the previous :ref:`DiscoveryResponse - // ` failed to update configuration. The - // *message* field in *error_details* provides the Envoy internal exception related to the - // failure. + // This is populated when the previous :ref:`DiscoveryResponse ` + // failed to update configuration. The *message* field in *error_details* + // provides the Envoy internal exception related to the failure. google.rpc.Status error_detail = 7; } diff --git a/envoy/service/route/v3/rds.proto b/envoy/service/route/v3/rds.proto index 3ab92481..3514ebd2 100644 --- a/envoy/service/route/v3/rds.proto +++ b/envoy/service/route/v3/rds.proto @@ -44,13 +44,12 @@ service RouteDiscoveryService { // Virtual Host Discovery Service (VHDS) is used to dynamically update the list of virtual hosts for // a given RouteConfiguration. If VHDS is configured a virtual host list update will be triggered // during the processing of an HTTP request if a route for the request cannot be resolved. The -// :ref:`resource_names_subscribe -// ` field -// contains a list of virtual host names or aliases to track. The contents of an alias would be the -// contents of a *host* or *authority* header used to make an http request. An xDS server will match -// an alias to a virtual host based on the content of :ref:`domains' -// ` field. The *resource_names_unsubscribe* -// field contains a list of virtual host names that have been :ref:`unsubscribed +// :ref:`resource_names_subscribe ` +// field contains a list of virtual host names or aliases to track. The contents of an alias would +// be the contents of a *host* or *authority* header used to make an http request. An xDS server +// will match an alias to a virtual host based on the content of :ref:`domains' +// ` field. The *resource_names_unsubscribe* field +// contains a list of virtual host names that have been :ref:`unsubscribed // ` from the routing table associated with the RouteConfiguration. service VirtualHostDiscoveryService { option (envoy.annotations.resource).type = "envoy.config.route.v3.VirtualHost"; diff --git a/envoy/type/matcher/v3/metadata.proto b/envoy/type/matcher/v3/metadata.proto index de43319e..586c2ea8 100644 --- a/envoy/type/matcher/v3/metadata.proto +++ b/envoy/type/matcher/v3/metadata.proto @@ -15,8 +15,8 @@ option java_multiple_files = true; // [#protodoc-title: MetadataMatcher] // 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. +// :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: // diff --git a/envoy/type/metadata/v2/BUILD b/envoy/type/metadata/v2/BUILD index 5dc095ad..ef3541eb 100644 --- a/envoy/type/metadata/v2/BUILD +++ b/envoy/type/metadata/v2/BUILD @@ -4,4 +4,6 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") licenses(["notice"]) # Apache 2 -api_proto_package() +api_proto_package( + deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], +) diff --git a/envoy/type/metadata/v2/metadata.proto b/envoy/type/metadata/v2/metadata.proto index 401b9748..67653519 100644 --- a/envoy/type/metadata/v2/metadata.proto +++ b/envoy/type/metadata/v2/metadata.proto @@ -2,11 +2,13 @@ syntax = "proto3"; package envoy.type.metadata.v2; +import "udpa/annotations/migrate.proto"; import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.type.metadata.v2"; option java_outer_classname = "MetadataProto"; option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.type.metadata.v3"; // [#protodoc-title: Metadata] diff --git a/envoy/type/metadata/v3/BUILD b/envoy/type/metadata/v3/BUILD new file mode 100644 index 00000000..34e1b604 --- /dev/null +++ b/envoy/type/metadata/v3/BUILD @@ -0,0 +1,12 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "//envoy/type/metadata/v2:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], +) diff --git a/envoy/type/metadata/v3/metadata.proto b/envoy/type/metadata/v3/metadata.proto new file mode 100644 index 00000000..f8a98d0b --- /dev/null +++ b/envoy/type/metadata/v3/metadata.proto @@ -0,0 +1,113 @@ +syntax = "proto3"; + +package envoy.type.metadata.v3; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.type.metadata.v3"; +option java_outer_classname = "MetadataProto"; +option java_multiple_files = true; + +// [#protodoc-title: Metadata] + +// MetadataKey provides a general interface using `key` and `path` to retrieve value from +// :ref:`Metadata `. +// +// For example, for the following Metadata: +// +// .. code-block:: yaml +// +// filter_metadata: +// envoy.xxx: +// prop: +// foo: bar +// xyz: +// hello: envoy +// +// The following MetadataKey will retrieve a string value "bar" from the Metadata. +// +// .. code-block:: yaml +// +// key: envoy.xxx +// path: +// - key: prop +// - key: foo +// +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. + message PathSegment { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKey.PathSegment"; + + oneof segment { + option (validate.required) = true; + + // If specified, use the key to retrieve the value in a Struct. + string key = 1 [(validate.rules).string = {min_bytes: 1}]; + } + } + + // The key name of Metadata to retrieve the Struct from the metadata. + // Typically, it represents a builtin subsystem or custom extension. + string key = 1 [(validate.rules).string = {min_bytes: 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. + // + // 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. + repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}]; +} + +// Describes what kind of metadata. +message MetadataKind { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKind"; + + // Represents dynamic metadata associated with the request. + message Request { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKind.Request"; + } + + // Represents metadata from :ref:`the route`. + message Route { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKind.Route"; + } + + // Represents metadata from :ref:`the upstream cluster`. + message Cluster { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKind.Cluster"; + } + + // Represents metadata from :ref:`the upstream + // host`. + message Host { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.metadata.v2.MetadataKind.Host"; + } + + oneof kind { + option (validate.required) = true; + + // Request kind of metadata. + Request request = 1; + + // Route kind of metadata. + Route route = 2; + + // Cluster kind of metadata. + Cluster cluster = 3; + + // Host kind of metadata. + Host host = 4; + } +} diff --git a/envoy/type/tracing/v3/BUILD b/envoy/type/tracing/v3/BUILD new file mode 100644 index 00000000..fe55e042 --- /dev/null +++ b/envoy/type/tracing/v3/BUILD @@ -0,0 +1,13 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "//envoy/type/metadata/v3:pkg", + "//envoy/type/tracing/v2:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], +) diff --git a/envoy/type/tracing/v3/custom_tag.proto b/envoy/type/tracing/v3/custom_tag.proto new file mode 100644 index 00000000..a1e0bdb9 --- /dev/null +++ b/envoy/type/tracing/v3/custom_tag.proto @@ -0,0 +1,99 @@ +syntax = "proto3"; + +package envoy.type.tracing.v3; + +import "envoy/type/metadata/v3/metadata.proto"; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.type.tracing.v3"; +option java_outer_classname = "CustomTagProto"; +option java_multiple_files = true; + +// [#protodoc-title: Custom Tag] + +// Describes custom tags for the active span. +// [#next-free-field: 6] +message CustomTag { + option (udpa.annotations.versioning).previous_message_type = "envoy.type.tracing.v2.CustomTag"; + + // Literal type custom tag with static value for the tag value. + message Literal { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.tracing.v2.CustomTag.Literal"; + + // Static literal value to populate the tag value. + string value = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + // Environment type custom tag with environment name and default value. + message Environment { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.tracing.v2.CustomTag.Environment"; + + // Environment variable name to obtain the value to populate the tag value. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // When the environment variable is not found, + // the tag value will be populated with this default value if specified, + // otherwise no tag will be populated. + string default_value = 2; + } + + // Header type custom tag with header name and default value. + message Header { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.tracing.v2.CustomTag.Header"; + + // Header name to obtain the value to populate the tag value. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // When the header does not exist, + // the tag value will be populated with this default value if specified, + // otherwise no tag will be populated. + string default_value = 2; + } + + // Metadata type custom tag using + // :ref:`MetadataKey ` to retrieve the protobuf value + // from :ref:`Metadata `, and populate the tag value with + // `the canonical JSON `_ + // representation of it. + message Metadata { + option (udpa.annotations.versioning).previous_message_type = + "envoy.type.tracing.v2.CustomTag.Metadata"; + + // Specify what kind of metadata to obtain tag value from. + metadata.v3.MetadataKind kind = 1; + + // Metadata key to define the path to retrieve the tag value. + metadata.v3.MetadataKey metadata_key = 2; + + // When no valid metadata is found, + // the tag value would be populated with this default value if specified, + // otherwise no tag would be populated. + string default_value = 3; + } + + // Used to populate the tag name. + string tag = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Used to specify what kind of custom tag. + oneof type { + option (validate.required) = true; + + // A literal custom tag. + Literal literal = 2; + + // An environment custom tag. + Environment environment = 3; + + // A request header custom tag. + Header request_header = 4; + + // A custom tag to obtain tag value from the metadata. + Metadata metadata = 5; + } +} diff --git a/xds_protocol.rst b/xds_protocol.rst index bbf1f5b3..6b580ad3 100644 --- a/xds_protocol.rst +++ b/xds_protocol.rst @@ -14,6 +14,41 @@ proto payload. Resources are delivered in a proto payload in all methods. We discuss each type of subscription below. +Resource Types +-------------- + +Every configuration resource in the xDS API has a type associated with it. Resource types follow a +:repo:`versioning scheme `. Resource types are versioned independent of the +transports described below. + +The following v2 xDS resource types are supported: + +- :ref:`envoy.api.v2.Listener ` +- :ref:`envoy.api.v2.RouteConfiguration ` +- :ref:`envoy.api.v2.ScopedRouteConfiguration ` +- :ref:`envoy.api.v2.route.VirtualHost ` +- :ref:`envoy.api.v2.Cluster ` +- :ref:`envoy.api.v2.ClusterLoadAssignment ` +- :ref:`envoy.api.v2.Auth.Secret ` +- :ref:`envoy.service.discovery.v2.Runtime ` + +The following v3 xdS resource types are supported: + +- :ref:`envoy.config.listener.v3.Listener ` +- :ref:`envoy.config.route.v3.RouteConfiguration ` +- :ref:`envoy.config.route.v3.ScopedRouteConfiguration ` +- :ref:`envoy.config.route.v3.VirtualHost ` +- :ref:`envoy.config.cluster.v3.Cluster ` +- :ref:`envoy.config.endpoint.v3.ClusterLoadAssignment ` +- :ref:`envoy.extensions.transport_sockets.tls.v3.Secret ` +- :ref:`envoy.service.runtime.v3.Runtime ` + +The concept of `type URLs `_ +appears below, and takes the form `type.googleapis.com/` -- e.g., +`type.googleapis.com/envoy.api.v2.Cluster` for a `Cluster` resource. In various requests from +Envoy and responses by the management server, the resource type URL is stated. + + Filesystem subscriptions ------------------------ @@ -36,26 +71,6 @@ occurs. Streaming gRPC subscriptions ---------------------------- -Resource Types -~~~~~~~~~~~~~~ - -Every configuration resource in the xDS API has a type associated with it. The following types are -supported: - -- :ref:`envoy.api.v2.Listener ` -- :ref:`envoy.api.v2.RouteConfiguration ` -- :ref:`envoy.api.v2.ScopedRouteConfiguration ` -- :ref:`envoy.api.v2.route.VirtualHost ` -- :ref:`envoy.api.v2.Cluster ` -- :ref:`envoy.api.v2.ClusterLoadAssignment ` -- :ref:`envoy.api.v2.Auth.Secret ` -- :ref:`envoy.service.discovery.v2.Runtime ` - -The concept of `type URLs `_ -appears below, and takes the form `type.googleapis.com/` -- e.g., -`type.googleapis.com/envoy.api.v2.Cluster` for a `Cluster` resource. In various requests from -Envoy and responses by the management server, the resource type URL is stated. - API flow ~~~~~~~~ @@ -202,16 +217,30 @@ the ADS server, which will be used for all resources. The :ref:`ConfigSource :ref:`Cluster ` resources must contain :ref:`AggregatedConfigSource ` messages. -The xDS Protocol -~~~~~~~~~~~~~~~~ +The xDS transport Protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~ -ACK/NACK and versioning -^^^^^^^^^^^^^^^^^^^^^^^ +Transport API version +^^^^^^^^^^^^^^^^^^^^^ + +In addition the resource type version described above, the xDS wire protocol has a +transport version associated with it. This provides type versioning for messages such as +:ref:`DiscoveryRequest ` and :ref:`DiscoveryResponse +`. + +ACK/NACK and resource instance versioning +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Each xDS stream begins with a :ref:`DiscoveryRequest ` from the client, specifying the list of resources to subscribe to, the type URL corresponding to the subscribed resources, the node identifier and an empty :ref:`version_info `. + +In addition to resource and transport type versioning schemes above, which operate at the type +level, Envoy has a resource instance version. Unlike the resource/transport types, this is not a +property of the API but is instead a reflection of the specific revision of a named resource +delivered over xDS. + An example EDS request might be: .. code:: yaml