diff --git a/.clang-format b/.clang-format index fb8719b446829..c2a2c20912529 100755 --- a/.clang-format +++ b/.clang-format @@ -12,4 +12,5 @@ Language: Proto ColumnLimit: 100 SpacesInContainerLiterals: false AllowShortFunctionsOnASingleLine: false +ReflowComments: false ... diff --git a/BUILD b/BUILD index bd487a868c0f0..4dc2cadee42d0 100644 --- a/BUILD +++ b/BUILD @@ -1,3 +1,6 @@ licenses(["notice"]) # Apache 2 -exports_files(["VERSION"]) +exports_files([ + "VERSION", + ".clang-format", +]) diff --git a/api/BUILD b/api/BUILD index 8c28c87dd92d8..1a3f30831036e 100644 --- a/api/BUILD +++ b/api/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/api/envoy/admin/v3/config_dump.proto b/api/envoy/admin/v3/config_dump.proto index 506d070a5fa3f..8a527f6fd9bc5 100644 --- a/api/envoy/admin/v3/config_dump.proto +++ b/api/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/api/envoy/api/v2/auth/cert.proto b/api/envoy/api/v2/auth/cert.proto index 0daf5acace748..e2302b2621a37 100644 --- a/api/envoy/api/v2/auth/cert.proto +++ b/api/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/api/envoy/api/v2/cluster.proto b/api/envoy/api/v2/cluster.proto index 7616d1fe31d6a..2d61ef3f22b99 100644 --- a/api/envoy/api/v2/cluster.proto +++ b/api/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/api/envoy/api/v2/core/base.proto b/api/envoy/api/v2/core/base.proto index c3b99ae813088..67a97dd6e25e8 100644 --- a/api/envoy/api/v2/core/base.proto +++ b/api/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/api/envoy/api/v2/core/health_check.proto b/api/envoy/api/v2/core/health_check.proto index 806d263e29ded..91aeb76b8b425 100644 --- a/api/envoy/api/v2/core/health_check.proto +++ b/api/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/api/envoy/api/v2/route/route_components.proto b/api/envoy/api/v2/route/route_components.proto index b386ca87f1f5a..d6c18b503cd66 100644 --- a/api/envoy/api/v2/route/route_components.proto +++ b/api/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/api/envoy/config/bootstrap/v2/bootstrap.proto b/api/envoy/config/bootstrap/v2/bootstrap.proto index cc12345efbae4..f4e47afe0b514 100644 --- a/api/envoy/config/bootstrap/v2/bootstrap.proto +++ b/api/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/api/envoy/config/bootstrap/v3/bootstrap.proto b/api/envoy/config/bootstrap/v3/bootstrap.proto index f77b41e24e3a2..e7ebeb12698d4 100644 --- a/api/envoy/config/bootstrap/v3/bootstrap.proto +++ b/api/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/api/envoy/config/cluster/v3/circuit_breaker.proto b/api/envoy/config/cluster/v3/circuit_breaker.proto index 1b6c1c99e1ea4..42de29b01e5b3 100644 --- a/api/envoy/config/cluster/v3/circuit_breaker.proto +++ b/api/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/api/envoy/config/cluster/v3/cluster.proto b/api/envoy/config/cluster/v3/cluster.proto index 74f5f0baaba61..3a71f8f17a970 100644 --- a/api/envoy/config/cluster/v3/cluster.proto +++ b/api/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/api/envoy/config/core/v3/base.proto b/api/envoy/config/core/v3/base.proto index a07c8cd4609e3..85218a90e80b6 100644 --- a/api/envoy/config/core/v3/base.proto +++ b/api/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/api/envoy/config/core/v3/grpc_service.proto b/api/envoy/config/core/v3/grpc_service.proto index 06d76098f4833..0c3be24231f1a 100644 --- a/api/envoy/config/core/v3/grpc_service.proto +++ b/api/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/api/envoy/config/core/v3/health_check.proto b/api/envoy/config/core/v3/health_check.proto index a1e39dee685f0..624b7f6e5b15d 100644 --- a/api/envoy/config/core/v3/health_check.proto +++ b/api/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/api/envoy/config/filter/http/csrf/v2/csrf.proto b/api/envoy/config/filter/http/csrf/v2/csrf.proto index f1463066babf0..ce38714bf45f5 100644 --- a/api/envoy/config/filter/http/csrf/v2/csrf.proto +++ b/api/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/api/envoy/config/filter/http/ext_authz/v2/ext_authz.proto b/api/envoy/config/filter/http/ext_authz/v2/ext_authz.proto index 064040fd6c5b2..d80ca7f479610 100644 --- a/api/envoy/config/filter/http/ext_authz/v2/ext_authz.proto +++ b/api/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/api/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto b/api/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto index 3eac388c904b5..f0996392f9524 100644 --- a/api/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto +++ b/api/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/api/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto b/api/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto index 7430ec8857521..91ac5da3ef28b 100644 --- a/api/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto +++ b/api/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/api/envoy/config/listener/v3/listener.proto b/api/envoy/config/listener/v3/listener.proto index 9ea16084b2f44..bd81a9efc6f8f 100644 --- a/api/envoy/config/listener/v3/listener.proto +++ b/api/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/api/envoy/config/listener/v3/listener_components.proto b/api/envoy/config/listener/v3/listener_components.proto index 9b6f4b8b80eff..afdfb59d3aa32 100644 --- a/api/envoy/config/listener/v3/listener_components.proto +++ b/api/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/api/envoy/config/rbac/v3/rbac.proto b/api/envoy/config/rbac/v3/rbac.proto index 355b072a5598d..3320c86a885fe 100644 --- a/api/envoy/config/rbac/v3/rbac.proto +++ b/api/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/api/envoy/config/route/v3/BUILD b/api/envoy/config/route/v3/BUILD index e96fada49ddb6..019cf27528c6a 100644 --- a/api/envoy/config/route/v3/BUILD +++ b/api/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/api/envoy/config/route/v3/route.proto b/api/envoy/config/route/v3/route.proto index ef3ab0e1e2760..96faec71e73b6 100644 --- a/api/envoy/config/route/v3/route.proto +++ b/api/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/api/envoy/config/route/v3/route_components.proto b/api/envoy/config/route/v3/route_components.proto index 3f6fc1f373a3c..f28ab12d1b5d2 100644 --- a/api/envoy/config/route/v3/route_components.proto +++ b/api/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/api/envoy/config/route/v3/scoped_route.proto b/api/envoy/config/route/v3/scoped_route.proto index 257d87f7c3166..fee88e862f47b 100644 --- a/api/envoy/config/route/v3/scoped_route.proto +++ b/api/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/api/envoy/data/cluster/v2alpha/BUILD b/api/envoy/data/cluster/v2alpha/BUILD index 5dc095ade27a9..ef3541ebcb1df 100644 --- a/api/envoy/data/cluster/v2alpha/BUILD +++ b/api/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/api/envoy/data/cluster/v2alpha/outlier_detection_event.proto b/api/envoy/data/cluster/v2alpha/outlier_detection_event.proto index abbf57cd86066..cec29bccc73f1 100644 --- a/api/envoy/data/cluster/v2alpha/outlier_detection_event.proto +++ b/api/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/api/envoy/data/cluster/v3/BUILD b/api/envoy/data/cluster/v3/BUILD new file mode 100644 index 0000000000000..33355e7efa192 --- /dev/null +++ b/api/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/api/envoy/data/cluster/v3/outlier_detection_event.proto b/api/envoy/data/cluster/v3/outlier_detection_event.proto new file mode 100644 index 0000000000000..6e9d59b0e15da --- /dev/null +++ b/api/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/api/envoy/data/core/v3/health_check_event.proto b/api/envoy/data/core/v3/health_check_event.proto index 6de8c6924e698..7ad278876dcfd 100644 --- a/api/envoy/data/core/v3/health_check_event.proto +++ b/api/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/api/envoy/extensions/filters/http/csrf/v3/csrf.proto b/api/envoy/extensions/filters/http/csrf/v3/csrf.proto index 988ed1bddb3f6..7748abf88d365 100644 --- a/api/envoy/extensions/filters/http/csrf/v3/csrf.proto +++ b/api/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/api/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto b/api/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto index bb9a85833fa1c..35e8a608d4738 100644 --- a/api/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto +++ b/api/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/api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 06e3125e98c06..f855a9e7567e5 100644 --- a/api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/api/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/api/envoy/extensions/filters/network/http_connection_manager/v3/BUILD b/api/envoy/extensions/filters/network/http_connection_manager/v3/BUILD index 249b1c74b6e37..7a8608967e4a2 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v3/BUILD +++ b/api/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/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index af3925c4e7390..7515a89b80e49 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/api/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/api/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto b/api/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto index 9b2d30c30e80f..4b1b97de46277 100644 --- a/api/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto +++ b/api/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/api/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto b/api/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto index eefcbfae1ad34..5707a8ed4dcbc 100644 --- a/api/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto +++ b/api/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/api/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto b/api/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto index 8b4d93ba1d7f8..1301566649422 100644 --- a/api/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto +++ b/api/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/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto b/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto index 7224637d34e4b..5308b0d5b4369 100644 --- a/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto +++ b/api/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/api/envoy/extensions/transport_sockets/tls/v3/cert.proto b/api/envoy/extensions/transport_sockets/tls/v3/cert.proto index eaa29e59d43be..e9fa044fa65c1 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/cert.proto +++ b/api/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/api/envoy/service/discovery/v3/discovery.proto b/api/envoy/service/discovery/v3/discovery.proto index 1c29b82dd5597..02997a51dca23 100644 --- a/api/envoy/service/discovery/v3/discovery.proto +++ b/api/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/api/envoy/service/route/v3/rds.proto b/api/envoy/service/route/v3/rds.proto index 3ab92481662f5..3514ebd2a2c73 100644 --- a/api/envoy/service/route/v3/rds.proto +++ b/api/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/api/envoy/type/matcher/v3/metadata.proto b/api/envoy/type/matcher/v3/metadata.proto index de43319e54048..586c2ea8d9422 100644 --- a/api/envoy/type/matcher/v3/metadata.proto +++ b/api/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/api/envoy/type/metadata/v2/BUILD b/api/envoy/type/metadata/v2/BUILD index 5dc095ade27a9..ef3541ebcb1df 100644 --- a/api/envoy/type/metadata/v2/BUILD +++ b/api/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/api/envoy/type/metadata/v2/metadata.proto b/api/envoy/type/metadata/v2/metadata.proto index 401b974824c90..67653519ba973 100644 --- a/api/envoy/type/metadata/v2/metadata.proto +++ b/api/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/api/envoy/type/metadata/v3/BUILD b/api/envoy/type/metadata/v3/BUILD new file mode 100644 index 0000000000000..34e1b604ce9f7 --- /dev/null +++ b/api/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/api/envoy/type/metadata/v3/metadata.proto b/api/envoy/type/metadata/v3/metadata.proto new file mode 100644 index 0000000000000..f8a98d0b58054 --- /dev/null +++ b/api/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/api/envoy/type/tracing/v3/BUILD b/api/envoy/type/tracing/v3/BUILD new file mode 100644 index 0000000000000..fe55e0428c7a4 --- /dev/null +++ b/api/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/api/envoy/type/tracing/v3/custom_tag.proto b/api/envoy/type/tracing/v3/custom_tag.proto new file mode 100644 index 0000000000000..a1e0bdb9bf2ed --- /dev/null +++ b/api/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/api/xds_protocol.rst b/api/xds_protocol.rst index bbf1f5b325173..6b580ad3d4467 100644 --- a/api/xds_protocol.rst +++ b/api/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 diff --git a/docs/build.sh b/docs/build.sh index ceb9ae7cf82d5..ccc6ac01f110d 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -64,43 +64,56 @@ export EXTENSION_DB_PATH="$(realpath "${BUILD_DIR}/extension_db.json")" mkdir -p "${GENERATED_RST_DIR}"/intro/arch_overview/security ./docs/generate_extension_rst.py "${EXTENSION_DB_PATH}" "${GENERATED_RST_DIR}"/intro/arch_overview/security -# Generate the extensions docs -bazel build ${BAZEL_BUILD_OPTIONS} @envoy_api_canonical//docs:protos --aspects \ - tools/protodoc/protodoc.bzl%protodoc_aspect --output_groups=rst --action_env=CPROFILE_ENABLED=1 \ - --action_env=ENVOY_BLOB_SHA --action_env=EXTENSION_DB_PATH="${EXTENSION_DB_PATH}" --host_force_python=PY3 - -# Fill in boiler plate for extensions that have google.protobuf.Empty as their -# config. -bazel run ${BAZEL_BUILD_OPTIONS} //tools/protodoc:generate_empty -- \ - "${PWD}"/docs/empty_extensions.json "${PWD}/${GENERATED_RST_DIR}"/api-v2/config - -# We do ** matching below to deal with Bazel cache blah (source proto artifacts -# are nested inside source package targets). -shopt -s globstar - -# Find all source protos. -declare -r PROTO_TARGET=$(bazel query "labels(srcs, labels(deps, @envoy_api_canonical//docs:protos))") - -# Only copy in the protos we care about and know how to deal with in protodoc. -for p in ${PROTO_TARGET} -do - declare PROTO_FILE_WITHOUT_PREFIX="${p#@envoy_api_canonical//}" - declare PROTO_FILE_CANONICAL="${PROTO_FILE_WITHOUT_PREFIX/://}" - # We use ** glob matching here to deal with the fact that we have something - # like - # bazel-bin/external/envoy_api_canonical/envoy/admin/v2alpha/pkg/envoy/admin/v2alpha/certs.proto.proto - # and we don't want to have to do a nested loop and slow bazel query to - # recover the canonical package part of the path. - declare SRCS=(bazel-bin/external/envoy_api_canonical/**/"${PROTO_FILE_CANONICAL}.rst") - # While we may have reformatted the file multiple times due to the transitive - # dependencies in the aspect above, they all look the same. So, just pick an - # arbitrary match and we're done. - declare SRC="${SRCS[0]}" - declare DST="${GENERATED_RST_DIR}/api-v2/${PROTO_FILE_CANONICAL#envoy/}".rst - - mkdir -p "$(dirname "${DST}")" - cp -f "${SRC}" "$(dirname "${DST}")" -done +function generate_api_rst() { + declare -r API_VERSION=$1 + echo "Generating ${API_VERSION} API RST..." + + # Generate the extensions docs + bazel build ${BAZEL_BUILD_OPTIONS} @envoy_api_canonical//:"${API_VERSION}"_protos --aspects \ + tools/protodoc/protodoc.bzl%protodoc_aspect --output_groups=rst --action_env=CPROFILE_ENABLED=1 \ + --action_env=ENVOY_BLOB_SHA --action_env=EXTENSION_DB_PATH="${EXTENSION_DB_PATH}" --host_force_python=PY3 + + # Fill in boiler plate for extensions that have google.protobuf.Empty as their + # config. + bazel run ${BAZEL_BUILD_OPTIONS} //tools/protodoc:generate_empty -- \ + "${PWD}"/docs/empty_extensions.json "${PWD}/${GENERATED_RST_DIR}"/api-"${API_VERSION}"/config + + # We do ** matching below to deal with Bazel cache blah (source proto artifacts + # are nested inside source package targets). + shopt -s globstar + + # Find all source protos. + declare -r PROTO_TARGET=$(bazel query "labels(srcs, labels(deps, @envoy_api_canonical//:${API_VERSION}_protos))") + + # Only copy in the protos we care about and know how to deal with in protodoc. + for p in ${PROTO_TARGET} + do + declare PROTO_FILE_WITHOUT_PREFIX="${p#@envoy_api_canonical//}" + declare PROTO_FILE_CANONICAL="${PROTO_FILE_WITHOUT_PREFIX/://}" + # We use ** glob matching here to deal with the fact that we have something + # like + # bazel-bin/external/envoy_api_canonical/envoy/admin/v2alpha/pkg/envoy/admin/v2alpha/certs.proto.proto + # and we don't want to have to do a nested loop and slow bazel query to + # recover the canonical package part of the path. + declare SRCS=(bazel-bin/external/envoy_api_canonical/**/"${PROTO_FILE_CANONICAL}.rst") + # While we may have reformatted the file multiple times due to the transitive + # dependencies in the aspect above, they all look the same. So, just pick an + # arbitrary match and we're done. + declare SRC="${SRCS[0]}" + declare DST="${GENERATED_RST_DIR}/api-${API_VERSION}/${PROTO_FILE_CANONICAL#envoy/}".rst + + mkdir -p "$(dirname "${DST}")" + cp -f "${SRC}" "$(dirname "${DST}")" + done +} + +generate_api_rst v2 +generate_api_rst v3 + +# Fixup anchors and references in v3 so they form a distinct namespace. +# TODO(htuch): Do this in protodoc generation in the future. +find "${GENERATED_RST_DIR}"/api-v3 -name "*.rst" -print0 | xargs -0 sed -i "s#envoy_api_#envoy_v3_api_#g" +find "${GENERATED_RST_DIR}"/api-v3 -name "*.rst" -print0 | xargs -0 sed -i "s#config_resource_monitors#v3_config_resource_monitors#g" mkdir -p ${GENERATED_RST_DIR}/api-docs diff --git a/docs/root/api-v3/admin/admin.rst b/docs/root/api-v3/admin/admin.rst new file mode 100644 index 0000000000000..79e784a530719 --- /dev/null +++ b/docs/root/api-v3/admin/admin.rst @@ -0,0 +1,8 @@ +Admin +======== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../admin/v3/* diff --git a/docs/root/api-v3/api.rst b/docs/root/api-v3/api.rst new file mode 100644 index 0000000000000..7dcb72a8ec829 --- /dev/null +++ b/docs/root/api-v3/api.rst @@ -0,0 +1,19 @@ +.. _envoy_v3_api_reference: + +v3 API reference +================ + +.. toctree:: + :glob: + :maxdepth: 2 + + bootstrap/bootstrap + listeners/listeners + clusters/clusters + http_routes/http_routes + config/config + admin/admin + data/data + service/service + common_messages/common_messages + types/types diff --git a/docs/root/api-v3/bootstrap/bootstrap.rst b/docs/root/api-v3/bootstrap/bootstrap.rst new file mode 100644 index 0000000000000..bbaf343a20abb --- /dev/null +++ b/docs/root/api-v3/bootstrap/bootstrap.rst @@ -0,0 +1,13 @@ +Bootstrap +========= + +.. toctree:: + :glob: + :maxdepth: 2 + + ../config/bootstrap/v3/bootstrap.proto + ../config/metrics/v3/stats.proto + ../config/metrics/v3/metrics_service.proto + ../config/overload/v3/overload.proto + ../config/ratelimit/v3/rls.proto + tracing/tracing.rst diff --git a/docs/root/api-v3/bootstrap/tracing/tracing.rst b/docs/root/api-v3/bootstrap/tracing/tracing.rst new file mode 100644 index 0000000000000..abc9e78169f7b --- /dev/null +++ b/docs/root/api-v3/bootstrap/tracing/tracing.rst @@ -0,0 +1,9 @@ +Tracing +======= + +.. toctree:: + :glob: + :maxdepth: 2 + + ../../config/trace/v3/trace.proto + ../../config/trace/v3/xray.proto diff --git a/docs/root/api-v3/clusters/clusters.rst b/docs/root/api-v3/clusters/clusters.rst new file mode 100644 index 0000000000000..9ebd9db910d2d --- /dev/null +++ b/docs/root/api-v3/clusters/clusters.rst @@ -0,0 +1,14 @@ +Clusters +======== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../config/cluster/v3/cluster.proto + ../config/cluster/v3/outlier_detection.proto + ../config/cluster/v3/circuit_breaker.proto + ../config/cluster/v3/filter.proto + ../config/endpoint/v3/endpoint.proto + ../config/endpoint/v3/endpoint_components.proto + ../config/core/v3/health_check.proto diff --git a/docs/root/api-v3/common_messages/common_messages.rst b/docs/root/api-v3/common_messages/common_messages.rst new file mode 100644 index 0000000000000..52d008e892c17 --- /dev/null +++ b/docs/root/api-v3/common_messages/common_messages.rst @@ -0,0 +1,16 @@ +Common messages +=============== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../config/core/v3/base.proto + ../config/core/v3/address.proto + ../config/core/v3/protocol.proto + ../service/discovery/v3/discovery.proto + ../config/core/v3/config_source.proto + ../config/core/v3/grpc_service.proto + ../config/core/v3/http_uri.proto + ../extensions/common/ratelimit/v3/ratelimit.proto + ../extensions/filters/common/fault/v3/fault.proto diff --git a/docs/root/api-v3/config/accesslog/accesslog.rst b/docs/root/api-v3/config/accesslog/accesslog.rst new file mode 100644 index 0000000000000..e6839c5059c83 --- /dev/null +++ b/docs/root/api-v3/config/accesslog/accesslog.rst @@ -0,0 +1,9 @@ +Access loggers +============== + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* + ../../extensions/access_loggers/*/v3/* diff --git a/docs/root/api-v3/config/cluster/cluster.rst b/docs/root/api-v3/config/cluster/cluster.rst new file mode 100644 index 0000000000000..f31111382c6cd --- /dev/null +++ b/docs/root/api-v3/config/cluster/cluster.rst @@ -0,0 +1,8 @@ +Cluster +======= + +.. toctree:: + :glob: + :maxdepth: 2 + + ../../extensions/clusters/*/v3/* diff --git a/docs/root/api-v3/config/common/common.rst b/docs/root/api-v3/config/common/common.rst new file mode 100644 index 0000000000000..5739dffe3676e --- /dev/null +++ b/docs/root/api-v3/config/common/common.rst @@ -0,0 +1,9 @@ +Common +====== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../../extensions/common/dynamic_forward_proxy/v3/* + ../../extensions/common/tap/v3/* diff --git a/docs/root/api-v3/config/config.rst b/docs/root/api-v3/config/config.rst new file mode 100644 index 0000000000000..3725a558c7c82 --- /dev/null +++ b/docs/root/api-v3/config/config.rst @@ -0,0 +1,17 @@ +Extensions +========== + +.. toctree:: + :glob: + :maxdepth: 2 + + filter/filter + accesslog/accesslog + rbac/rbac + health_checker/health_checker + transport_socket/transport_socket + resource_monitor/resource_monitor + common/common + cluster/cluster + grpc_credential/grpc_credential + retry/retry diff --git a/docs/root/api-v3/config/filter/dubbo/dubbo.rst b/docs/root/api-v3/config/filter/dubbo/dubbo.rst new file mode 100644 index 0000000000000..a8f8f743f76c1 --- /dev/null +++ b/docs/root/api-v3/config/filter/dubbo/dubbo.rst @@ -0,0 +1,8 @@ +Dubbo filters +============== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../../../extensions/filters/network/dubbo_proxy/*/v3/* diff --git a/docs/root/api-v3/config/filter/filter.rst b/docs/root/api-v3/config/filter/filter.rst new file mode 100644 index 0000000000000..4bf4fe9f245ef --- /dev/null +++ b/docs/root/api-v3/config/filter/filter.rst @@ -0,0 +1,13 @@ +Filters +======= + +.. toctree:: + :glob: + :maxdepth: 2 + + listener/listener + network/network + udp/udp + http/http + dubbo/dubbo + thrift/thrift diff --git a/docs/root/api-v3/config/filter/http/http.rst b/docs/root/api-v3/config/filter/http/http.rst new file mode 100644 index 0000000000000..20f2c75664dbc --- /dev/null +++ b/docs/root/api-v3/config/filter/http/http.rst @@ -0,0 +1,9 @@ +HTTP filters +============ + +.. toctree:: + :glob: + :maxdepth: 2 + + */empty/* + ../../../extensions/filters/http/*/v3/* diff --git a/docs/root/api-v3/config/filter/listener/listener.rst b/docs/root/api-v3/config/filter/listener/listener.rst new file mode 100644 index 0000000000000..b326c1c5e8319 --- /dev/null +++ b/docs/root/api-v3/config/filter/listener/listener.rst @@ -0,0 +1,9 @@ +Listener filters +================ + +.. toctree:: + :glob: + :maxdepth: 2 + + */empty/* + ../../../extensions/filters/listener/*/v3/* diff --git a/docs/root/api-v3/config/filter/network/network.rst b/docs/root/api-v3/config/filter/network/network.rst new file mode 100644 index 0000000000000..4b56226331b63 --- /dev/null +++ b/docs/root/api-v3/config/filter/network/network.rst @@ -0,0 +1,9 @@ +Network filters +=============== + +.. toctree:: + :glob: + :maxdepth: 2 + + */empty/* + ../../../extensions/filters/network/*/v3/* diff --git a/docs/root/api-v3/config/filter/thrift/thrift.rst b/docs/root/api-v3/config/filter/thrift/thrift.rst new file mode 100644 index 0000000000000..7e40e6f951942 --- /dev/null +++ b/docs/root/api-v3/config/filter/thrift/thrift.rst @@ -0,0 +1,9 @@ +Thrift filters +============== + +.. toctree:: + :glob: + :maxdepth: 2 + + router/v2alpha1/* + ../../../extensions/filters/network/thrift_proxy/**/v3/* diff --git a/docs/root/api-v3/config/filter/udp/udp.rst b/docs/root/api-v3/config/filter/udp/udp.rst new file mode 100644 index 0000000000000..9728ddad14975 --- /dev/null +++ b/docs/root/api-v3/config/filter/udp/udp.rst @@ -0,0 +1,8 @@ +UDP listener filters +==================== + +.. toctree:: + :glob: + :maxdepth: 2 + + */v2alpha/* diff --git a/docs/root/api-v3/config/grpc_credential/grpc_credential.rst b/docs/root/api-v3/config/grpc_credential/grpc_credential.rst new file mode 100644 index 0000000000000..975dae87d871c --- /dev/null +++ b/docs/root/api-v3/config/grpc_credential/grpc_credential.rst @@ -0,0 +1,8 @@ +Grpc Credentials +================ + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* diff --git a/docs/root/api-v3/config/health_checker/health_checker.rst b/docs/root/api-v3/config/health_checker/health_checker.rst new file mode 100644 index 0000000000000..3e5d283725056 --- /dev/null +++ b/docs/root/api-v3/config/health_checker/health_checker.rst @@ -0,0 +1,8 @@ +Health checkers +=============== + +.. toctree:: + :glob: + :maxdepth: 2 + + */v2/* \ No newline at end of file diff --git a/docs/root/api-v3/config/rbac/rbac.rst b/docs/root/api-v3/config/rbac/rbac.rst new file mode 100644 index 0000000000000..6b3d247c0a905 --- /dev/null +++ b/docs/root/api-v3/config/rbac/rbac.rst @@ -0,0 +1,8 @@ +RBAC +==== + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* diff --git a/docs/root/api-v3/config/resource_monitor/resource_monitor.rst b/docs/root/api-v3/config/resource_monitor/resource_monitor.rst new file mode 100644 index 0000000000000..ef47ad7dca3e7 --- /dev/null +++ b/docs/root/api-v3/config/resource_monitor/resource_monitor.rst @@ -0,0 +1,10 @@ +.. _v3_config_resource_monitors: + +Resource monitors +================= + +.. toctree:: + :glob: + :maxdepth: 2 + + */v2alpha/* diff --git a/docs/root/api-v3/config/retry/retry.rst b/docs/root/api-v3/config/retry/retry.rst new file mode 100644 index 0000000000000..2ba4572ab2edc --- /dev/null +++ b/docs/root/api-v3/config/retry/retry.rst @@ -0,0 +1,10 @@ +Retry Predicates +================ + +.. toctree:: + :glob: + :maxdepth: 2 + + */empty/* + */v2/* + ../../extensions/retry/**/v3/* diff --git a/docs/root/api-v3/config/transport_socket/transport_socket.rst b/docs/root/api-v3/config/transport_socket/transport_socket.rst new file mode 100644 index 0000000000000..40ad029d84a90 --- /dev/null +++ b/docs/root/api-v3/config/transport_socket/transport_socket.rst @@ -0,0 +1,8 @@ +Transport sockets +================= + +.. toctree:: + :glob: + :maxdepth: 2 + + ../../extensions/transport_sockets/*/v3/* diff --git a/docs/root/api-v3/data/accesslog/accesslog.rst b/docs/root/api-v3/data/accesslog/accesslog.rst new file mode 100644 index 0000000000000..a047226260a60 --- /dev/null +++ b/docs/root/api-v3/data/accesslog/accesslog.rst @@ -0,0 +1,8 @@ +Access logs +=========== + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* diff --git a/docs/root/api-v3/data/cluster/cluster.rst b/docs/root/api-v3/data/cluster/cluster.rst new file mode 100644 index 0000000000000..bbffee2bafc9b --- /dev/null +++ b/docs/root/api-v3/data/cluster/cluster.rst @@ -0,0 +1,8 @@ +Cluster data +============ + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/outlier_detection_event.proto diff --git a/docs/root/api-v3/data/core/core.rst b/docs/root/api-v3/data/core/core.rst new file mode 100644 index 0000000000000..15fa7ab1ed165 --- /dev/null +++ b/docs/root/api-v3/data/core/core.rst @@ -0,0 +1,8 @@ +Core data +========= + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/health_check_event.proto diff --git a/docs/root/api-v3/data/data.rst b/docs/root/api-v3/data/data.rst new file mode 100644 index 0000000000000..0f5857448e860 --- /dev/null +++ b/docs/root/api-v3/data/data.rst @@ -0,0 +1,11 @@ +Envoy data +========== + +.. toctree:: + :glob: + :maxdepth: 2 + + accesslog/accesslog + core/core + cluster/cluster + tap/tap diff --git a/docs/root/api-v3/data/tap/tap.rst b/docs/root/api-v3/data/tap/tap.rst new file mode 100644 index 0000000000000..8302f37e02b37 --- /dev/null +++ b/docs/root/api-v3/data/tap/tap.rst @@ -0,0 +1,8 @@ +Tap +=== + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* diff --git a/docs/root/api-v3/http_routes/http_routes.rst b/docs/root/api-v3/http_routes/http_routes.rst new file mode 100644 index 0000000000000..006d4610395e1 --- /dev/null +++ b/docs/root/api-v3/http_routes/http_routes.rst @@ -0,0 +1,10 @@ +HTTP route management +===================== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../config/route/v3/route.proto + ../config/route/v3/scoped_route.proto + ../config/route/v3/route_components.proto diff --git a/docs/root/api-v3/listeners/listeners.rst b/docs/root/api-v3/listeners/listeners.rst new file mode 100644 index 0000000000000..40935163eed73 --- /dev/null +++ b/docs/root/api-v3/listeners/listeners.rst @@ -0,0 +1,12 @@ +Listeners +========= + +.. toctree:: + :glob: + :maxdepth: 2 + + ../config/listener/v3/listener.proto + ../config/listener/v3/listener_components.proto + ../config/listener/v3/api_listener.proto + ../config/listener/v3/udp_listener_config.proto + ../config/listener/v3/quic_config.proto diff --git a/docs/root/api-v3/service/service.rst b/docs/root/api-v3/service/service.rst new file mode 100644 index 0000000000000..7e07e7c387d90 --- /dev/null +++ b/docs/root/api-v3/service/service.rst @@ -0,0 +1,16 @@ +Services +======== + +.. toctree:: + :glob: + :maxdepth: 2 + + accesslog/v3/* + auth/v3/* + health/v3/* + metrics/v3/* + ratelimit/v3/* + runtime/v3/* + tap/v3/* + ../config/tap/v3/* + trace/v3/* diff --git a/docs/root/api-v3/types/types.rst b/docs/root/api-v3/types/types.rst new file mode 100644 index 0000000000000..58e8d9dade0d9 --- /dev/null +++ b/docs/root/api-v3/types/types.rst @@ -0,0 +1,21 @@ +Types +===== + +.. toctree:: + :glob: + :maxdepth: 2 + + ../type/v3/hash_policy.proto + ../type/v3/http.proto + ../type/v3/http_status.proto + ../type/v3/percent.proto + ../type/v3/range.proto + ../type/v3/semantic_version.proto + ../type/v3/token_bucket.proto + ../type/matcher/v3/metadata.proto + ../type/matcher/v3/number.proto + ../type/matcher/v3/regex.proto + ../type/matcher/v3/string.proto + ../type/matcher/v3/value.proto + ../type/metadata/v3/metadata.proto + ../type/tracing/v3/custom_tag.proto diff --git a/docs/root/api/api.rst b/docs/root/api/api.rst index 086a481e484da..4224d9626ae07 100644 --- a/docs/root/api/api.rst +++ b/docs/root/api/api.rst @@ -7,6 +7,8 @@ API :glob: :maxdepth: 2 + api_supported_versions ../api-v2/api + ../api-v3/api ../api-docs/xds_protocol client_features diff --git a/docs/root/api/api_supported_versions.rst b/docs/root/api/api_supported_versions.rst new file mode 100644 index 0000000000000..92d4bf97d210d --- /dev/null +++ b/docs/root/api/api_supported_versions.rst @@ -0,0 +1,17 @@ +.. _api_supported_versions: + +Suported API versions +===================== + +Envoy's APIs follow a :repo:`versioning scheme ` in which Envoy supports +multiple major API versions at any point in time. The following versions are currently supported: + +* v2 xDS API (*deprecated*, end-of-life EOY 2020). This API will not accept new features after the + end of Q1 2020. +* v3 xDS API (*active*, end-of-life EOY 2021). Envoy developers and operators are encouraged to be + actively adopting and working with v3 xDS. + +The following API versions are no longer supported by Envoy: + +* v1 xDS API. This was the legacy REST-JSON API that preceded the current Protobuf and dual + REST/gRPC xDS APIs. diff --git a/docs/root/configuration/configuration.rst b/docs/root/configuration/configuration.rst index ec5da63ffcd18..509c3e340a9af 100644 --- a/docs/root/configuration/configuration.rst +++ b/docs/root/configuration/configuration.rst @@ -6,7 +6,7 @@ Configuration reference .. toctree:: :maxdepth: 2 - overview/v2_overview + overview/overview listeners/listeners http/http upstream/upstream diff --git a/docs/root/configuration/http/http_filters/cors_filter.rst b/docs/root/configuration/http/http_filters/cors_filter.rst index 6db50963e22e3..a1a2d85dad29f 100644 --- a/docs/root/configuration/http/http_filters/cors_filter.rst +++ b/docs/root/configuration/http/http_filters/cors_filter.rst @@ -16,11 +16,11 @@ For the meaning of the headers please refer to the pages below. Runtime ------- The fraction of requests for which the filter is enabled can be configured via the :ref:`runtime_key -` value of the :ref:`filter_enabled +` value of the :ref:`filter_enabled ` field. The fraction of requests for which the filter is enabled in shadow-only mode can be configured via -the :ref:`runtime_key ` value of the +the :ref:`runtime_key ` value of the :ref:`shadow_enabled ` field. When enabled in shadow-only mode, the filter will evaluate the request's *Origin* to determine if it's valid but will not enforce any policies. diff --git a/docs/root/configuration/http/http_filters/csrf_filter.rst b/docs/root/configuration/http/http_filters/csrf_filter.rst index 93e3fe44354c0..3de1b2b5376d4 100644 --- a/docs/root/configuration/http/http_filters/csrf_filter.rst +++ b/docs/root/configuration/http/http_filters/csrf_filter.rst @@ -76,11 +76,11 @@ Runtime ------- The fraction of requests for which the filter is enabled can be configured via the :ref:`runtime_key -` value of the :ref:`filter_enabled +` value of the :ref:`filter_enabled ` field. The fraction of requests for which the filter is enabled in shadow-only mode can be configured via -the :ref:`runtime_key ` value of the +the :ref:`runtime_key ` value of the :ref:`shadow_enabled ` field. When enabled in shadow-only mode, the filter will evaluate the request's *Origin* and *Destination* to determine if it's valid but will not enforce any policies. diff --git a/docs/root/configuration/http/http_filters/ext_authz_filter.rst b/docs/root/configuration/http/http_filters/ext_authz_filter.rst index 757a142d2f673..b271c14acf406 100644 --- a/docs/root/configuration/http/http_filters/ext_authz_filter.rst +++ b/docs/root/configuration/http/http_filters/ext_authz_filter.rst @@ -139,5 +139,5 @@ The HTTP filter outputs statistics in the *cluster..ext_au Runtime ------- The fraction of requests for which the filter is enabled can be configured via the :ref:`runtime_key -` value of the :ref:`filter_enabled +` value of the :ref:`filter_enabled ` field. diff --git a/docs/root/configuration/overview/v2_overview.rst b/docs/root/configuration/overview/overview.rst similarity index 87% rename from docs/root/configuration/overview/v2_overview.rst rename to docs/root/configuration/overview/overview.rst index 004361529f13f..31c7919d4a404 100644 --- a/docs/root/configuration/overview/v2_overview.rst +++ b/docs/root/configuration/overview/overview.rst @@ -1,9 +1,9 @@ -.. _config_overview_v2: +.. _config_overview: Overview ======== -The Envoy v2 APIs are defined as `proto3 +The Envoy xDS APIs are defined as `proto3 `_ `Protocol Buffers `_ in the :repo:`api tree `. They support: @@ -21,14 +21,40 @@ support: when needed. The v2 APIs still maintain a baseline eventual consistency model. See the :ref:`xDS protocol description ` for -further details on aspects of v2 message exchange between Envoy and the management server. +further details on aspects of xDS message exchange between Envoy and the management server. -.. _config_overview_v2_bootstrap: +Versioning +---------- + +The Envoy xDS APIs follow a well defined :repo:`versioning scheme `. Envoy +supports :ref:`multiple major versions ` at any point in time. The examples +below are taken from the v2 xDS API. + +Envoy has API versions for both the xDS transport, i.e. the wire protocol for moving resources +between a management server and Envoy, and for resources. These are known as the transport and +resource API version respectively. + +The transport and resource version may be mixed. For example, v3 resources may be transferred over +the v2 transport protocol. In addition, an Envoy may consume mixed resource versions for distinct +resource types. For example, :ref:`v3 Clusters ` may be +used alongside :ref:`v2 Listeners `. + +Both the transport and resource API versions follow the API versioning support and deprecation +:repo:`policy `. + +.. note:: + + Envoy will internally operate at the latest xDS resource version and all supported versioned + resources will be transparently upgrading to this latest version on configuration ingestion. For + example, v2 and v3 resources, delivered over either a v2 or v3 transport, or any mix thereof, + will be internally converted into v3 resources. + +.. _config_overview_bootstrap: Bootstrap configuration ----------------------- -To use the v2 API, it's necessary to supply a bootstrap configuration file. This +To use the xDS API, it's necessary to supply a bootstrap configuration file. This provides static server configuration and configures Envoy to access :ref:`dynamic configuration if needed `. This is supplied on the command-line via the :option:`-c` flag, i.e.: @@ -37,7 +63,7 @@ the :option:`-c` flag, i.e.: ./envoy -c .{json,yaml,pb,pb_text} -where the extension reflects the underlying v2 config representation. +where the extension reflects the underlying config representation. The :ref:`Bootstrap ` message is the root of the configuration. A key concept in the :ref:`Bootstrap ` @@ -332,23 +358,26 @@ The management server could respond to EDS requests with: address: 127.0.0.2 port_value: 1234 -.. _config_overview_v2_management_server: +.. _config_overview_management_server: xDS API endpoints ----------------- -A v2 xDS management server will implement the below endpoints as required for +An xDS management server will implement the below endpoints as required for gRPC and/or REST serving. In both streaming gRPC and REST-JSON cases, a :ref:`DiscoveryRequest ` is sent and a :ref:`DiscoveryResponse ` received following the :ref:`xDS protocol `. +Below we describe endpoints for the v2 and v3 transport API versions. + .. _v2_grpc_streaming_endpoints: gRPC streaming endpoints ^^^^^^^^^^^^^^^^^^^^^^^^ .. http:post:: /envoy.api.v2.ClusterDiscoveryService/StreamClusters +.. http:post:: /envoy.service.cluster.v3.ClusterDiscoveryService/StreamClusters See :repo:`cds.proto ` for the service definition. This is used by Envoy as a client when @@ -358,6 +387,7 @@ as a client when cds_config: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -367,6 +397,7 @@ is set in the :ref:`dynamic_resources ` config. .. http:post:: /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints +.. http:post:: /envoy.service.endpoint.v3.EndpointDiscoveryService/StreamEndpoints See :repo:`eds.proto ` @@ -377,6 +408,7 @@ for the service definition. This is used by Envoy as a client when eds_config: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -386,6 +418,7 @@ is set in the :ref:`eds_cluster_config ` config. .. http:post:: /envoy.api.v2.ListenerDiscoveryService/StreamListeners +.. http:post:: /envoy.service.listener.v3.ListenerDiscoveryService/StreamListeners See :repo:`lds.proto ` @@ -396,6 +429,7 @@ for the service definition. This is used by Envoy as a client when lds_config: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -405,6 +439,7 @@ is set in the :ref:`dynamic_resources ` config. .. http:post:: /envoy.api.v2.RouteDiscoveryService/StreamRoutes +.. http:post:: /envoy.service.route.v3.RouteDiscoveryService/StreamRoutes See :repo:`rds.proto ` @@ -416,6 +451,7 @@ for the service definition. This is used by Envoy as a client when config_source: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -426,6 +462,7 @@ of the :ref:`HttpConnectionManager ` config. .. http:post:: /envoy.api.v2.ScopedRoutesDiscoveryService/StreamScopedRoutes +.. http:post:: /envoy.service.route.v3.ScopedRoutesDiscoveryService/StreamScopedRoutes See :repo:`srds.proto ` @@ -438,6 +475,7 @@ for the service definition. This is used by Envoy as a client when config_source: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -448,6 +486,7 @@ field of the :ref:`HttpConnectionManager ` config. .. http:post:: /envoy.service.discovery.v2.SecretDiscoveryService/StreamSecrets +.. http:post:: /envoy.service.secret.v3.SecretDiscoveryService/StreamSecrets See :repo:`sds.proto ` @@ -459,6 +498,7 @@ for the service definition. This is used by Envoy as a client when config_source: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -467,6 +507,7 @@ is set inside a :ref:`SdsSecretConfig ` mess is used in various places such as the :ref:`CommonTlsContext `. .. http:post:: /envoy.service.discovery.v2.RuntimeDiscoveryService/StreamRuntime +.. http:post:: /envoy.service.runtime.v3.RuntimeDiscoveryService/StreamRuntime See :repo:`rtds.proto ` @@ -478,6 +519,7 @@ for the service definition. This is used by Envoy as a client when config_source: api_config_source: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_xds_cluster @@ -489,6 +531,7 @@ REST endpoints ^^^^^^^^^^^^^^ .. http:post:: /v2/discovery:clusters +.. http:post:: /v3/discovery:clusters See :repo:`cds.proto ` @@ -499,6 +542,7 @@ for the service definition. This is used by Envoy as a client when cds_config: api_config_source: api_type: REST + transport_api_version: cluster_names: [some_xds_cluster] is set in the :ref:`dynamic_resources @@ -506,6 +550,7 @@ is set in the :ref:`dynamic_resources ` config. .. http:post:: /v2/discovery:endpoints +.. http:post:: /v3/discovery:endpoints See :repo:`eds.proto ` @@ -516,6 +561,7 @@ for the service definition. This is used by Envoy as a client when eds_config: api_config_source: api_type: REST + transport_api_version: cluster_names: [some_xds_cluster] is set in the :ref:`eds_cluster_config @@ -523,6 +569,7 @@ is set in the :ref:`eds_cluster_config ` config. .. http:post:: /v2/discovery:listeners +.. http:post:: /v3/discovery:listeners See :repo:`lds.proto ` @@ -533,6 +580,7 @@ for the service definition. This is used by Envoy as a client when lds_config: api_config_source: api_type: REST + transport_api_version: cluster_names: [some_xds_cluster] is set in the :ref:`dynamic_resources @@ -540,6 +588,7 @@ is set in the :ref:`dynamic_resources ` config. .. http:post:: /v2/discovery:routes +.. http:post:: /v3/discovery:routes See :repo:`rds.proto ` @@ -551,6 +600,7 @@ for the service definition. This is used by Envoy as a client when config_source: api_config_source: api_type: REST + transport_api_version: cluster_names: [some_xds_cluster] is set in the :ref:`rds @@ -563,10 +613,10 @@ is set in the :ref:`rds along with a HTTP status of 200. Additionally, if the configuration that would be supplied has not changed (as indicated by the version supplied by the Envoy client) then the management server can respond with an empty body and a HTTP status of 304. -.. _config_overview_v2_ads: +.. _config_overview_ads: Aggregated Discovery Service ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While Envoy fundamentally employs an eventual consistency model, ADS provides an opportunity to sequence API update pushes and ensure affinity of a single @@ -595,6 +645,7 @@ in :ref:`xDS ` document. The gRPC endpoint is: .. http:post:: /envoy.service.discovery.v2.AggregatedDiscoveryService/StreamAggregatedResources +.. http:post:: /envoy.service.discovery.v3.AggregatedDiscoveryService/StreamAggregatedResources See :repo:`discovery.proto ` @@ -604,6 +655,7 @@ for the service definition. This is used by Envoy as a client when ads_config: api_type: GRPC + transport_api_version: grpc_services: envoy_grpc: cluster_name: some_ads_cluster @@ -631,10 +683,10 @@ to with the effect that the LDS stream will be directed to *some_ads_cluster* over the shared ADS channel. -.. _config_overview_v2_delta: +.. _config_overview_delta: Delta endpoints ---------------- +^^^^^^^^^^^^^^^ The REST, filesystem, and original gRPC xDS implementations all deliver "state of the world" updates: every CDS update must contain every cluster, with the absence of a cluster from an update implying @@ -657,7 +709,7 @@ That works for both xDS and ADS; for ADS, it's the api_type field of :ref:`DynamicResources.ads_config `, as described in the previous section. -.. _config_overview_v2_mgmt_con_issues: +.. _config_overview_mgmt_con_issues: Management Server Unreachability -------------------------------- diff --git a/docs/root/faq/configuration/sni.rst b/docs/root/faq/configuration/sni.rst index 6e2a7fddcf825..2498f5d9975f5 100644 --- a/docs/root/faq/configuration/sni.rst +++ b/docs/root/faq/configuration/sni.rst @@ -4,7 +4,7 @@ How do I configure SNI? ======================= `SNI `_ is only supported in the :ref:`v2 -configuration/API `. +configuration/API `. .. attention:: diff --git a/docs/root/faq/configuration/zone_aware_routing.rst b/docs/root/faq/configuration/zone_aware_routing.rst index 3fffa973cde79..65c7967e0142b 100644 --- a/docs/root/faq/configuration/zone_aware_routing.rst +++ b/docs/root/faq/configuration/zone_aware_routing.rst @@ -35,7 +35,7 @@ Envoy configuration on the destination service ---------------------------------------------- It's not necessary to run Envoy side by side with the destination service, but it's important that each host in the destination cluster registers with the discovery service :ref:`queried by the source service Envoy -`. :ref:`Zone ` +`. :ref:`Zone ` information must be available as part of that response. Only zone related data is listed in the response below. diff --git a/docs/root/intro/arch_overview/operations/dynamic_configuration.rst b/docs/root/intro/arch_overview/operations/dynamic_configuration.rst index eb3204fa3347f..e2c0a00ea14dc 100644 --- a/docs/root/intro/arch_overview/operations/dynamic_configuration.rst +++ b/docs/root/intro/arch_overview/operations/dynamic_configuration.rst @@ -13,8 +13,8 @@ overview of the options currently available. * Top level configuration :ref:`reference `. * :ref:`Reference configurations `. -* Envoy :ref:`v2 API overview `. -* :ref:`xDS API endpoints `. +* Envoy :ref:`v2 API overview `. +* :ref:`xDS API endpoints `. Fully static ------------ @@ -118,7 +118,7 @@ EDS, CDS, etc. are each separate services, with different REST/gRPC service name StreamListeners, StreamSecrets. For users looking to enforce the order in which resources of different types reach Envoy, there is aggregated xDS, a single gRPC service that carries all resource types in a single gRPC stream. (ADS is only supported by gRPC). -:ref:`More details about ADS `. +:ref:`More details about ADS `. .. _arch_overview_dynamic_config_delta: @@ -129,4 +129,4 @@ Standard xDS is "state-of-the-world": every update must contain every resource, a resource from an update implying that the resource is gone. Envoy supports a "delta" variant of xDS (including ADS), where updates only contain resources added/changed/removed. Delta xDS is a new protocol, with request/response APIs different from SotW. -:ref:`More details about delta `. +:ref:`More details about delta `. diff --git a/docs/root/intro/arch_overview/other_protocols/grpc.rst b/docs/root/intro/arch_overview/other_protocols/grpc.rst index 1277ac6e983fd..87ae32984c88a 100644 --- a/docs/root/intro/arch_overview/other_protocols/grpc.rst +++ b/docs/root/intro/arch_overview/other_protocols/grpc.rst @@ -42,7 +42,7 @@ gRPC services In addition to proxying gRPC on the data plane, Envoy makes use of gRPC for its control plane, where it :ref:`fetches configuration from management server(s) -` and in filters, such as for :ref:`rate limiting +` and in filters, such as for :ref:`rate limiting ` or authorization checks. We refer to these as *gRPC services*. diff --git a/docs/root/intro/arch_overview/upstream/service_discovery.rst b/docs/root/intro/arch_overview/upstream/service_discovery.rst index 5147d3ef162ca..dbfd5220cb8d4 100644 --- a/docs/root/intro/arch_overview/upstream/service_discovery.rst +++ b/docs/root/intro/arch_overview/upstream/service_discovery.rst @@ -95,7 +95,7 @@ Endpoint discovery service (EDS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The *endpoint discovery service* is a :ref:`xDS management server based on gRPC or REST-JSON API server -` used by Envoy to fetch cluster members. The cluster members are called +` used by Envoy to fetch cluster members. The cluster members are called "endpoint" in Envoy terminology. For each cluster, Envoy fetch the endpoints from the discovery service. EDS is the preferred service discovery mechanism for a few reasons: diff --git a/docs/root/intro/deprecated.rst b/docs/root/intro/deprecated.rst index 215399eb26c14..f16a663164e27 100644 --- a/docs/root/intro/deprecated.rst +++ b/docs/root/intro/deprecated.rst @@ -25,6 +25,8 @@ Version 1.13.0 (pending) * The `service_name` field in :ref:`HTTP health checker ` has been deprecated in favor of the `service_name_matcher` field. +* The v2 xDS API is deprecated. It will be supported by Envoy until EOY 2020. See + :ref:`api_supported_versions`. Version 1.12.0 (October 31, 2019) ================================= diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst index a5aea28578032..82fa55987450d 100644 --- a/docs/root/intro/version_history.rst +++ b/docs/root/intro/version_history.rst @@ -10,6 +10,7 @@ Version history * access log: added HOSTNAME. * api: remove all support for v1 * api: added ability to specify `mode` for :ref:`Pipe `. +* api: support for the v3 xDS API added. See :ref:`api_supported_versions`. * buffer: remove old implementation * build: official released binary is now built against libc++. * cluster: added :ref:`aggregate cluster ` that allows load balancing between clusters. @@ -330,7 +331,7 @@ Version history * config: added support of using google.protobuf.Any in opaque configs for extensions. * config: logging warnings when deprecated fields are in use. * config: removed deprecated --v2-config-only from command line config. -* config: removed deprecated_v1 sds_config from :ref:`Bootstrap config `. +* config: removed deprecated_v1 sds_config from :ref:`Bootstrap config `. * config: removed the deprecated_v1 config option from :ref:`ring hash `. * config: removed REST_LEGACY as a valid :ref:`ApiType `. * config: finish cluster warming only when a named response i.e. ClusterLoadAssignment associated to the cluster being warmed comes in the EDS response. This is a behavioural change from the current implementation where warming of cluster completes on missing load assignments also. @@ -883,7 +884,7 @@ Version history * admin: added basic :ref:`Prometheus output ` for stats admin endpoint. Histograms are not currently output. * admin: added ``version_info`` to the :ref:`/clusters admin endpoint`. -* config: the :ref:`v2 API ` is now considered production ready. +* config: the :ref:`v2 API ` is now considered production ready. * config: added --v2-config-only CLI flag. * cors: added :ref:`CORS filter `. * health check: added :ref:`x-envoy-immediate-health-check-fail diff --git a/docs/root/operations/cli.rst b/docs/root/operations/cli.rst index df72fef85399d..a14f7efe97f43 100644 --- a/docs/root/operations/cli.rst +++ b/docs/root/operations/cli.rst @@ -11,7 +11,7 @@ following are the command line options that Envoy supports. *(optional)* The path to the v2 :ref:`JSON/YAML/proto3 configuration file `. If this flag is missing, :option:`--config-yaml` is required. This will be parsed as a :ref:`v2 bootstrap configuration file - `. + `. Valid extensions are ``.json``, ``.yaml``, ``.pb`` and ``.pb_text``, which indicate JSON, YAML, `binary proto3 `_ and `text diff --git a/docs/root/start/start.rst b/docs/root/start/start.rst index eec985b771faa..26f0e34be0d89 100644 --- a/docs/root/start/start.rst +++ b/docs/root/start/start.rst @@ -52,7 +52,7 @@ which in this case is simply `0.0.0.0:9901`. The :ref:`static_resources ` contains everything that is configured statically when Envoy starts, as opposed to the means of configuring resources dynamically when Envoy is running. -The :ref:`v2 API Overview ` describes this. +The :ref:`v2 API Overview ` describes this. .. code-block:: yaml diff --git a/generated_api_shadow/envoy/admin/v3/config_dump.proto b/generated_api_shadow/envoy/admin/v3/config_dump.proto index 506d070a5fa3f..8a527f6fd9bc5 100644 --- a/generated_api_shadow/envoy/admin/v3/config_dump.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/api/v2/auth/cert.proto b/generated_api_shadow/envoy/api/v2/auth/cert.proto index 0daf5acace748..e2302b2621a37 100644 --- a/generated_api_shadow/envoy/api/v2/auth/cert.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/api/v2/cluster.proto b/generated_api_shadow/envoy/api/v2/cluster.proto index 7616d1fe31d6a..2d61ef3f22b99 100644 --- a/generated_api_shadow/envoy/api/v2/cluster.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/api/v2/core/base.proto b/generated_api_shadow/envoy/api/v2/core/base.proto index c3b99ae813088..67a97dd6e25e8 100644 --- a/generated_api_shadow/envoy/api/v2/core/base.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/api/v2/core/health_check.proto b/generated_api_shadow/envoy/api/v2/core/health_check.proto index 806d263e29ded..91aeb76b8b425 100644 --- a/generated_api_shadow/envoy/api/v2/core/health_check.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/api/v2/route/route_components.proto b/generated_api_shadow/envoy/api/v2/route/route_components.proto index b386ca87f1f5a..d6c18b503cd66 100644 --- a/generated_api_shadow/envoy/api/v2/route/route_components.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/bootstrap/v2/bootstrap.proto b/generated_api_shadow/envoy/config/bootstrap/v2/bootstrap.proto index cc12345efbae4..f4e47afe0b514 100644 --- a/generated_api_shadow/envoy/config/bootstrap/v2/bootstrap.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto b/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto index bb2819054ccf0..f7e05a39b7569 100644 --- a/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto +++ b/generated_api_shadow/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 @@ -172,8 +172,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/generated_api_shadow/envoy/config/cluster/v3/circuit_breaker.proto b/generated_api_shadow/envoy/config/cluster/v3/circuit_breaker.proto index 1b6c1c99e1ea4..42de29b01e5b3 100644 --- a/generated_api_shadow/envoy/config/cluster/v3/circuit_breaker.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/cluster/v3/cluster.proto b/generated_api_shadow/envoy/config/cluster/v3/cluster.proto index da01d5458b44b..cb553f2f31dce 100644 --- a/generated_api_shadow/envoy/config/cluster/v3/cluster.proto +++ b/generated_api_shadow/envoy/config/cluster/v3/cluster.proto @@ -106,8 +106,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.] @@ -132,9 +131,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. @@ -244,15 +242,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; } @@ -491,9 +488,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}}]; } @@ -523,9 +519,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 @@ -585,32 +581,26 @@ message Cluster { // If the service discovery type is // :ref:`STATIC`, // :ref:`STRICT_DNS` - // or - // :ref:`LOGICAL_DNS`, + // or :ref:`LOGICAL_DNS`, // then hosts is required. // // .. attention:: // // **This field is deprecated**. Set the - // :ref:`load_assignment` field - // instead. + // :ref:`load_assignment` field instead. // repeated core.v3.Address hidden_envoy_deprecated_hosts = 7 [deprecated = true]; // 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; @@ -672,28 +662,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. @@ -711,15 +697,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; @@ -778,8 +762,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/generated_api_shadow/envoy/config/core/v3/base.proto b/generated_api_shadow/envoy/config/core/v3/base.proto index 4bc9a75a25f6e..0172a289c8dff 100644 --- a/generated_api_shadow/envoy/config/core/v3/base.proto +++ b/generated_api_shadow/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. @@ -143,7 +142,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/generated_api_shadow/envoy/config/core/v3/grpc_service.proto b/generated_api_shadow/envoy/config/core/v3/grpc_service.proto index 82c991b6348ef..98ab911a57e37 100644 --- a/generated_api_shadow/envoy/config/core/v3/grpc_service.proto +++ b/generated_api_shadow/envoy/config/core/v3/grpc_service.proto @@ -201,8 +201,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/generated_api_shadow/envoy/config/core/v3/health_check.proto b/generated_api_shadow/envoy/config/core/v3/health_check.proto index b9e35b220fa4d..c534fa77a777b 100644 --- a/generated_api_shadow/envoy/config/core/v3/health_check.proto +++ b/generated_api_shadow/envoy/config/core/v3/health_check.proto @@ -125,10 +125,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 @@ -210,9 +207,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/generated_api_shadow/envoy/config/filter/http/csrf/v2/csrf.proto b/generated_api_shadow/envoy/config/filter/http/csrf/v2/csrf.proto index f1463066babf0..ce38714bf45f5 100644 --- a/generated_api_shadow/envoy/config/filter/http/csrf/v2/csrf.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/filter/http/ext_authz/v2/ext_authz.proto b/generated_api_shadow/envoy/config/filter/http/ext_authz/v2/ext_authz.proto index 064040fd6c5b2..d80ca7f479610 100644 --- a/generated_api_shadow/envoy/config/filter/http/ext_authz/v2/ext_authz.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto b/generated_api_shadow/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto index 3eac388c904b5..f0996392f9524 100644 --- a/generated_api_shadow/envoy/config/filter/network/redis_proxy/v2/redis_proxy.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto b/generated_api_shadow/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto index 7430ec8857521..91ac5da3ef28b 100644 --- a/generated_api_shadow/envoy/config/filter/network/thrift_proxy/v2alpha1/thrift_proxy.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/listener/v3/listener.proto b/generated_api_shadow/envoy/config/listener/v3/listener.proto index 767fe197e94d5..6785848e5383d 100644 --- a/generated_api_shadow/envoy/config/listener/v3/listener.proto +++ b/generated_api_shadow/envoy/config/listener/v3/listener.proto @@ -94,8 +94,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 `. @@ -110,13 +110,12 @@ message Listener { // .. attention:: // // This field is deprecated. Use :ref:`an original_dst ` - // :ref:`listener filter ` - // instead. + // :ref:`listener filter ` instead. // // Note that hand off to another listener is *NOT* performed without this flag. Once - // :ref:`FilterChainMatch ` is implemented - // this flag will be removed, as filter chain matching can be used to select a filter chain - // based on the restored destination address. + // :ref:`FilterChainMatch ` is implemented this flag + // will be removed, as filter chain matching can be used to select a filter chain based on the + // restored destination address. google.protobuf.BoolValue hidden_envoy_deprecated_use_original_dst = 4 [deprecated = true]; // Soft limit on size of the listener’s new connection read and write buffers. @@ -134,11 +133,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; @@ -163,14 +162,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 @@ -206,16 +206,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/generated_api_shadow/envoy/config/listener/v3/listener_components.proto b/generated_api_shadow/envoy/config/listener/v3/listener_components.proto index e18c86142bf89..0b771b66e370f 100644 --- a/generated_api_shadow/envoy/config/listener/v3/listener_components.proto +++ b/generated_api_shadow/envoy/config/listener/v3/listener_components.proto @@ -201,10 +201,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/generated_api_shadow/envoy/config/rbac/v3/rbac.proto b/generated_api_shadow/envoy/config/rbac/v3/rbac.proto index 355b072a5598d..3320c86a885fe 100644 --- a/generated_api_shadow/envoy/config/rbac/v3/rbac.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/route/v3/BUILD b/generated_api_shadow/envoy/config/route/v3/BUILD index e96fada49ddb6..019cf27528c6a 100644 --- a/generated_api_shadow/envoy/config/route/v3/BUILD +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/route/v3/route.proto b/generated_api_shadow/envoy/config/route/v3/route.proto index ef3ab0e1e2760..96faec71e73b6 100644 --- a/generated_api_shadow/envoy/config/route/v3/route.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/config/route/v3/route_components.proto b/generated_api_shadow/envoy/config/route/v3/route_components.proto index cacaef306c647..d3cebd0a8404d 100644 --- a/generated_api_shadow/envoy/config/route/v3/route_components.proto +++ b/generated_api_shadow/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"; @@ -91,8 +91,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 @@ -104,8 +104,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 @@ -230,8 +230,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 @@ -243,8 +243,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 @@ -264,11 +264,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"; @@ -284,46 +285,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 @@ -523,8 +522,7 @@ message CorsPolicy { // .. attention:: // // **This field is deprecated**. Set the - // :ref:`filter_enabled` field - // instead. + // :ref:`filter_enabled` field instead. google.protobuf.BoolValue hidden_envoy_deprecated_enabled = 7 [deprecated = true, (envoy.annotations.disallowed_by_default) = true]; @@ -533,7 +531,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; } @@ -544,7 +542,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; @@ -598,14 +596,14 @@ 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 hidden_envoy_deprecated_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. @@ -776,8 +774,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 @@ -889,8 +887,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 @@ -913,9 +911,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 @@ -937,14 +935,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. @@ -1145,8 +1142,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; } @@ -1172,8 +1168,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; } @@ -1221,11 +1217,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 @@ -1314,16 +1310,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 = @@ -1462,9 +1456,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/generated_api_shadow/envoy/config/route/v3/scoped_route.proto b/generated_api_shadow/envoy/config/route/v3/scoped_route.proto index 257d87f7c3166..fee88e862f47b 100644 --- a/generated_api_shadow/envoy/config/route/v3/scoped_route.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/data/cluster/v2alpha/BUILD b/generated_api_shadow/envoy/data/cluster/v2alpha/BUILD index 5dc095ade27a9..ef3541ebcb1df 100644 --- a/generated_api_shadow/envoy/data/cluster/v2alpha/BUILD +++ b/generated_api_shadow/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/generated_api_shadow/envoy/data/cluster/v2alpha/outlier_detection_event.proto b/generated_api_shadow/envoy/data/cluster/v2alpha/outlier_detection_event.proto index abbf57cd86066..cec29bccc73f1 100644 --- a/generated_api_shadow/envoy/data/cluster/v2alpha/outlier_detection_event.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/data/cluster/v3/BUILD b/generated_api_shadow/envoy/data/cluster/v3/BUILD new file mode 100644 index 0000000000000..33355e7efa192 --- /dev/null +++ b/generated_api_shadow/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/generated_api_shadow/envoy/data/cluster/v3/outlier_detection_event.proto b/generated_api_shadow/envoy/data/cluster/v3/outlier_detection_event.proto new file mode 100644 index 0000000000000..6e9d59b0e15da --- /dev/null +++ b/generated_api_shadow/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/generated_api_shadow/envoy/data/core/v3/health_check_event.proto b/generated_api_shadow/envoy/data/core/v3/health_check_event.proto index 6de8c6924e698..7ad278876dcfd 100644 --- a/generated_api_shadow/envoy/data/core/v3/health_check_event.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/extensions/filters/http/csrf/v3/csrf.proto b/generated_api_shadow/envoy/extensions/filters/http/csrf/v3/csrf.proto index 988ed1bddb3f6..7748abf88d365 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/csrf/v3/csrf.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto b/generated_api_shadow/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto index bb9a85833fa1c..35e8a608d4738 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/dynamic_forward_proxy/v3/dynamic_forward_proxy.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/generated_api_shadow/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 549b1b0ab1a67..87ec05d2491ee 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto @@ -93,7 +93,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. @@ -172,8 +172,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/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/BUILD b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/BUILD index 249b1c74b6e37..7a8608967e4a2 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/BUILD +++ b/generated_api_shadow/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/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index 5d7b252e2f5ef..d41b41a8f9eb3 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/generated_api_shadow/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"; @@ -160,7 +160,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 { @@ -532,16 +532,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/generated_api_shadow/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto b/generated_api_shadow/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto index bc6dd71a4faef..b56940edaa049 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto @@ -250,7 +250,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/generated_api_shadow/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto b/generated_api_shadow/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto index 980a48593defc..8c58ba2eb1296 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto @@ -112,8 +112,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/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto index 8b4d93ba1d7f8..1301566649422 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/filters/ratelimit/v3/rate_limit.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto index c6b01149afdd4..16e3ce8e96b85 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto @@ -107,7 +107,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/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/cert.proto b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/cert.proto index eaa27cad959e2..9cbc61fec9fd9 100644 --- a/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/cert.proto +++ b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/cert.proto @@ -139,12 +139,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 @@ -167,8 +167,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. @@ -204,10 +203,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. @@ -235,11 +234,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:: // @@ -272,11 +270,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}}}]; @@ -391,8 +388,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/generated_api_shadow/envoy/service/discovery/v3/discovery.proto b/generated_api_shadow/envoy/service/discovery/v3/discovery.proto index 1c29b82dd5597..02997a51dca23 100644 --- a/generated_api_shadow/envoy/service/discovery/v3/discovery.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/service/route/v3/rds.proto b/generated_api_shadow/envoy/service/route/v3/rds.proto index 3ab92481662f5..3514ebd2a2c73 100644 --- a/generated_api_shadow/envoy/service/route/v3/rds.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/matcher/v3/metadata.proto b/generated_api_shadow/envoy/type/matcher/v3/metadata.proto index de43319e54048..586c2ea8d9422 100644 --- a/generated_api_shadow/envoy/type/matcher/v3/metadata.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/metadata/v2/BUILD b/generated_api_shadow/envoy/type/metadata/v2/BUILD index 5dc095ade27a9..ef3541ebcb1df 100644 --- a/generated_api_shadow/envoy/type/metadata/v2/BUILD +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/metadata/v2/metadata.proto b/generated_api_shadow/envoy/type/metadata/v2/metadata.proto index 401b974824c90..67653519ba973 100644 --- a/generated_api_shadow/envoy/type/metadata/v2/metadata.proto +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/metadata/v3/BUILD b/generated_api_shadow/envoy/type/metadata/v3/BUILD new file mode 100644 index 0000000000000..34e1b604ce9f7 --- /dev/null +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/metadata/v3/metadata.proto b/generated_api_shadow/envoy/type/metadata/v3/metadata.proto new file mode 100644 index 0000000000000..f8a98d0b58054 --- /dev/null +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/tracing/v3/BUILD b/generated_api_shadow/envoy/type/tracing/v3/BUILD new file mode 100644 index 0000000000000..fe55e0428c7a4 --- /dev/null +++ b/generated_api_shadow/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/generated_api_shadow/envoy/type/tracing/v3/custom_tag.proto b/generated_api_shadow/envoy/type/tracing/v3/custom_tag.proto new file mode 100644 index 0000000000000..a1e0bdb9bf2ed --- /dev/null +++ b/generated_api_shadow/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/source/common/config/BUILD b/source/common/config/BUILD index f5ffedd1bcd6d..24769e4df38d9 100644 --- a/source/common/config/BUILD +++ b/source/common/config/BUILD @@ -216,7 +216,7 @@ envoy_cc_library( "//source/common/protobuf", "//source/common/protobuf:utility_lib", "@envoy_api//envoy/config/core/v3:pkg_cc_proto", - "@envoy_api//envoy/type/metadata/v2:pkg_cc_proto", + "@envoy_api//envoy/type/metadata/v3:pkg_cc_proto", ], ) diff --git a/source/common/config/metadata.cc b/source/common/config/metadata.cc index 5850f74af3df5..509c3f2db85af 100644 --- a/source/common/config/metadata.cc +++ b/source/common/config/metadata.cc @@ -1,14 +1,14 @@ #include "common/config/metadata.h" #include "envoy/config/core/v3/base.pb.h" -#include "envoy/type/metadata/v2/metadata.pb.h" +#include "envoy/type/metadata/v3/metadata.pb.h" #include "common/protobuf/utility.h" namespace Envoy { namespace Config { -MetadataKey::MetadataKey(const envoy::type::metadata::v2::MetadataKey& metadata_key) +MetadataKey::MetadataKey(const envoy::type::metadata::v3::MetadataKey& metadata_key) : key_(metadata_key.key()) { for (const auto& seg : metadata_key.path()) { path_.push_back(seg.key()); diff --git a/source/common/config/metadata.h b/source/common/config/metadata.h index df6e9fb62e9a5..5ad2315d5c038 100644 --- a/source/common/config/metadata.h +++ b/source/common/config/metadata.h @@ -7,7 +7,7 @@ #include "envoy/config/core/v3/base.pb.h" #include "envoy/config/typed_metadata.h" #include "envoy/registry/registry.h" -#include "envoy/type/metadata/v2/metadata.pb.h" +#include "envoy/type/metadata/v3/metadata.pb.h" #include "common/protobuf/protobuf.h" @@ -21,7 +21,7 @@ struct MetadataKey { std::string key_; std::vector path_; - MetadataKey(const envoy::type::metadata::v2::MetadataKey& metadata_key); + MetadataKey(const envoy::type::metadata::v3::MetadataKey& metadata_key); }; /** diff --git a/source/common/tracing/BUILD b/source/common/tracing/BUILD index 018b31404a654..b2ce19b962174 100644 --- a/source/common/tracing/BUILD +++ b/source/common/tracing/BUILD @@ -39,7 +39,7 @@ envoy_cc_library( "//source/common/runtime:uuid_util_lib", "//source/common/stream_info:utility_lib", "@envoy_api//envoy/config/core/v3:pkg_cc_proto", - "@envoy_api//envoy/type/metadata/v2:pkg_cc_proto", - "@envoy_api//envoy/type/tracing/v2:pkg_cc_proto", + "@envoy_api//envoy/type/metadata/v3:pkg_cc_proto", + "@envoy_api//envoy/type/tracing/v3:pkg_cc_proto", ], ) diff --git a/source/common/tracing/http_tracer_impl.cc b/source/common/tracing/http_tracer_impl.cc index 3ceb527e4dd9c..3e15539382b89 100644 --- a/source/common/tracing/http_tracer_impl.cc +++ b/source/common/tracing/http_tracer_impl.cc @@ -3,8 +3,8 @@ #include #include "envoy/config/core/v3/base.pb.h" -#include "envoy/type/metadata/v2/metadata.pb.h" -#include "envoy/type/tracing/v2/custom_tag.pb.h" +#include "envoy/type/metadata/v3/metadata.pb.h" +#include "envoy/type/tracing/v3/custom_tag.pb.h" #include "common/access_log/access_log_formatter.h" #include "common/common/assert.h" @@ -248,15 +248,15 @@ void HttpTracerUtility::setCommonTags(Span& span, const Http::HeaderMap* respons } CustomTagConstSharedPtr -HttpTracerUtility::createCustomTag(const envoy::type::tracing::v2::CustomTag& tag) { +HttpTracerUtility::createCustomTag(const envoy::type::tracing::v3::CustomTag& tag) { switch (tag.type_case()) { - case envoy::type::tracing::v2::CustomTag::TypeCase::kLiteral: + case envoy::type::tracing::v3::CustomTag::TypeCase::kLiteral: return std::make_shared(tag.tag(), tag.literal()); - case envoy::type::tracing::v2::CustomTag::TypeCase::kEnvironment: + case envoy::type::tracing::v3::CustomTag::TypeCase::kEnvironment: return std::make_shared(tag.tag(), tag.environment()); - case envoy::type::tracing::v2::CustomTag::TypeCase::kRequestHeader: + case envoy::type::tracing::v3::CustomTag::TypeCase::kRequestHeader: return std::make_shared(tag.tag(), tag.request_header()); - case envoy::type::tracing::v2::CustomTag::TypeCase::kMetadata: + case envoy::type::tracing::v3::CustomTag::TypeCase::kMetadata: return std::make_shared(tag.tag(), tag.metadata()); default: NOT_REACHED_GCOVR_EXCL_LINE; @@ -296,14 +296,14 @@ void CustomTagBase::apply(Span& span, const CustomTagContext& ctx) const { } EnvironmentCustomTag::EnvironmentCustomTag( - const std::string& tag, const envoy::type::tracing::v2::CustomTag::Environment& environment) + const std::string& tag, const envoy::type::tracing::v3::CustomTag::Environment& environment) : CustomTagBase(tag), name_(environment.name()), default_value_(environment.default_value()) { const char* env = std::getenv(name_.data()); final_value_ = env ? env : default_value_; } RequestHeaderCustomTag::RequestHeaderCustomTag( - const std::string& tag, const envoy::type::tracing::v2::CustomTag::Header& request_header) + const std::string& tag, const envoy::type::tracing::v3::CustomTag::Header& request_header) : CustomTagBase(tag), name_(Http::LowerCaseString(request_header.name())), default_value_(request_header.default_value()) {} @@ -316,7 +316,7 @@ absl::string_view RequestHeaderCustomTag::value(const CustomTagContext& ctx) con } MetadataCustomTag::MetadataCustomTag(const std::string& tag, - const envoy::type::tracing::v2::CustomTag::Metadata& metadata) + const envoy::type::tracing::v3::CustomTag::Metadata& metadata) : CustomTagBase(tag), kind_(metadata.kind().kind_case()), metadata_key_(metadata.metadata_key()), default_value_(metadata.default_value()) {} @@ -357,17 +357,17 @@ const envoy::config::core::v3::Metadata* MetadataCustomTag::metadata(const CustomTagContext& ctx) const { const StreamInfo::StreamInfo& info = ctx.stream_info; switch (kind_) { - case envoy::type::metadata::v2::MetadataKind::KindCase::kRequest: + case envoy::type::metadata::v3::MetadataKind::KindCase::kRequest: return &info.dynamicMetadata(); - case envoy::type::metadata::v2::MetadataKind::KindCase::kRoute: { + case envoy::type::metadata::v3::MetadataKind::KindCase::kRoute: { const Router::RouteEntry* route_entry = info.routeEntry(); return route_entry ? &route_entry->metadata() : nullptr; } - case envoy::type::metadata::v2::MetadataKind::KindCase::kCluster: { + case envoy::type::metadata::v3::MetadataKind::KindCase::kCluster: { const auto& hostPtr = info.upstreamHost(); return hostPtr ? &hostPtr->cluster().metadata() : nullptr; } - case envoy::type::metadata::v2::MetadataKind::KindCase::kHost: { + case envoy::type::metadata::v3::MetadataKind::KindCase::kHost: { const auto& hostPtr = info.upstreamHost(); return hostPtr ? hostPtr->metadata().get() : nullptr; } diff --git a/source/common/tracing/http_tracer_impl.h b/source/common/tracing/http_tracer_impl.h index cb05262ebe0ef..80d5cc10a2ee2 100644 --- a/source/common/tracing/http_tracer_impl.h +++ b/source/common/tracing/http_tracer_impl.h @@ -8,8 +8,8 @@ #include "envoy/runtime/runtime.h" #include "envoy/thread_local/thread_local.h" #include "envoy/tracing/http_tracer.h" -#include "envoy/type/metadata/v2/metadata.pb.h" -#include "envoy/type/tracing/v2/custom_tag.pb.h" +#include "envoy/type/metadata/v3/metadata.pb.h" +#include "envoy/type/tracing/v3/custom_tag.pb.h" #include "envoy/upstream/cluster_manager.h" #include "common/config/metadata.h" @@ -132,7 +132,7 @@ class HttpTracerUtility { * Create a custom tag according to the configuration. * @param tag a tracing custom tag configuration. */ - static CustomTagConstSharedPtr createCustomTag(const envoy::type::tracing::v2::CustomTag& tag); + static CustomTagConstSharedPtr createCustomTag(const envoy::type::tracing::v3::CustomTag& tag); private: static void setCommonTags(Span& span, const Http::HeaderMap* response_headers, @@ -212,7 +212,7 @@ class CustomTagBase : public CustomTag { class LiteralCustomTag : public CustomTagBase { public: LiteralCustomTag(const std::string& tag, - const envoy::type::tracing::v2::CustomTag::Literal& literal) + const envoy::type::tracing::v3::CustomTag::Literal& literal) : CustomTagBase(tag), value_(literal.value()) {} absl::string_view value(const CustomTagContext&) const override { return value_; } @@ -223,7 +223,7 @@ class LiteralCustomTag : public CustomTagBase { class EnvironmentCustomTag : public CustomTagBase { public: EnvironmentCustomTag(const std::string& tag, - const envoy::type::tracing::v2::CustomTag::Environment& environment); + const envoy::type::tracing::v3::CustomTag::Environment& environment); absl::string_view value(const CustomTagContext&) const override { return final_value_; } private: @@ -235,7 +235,7 @@ class EnvironmentCustomTag : public CustomTagBase { class RequestHeaderCustomTag : public CustomTagBase { public: RequestHeaderCustomTag(const std::string& tag, - const envoy::type::tracing::v2::CustomTag::Header& request_header); + const envoy::type::tracing::v3::CustomTag::Header& request_header); absl::string_view value(const CustomTagContext& ctx) const override; private: @@ -246,13 +246,13 @@ class RequestHeaderCustomTag : public CustomTagBase { class MetadataCustomTag : public CustomTagBase { public: MetadataCustomTag(const std::string& tag, - const envoy::type::tracing::v2::CustomTag::Metadata& metadata); + const envoy::type::tracing::v3::CustomTag::Metadata& metadata); void apply(Span& span, const CustomTagContext& ctx) const override; absl::string_view value(const CustomTagContext&) const override { return default_value_; } const envoy::config::core::v3::Metadata* metadata(const CustomTagContext& ctx) const; protected: - const envoy::type::metadata::v2::MetadataKind::KindCase kind_; + const envoy::type::metadata::v3::MetadataKind::KindCase kind_; const Envoy::Config::MetadataKey metadata_key_; const std::string default_value_; }; diff --git a/source/extensions/filters/network/http_connection_manager/BUILD b/source/extensions/filters/network/http_connection_manager/BUILD index c566531c557e1..22fda55593a63 100644 --- a/source/extensions/filters/network/http_connection_manager/BUILD +++ b/source/extensions/filters/network/http_connection_manager/BUILD @@ -45,7 +45,7 @@ envoy_cc_extension( "//source/extensions/filters/network/common:factory_base_lib", "@envoy_api//envoy/config/core/v3:pkg_cc_proto", "@envoy_api//envoy/extensions/filters/network/http_connection_manager/v3:pkg_cc_proto", - "@envoy_api//envoy/type/tracing/v2:pkg_cc_proto", + "@envoy_api//envoy/type/tracing/v3:pkg_cc_proto", "@envoy_api//envoy/type/v3:pkg_cc_proto", ], ) diff --git a/source/extensions/filters/network/http_connection_manager/config.cc b/source/extensions/filters/network/http_connection_manager/config.cc index 3848e7f486fbd..ba46e92c99f3b 100644 --- a/source/extensions/filters/network/http_connection_manager/config.cc +++ b/source/extensions/filters/network/http_connection_manager/config.cc @@ -11,7 +11,7 @@ #include "envoy/filesystem/filesystem.h" #include "envoy/server/admin.h" #include "envoy/tracing/http_tracer.h" -#include "envoy/type/tracing/v2/custom_tag.pb.h" +#include "envoy/type/tracing/v3/custom_tag.pb.h" #include "envoy/type/v3/percent.pb.h" #include "common/access_log/access_log_impl.h" @@ -309,7 +309,7 @@ HttpConnectionManagerConfig::HttpConnectionManagerConfig( Tracing::CustomTagMap custom_tags; for (const std::string& header : tracing_config.hidden_envoy_deprecated_request_headers_for_tags()) { - envoy::type::tracing::v2::CustomTag::Header headerTag; + envoy::type::tracing::v3::CustomTag::Header headerTag; headerTag.set_name(header); custom_tags.emplace( header, std::make_shared(header, headerTag)); diff --git a/test/common/http/BUILD b/test/common/http/BUILD index 7b7584d7cba32..593d22653e689 100644 --- a/test/common/http/BUILD +++ b/test/common/http/BUILD @@ -209,7 +209,7 @@ envoy_cc_test( "//test/test_common:logging_lib", "//test/test_common:test_time_lib", "@envoy_api//envoy/extensions/filters/network/http_connection_manager/v3:pkg_cc_proto", - "@envoy_api//envoy/type/tracing/v2:pkg_cc_proto", + "@envoy_api//envoy/type/tracing/v3:pkg_cc_proto", "@envoy_api//envoy/type/v3:pkg_cc_proto", ], ) diff --git a/test/common/http/conn_manager_impl_test.cc b/test/common/http/conn_manager_impl_test.cc index 54df22445389f..2d63ba04fc4bf 100644 --- a/test/common/http/conn_manager_impl_test.cc +++ b/test/common/http/conn_manager_impl_test.cc @@ -9,7 +9,7 @@ #include "envoy/event/dispatcher.h" #include "envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.pb.h" #include "envoy/tracing/http_tracer.h" -#include "envoy/type/tracing/v2/custom_tag.pb.h" +#include "envoy/type/tracing/v3/custom_tag.pb.h" #include "envoy/type/v3/percent.pb.h" #include "common/access_log/access_log_formatter.h" @@ -112,7 +112,7 @@ class HttpConnectionManagerImplTest : public testing::Test, public ConnectionMan } Tracing::CustomTagConstSharedPtr requestHeaderCustomTag(const std::string& header) { - envoy::type::tracing::v2::CustomTag::Header headerTag; + envoy::type::tracing::v3::CustomTag::Header headerTag; headerTag.set_name(header); return std::make_shared(header, headerTag); } @@ -845,24 +845,24 @@ TEST_F(HttpConnectionManagerImplTest, StartAndFinishSpanNormalFlow) { std::vector tracing_tag_meta_cases = { {"l-tag", [](const std::string& t, const std::string& v) { - envoy::type::tracing::v2::CustomTag::Literal literal; + envoy::type::tracing::v3::CustomTag::Literal literal; literal.set_value(v); return std::make_shared(t, literal); }}, {"e-tag", [](const std::string& t, const std::string& v) { - envoy::type::tracing::v2::CustomTag::Environment e; + envoy::type::tracing::v3::CustomTag::Environment e; e.set_default_value(v); return std::make_shared(t, e); }}, {"x-tag", [](const std::string& t, const std::string& v) { - envoy::type::tracing::v2::CustomTag::Header h; + envoy::type::tracing::v3::CustomTag::Header h; h.set_default_value(v); return std::make_shared(t, h); }}, {"m-tag", [](const std::string& t, const std::string& v) { - envoy::type::tracing::v2::CustomTag::Metadata m; + envoy::type::tracing::v3::CustomTag::Metadata m; m.mutable_kind()->mutable_host(); m.set_default_value(v); return std::make_shared(t, m); diff --git a/test/common/tracing/BUILD b/test/common/tracing/BUILD index b3e1e718f8764..de957f4bd792d 100644 --- a/test/common/tracing/BUILD +++ b/test/common/tracing/BUILD @@ -32,6 +32,6 @@ envoy_cc_test( "//test/test_common:environment_lib", "//test/test_common:utility_lib", "@envoy_api//envoy/config/core/v3:pkg_cc_proto", - "@envoy_api//envoy/type/tracing/v2:pkg_cc_proto", + "@envoy_api//envoy/type/tracing/v3:pkg_cc_proto", ], ) diff --git a/test/common/tracing/http_tracer_impl_test.cc b/test/common/tracing/http_tracer_impl_test.cc index da9eb9535db16..a250a794d298b 100644 --- a/test/common/tracing/http_tracer_impl_test.cc +++ b/test/common/tracing/http_tracer_impl_test.cc @@ -3,7 +3,7 @@ #include #include "envoy/config/core/v3/base.pb.h" -#include "envoy/type/tracing/v2/custom_tag.pb.h" +#include "envoy/type/tracing/v3/custom_tag.pb.h" #include "common/common/base64.h" #include "common/http/header_map_impl.h" @@ -125,7 +125,7 @@ class HttpConnManFinalizerImplTest : public testing::Test { void expectSetCustomTags(const std::vector& cases) { for (const CustomTagCase& cas : cases) { - envoy::type::tracing::v2::CustomTag custom_tag; + envoy::type::tracing::v3::CustomTag custom_tag; TestUtility::loadFromYaml(cas.custom_tag, custom_tag); config.custom_tags_.emplace(custom_tag.tag(), HttpTracerUtility::createCustomTag(custom_tag)); if (cas.set) { diff --git a/tools/proto_format.sh b/tools/proto_format.sh index fdc515fd108ed..3308909c0c798 100755 --- a/tools/proto_format.sh +++ b/tools/proto_format.sh @@ -26,4 +26,7 @@ bazel build ${BAZEL_BUILD_OPTIONS} --//tools/api_proto_plugin:default_type_db_ta --action_env=CPROFILE_ENABLED=1 --host_force_python=PY3 ./tools/proto_sync.py "--mode=$1" ${PROTO_TARGETS} +bazel build ${BAZEL_BUILD_OPTIONS} //tools/type_whisperer:api_build_file +cp -f bazel-bin/tools/type_whisperer/BUILD.api_build_file api/BUILD + cp -f ./api/bazel/*.bzl ./api/bazel/BUILD ./generated_api_shadow/bazel diff --git a/tools/proto_sync.py b/tools/proto_sync.py index 0c9617c344db2..36c40fd12504b 100755 --- a/tools/proto_sync.py +++ b/tools/proto_sync.py @@ -44,22 +44,6 @@ api_proto_package($fields) """) -TOP_LEVEL_API_BUILD_FILE_TEMPLATE = string.Template( - '''# DO NOT EDIT. This file is generated by tools/proto_sync.py. - -load("@rules_proto//proto:defs.bzl", "proto_library") - -licenses(["notice"]) # Apache 2 - -proto_library( - name = "protos", - visibility = ["//visibility:public"], - deps = [ -$deps - ], -) -''') - IMPORT_REGEX = re.compile('import "(.*)";') SERVICE_REGEX = re.compile('service \w+ {') PACKAGE_REGEX = re.compile('\npackage ([^="]*);') @@ -311,11 +295,6 @@ def Sync(api_root, mode, labels, shadow): else: subprocess.run(['patch', '-p1'], input=diff, cwd=str(api_root_path.resolve())) - with open(os.path.join(api_root, 'BUILD'), 'w') as f: - formatted_deps = '\n'.join( - ' "%s",' % d for d in sorted(set(pkg_deps), key=BuildOrderKey)) - f.write(TOP_LEVEL_API_BUILD_FILE_TEMPLATE.substitute(deps=formatted_deps)) - if __name__ == '__main__': parser = argparse.ArgumentParser() diff --git a/tools/protoxform/BUILD b/tools/protoxform/BUILD index a4f15e37095fc..268579f06be62 100644 --- a/tools/protoxform/BUILD +++ b/tools/protoxform/BUILD @@ -8,6 +8,7 @@ py_binary( "protoxform.py", "utils.py", ], + data = ["//:.clang-format"], python_version = "PY3", visibility = ["//visibility:public"], deps = [ diff --git a/tools/protoxform/migrate.py b/tools/protoxform/migrate.py index 58307dc221252..abd984c852cd4 100644 --- a/tools/protoxform/migrate.py +++ b/tools/protoxform/migrate.py @@ -12,7 +12,9 @@ from udpa.annotations import migrate_pb2 from google.api import annotations_pb2 -ENVOY_COMMENT_WITH_TYPE_REGEX = re.compile('') +ENVOY_API_TYPE_REGEX_STR = 'envoy_api_(msg|enum_value|field|enum)_([\w\.]+)' +ENVOY_COMMENT_WITH_TYPE_REGEX = re.compile('<%s>|:ref:`%s`' % + (ENVOY_API_TYPE_REGEX_STR, ENVOY_API_TYPE_REGEX_STR)) class UpgradeVisitor(visitor.Visitor): @@ -32,7 +34,14 @@ def UpgradeType(match): # stylized and match the output format of tools/protodoc. We need to do # some special handling of field/enum values, and also the normalization # that was performed in v2 for envoy.api.v2 types. - ref_type, normalized_type_name = match.groups() + label_ref_type, label_normalized_type_name, section_ref_type, section_normalized_type_name = match.groups( + ) + if label_ref_type is not None: + ref_type = label_ref_type + normalized_type_name = label_normalized_type_name + else: + ref_type = section_ref_type + normalized_type_name = section_normalized_type_name if ref_type == 'field' or ref_type == 'enum_value': normalized_type_name, residual = normalized_type_name.rsplit('.', 1) else: @@ -47,7 +56,20 @@ def UpgradeType(match): type_desc = self._typedb.types[api_v2_type_name] repl_type = type_desc.next_version_type_name[len( 'envoy.'):] if type_desc.next_version_type_name else normalized_type_name - return '' % (ref_type, repl_type, '.' + residual if residual else '') + # TODO(htuch): this should really either go through the type database or + # via the descriptor pool and annotations, but there are only two of these + # we need for the initial v2 -> v3 docs cut, so hard coding for now. + # Tracked at https://github.com/envoyproxy/envoy/issues/9734. + if repl_type == 'config.route.v3.RouteAction': + if residual == 'host_rewrite': + residual = 'host_rewrite_literal' + elif residual == 'auto_host_rewrite_header': + residual = 'auto_host_rewrite' + new_ref = 'envoy_api_%s_%s%s' % (ref_type, repl_type, '.' + residual if residual else '') + if label_ref_type is not None: + return '<%s>' % new_ref + else: + return ':ref:`%s`' % new_ref return re.sub(ENVOY_COMMENT_WITH_TYPE_REGEX, UpgradeType, c) diff --git a/tools/protoxform/protoxform.py b/tools/protoxform/protoxform.py index 8e6de1599b0ed..e183a6f44851f 100755 --- a/tools/protoxform/protoxform.py +++ b/tools/protoxform/protoxform.py @@ -13,6 +13,7 @@ import functools import io import os +import pathlib import re import subprocess @@ -38,9 +39,6 @@ from envoy.annotations import resource_pb2 from udpa.annotations import migrate_pb2 -CLANG_FORMAT_STYLE = ('{ColumnLimit: 100, SpacesInContainerLiterals: false, ' - 'AllowShortFunctionsOnASingleLine: false}') - NEXT_FREE_FIELD_MIN = 5 @@ -48,6 +46,37 @@ class ProtoXformError(Exception): """Base error class for the protoxform module.""" +def ExtractClangProtoStyle(clang_format_text): + """Extract a key:value dictionary for proto formatting. + + Args: + clang_format_text: text from a .clang-format file. + + Returns: + key:value dictionary suitable for passing to clang-format --style. + """ + lang = None + format_dict = {} + for line in clang_format_text.split('\n'): + if lang is None or lang != 'Proto': + match = re.match('Language:\s+(\w+)', line) + if match: + lang = match.group(1) + continue + match = re.match('(\w+):\s+(\w+)', line) + if match: + key, value = match.groups() + format_dict[key] = value + else: + break + return str(format_dict) + + +# Ensure we are using the canonical clang-format proto style. +CLANG_FORMAT_STYLE = ExtractClangProtoStyle( + pathlib.Path(os.getenv('RUNFILES_DIR'), 'envoy/.clang-format').read_text()) + + def ClangFormat(contents): """Run proto-style oriented clang-format over given string. diff --git a/tools/type_whisperer/BUILD b/tools/type_whisperer/BUILD index 6e0e9cd02cc7a..4f586cb56e59a 100644 --- a/tools/type_whisperer/BUILD +++ b/tools/type_whisperer/BUILD @@ -1,6 +1,7 @@ licenses(["notice"]) # Apache 2 load("//bazel:envoy_build_system.bzl", "envoy_cc_library", "envoy_package", "envoy_proto_library") +load("//tools/type_whisperer:api_build_file.bzl", "api_build_file") load("//tools/type_whisperer:file_descriptor_set_text.bzl", "file_descriptor_set_text") load("//tools/type_whisperer:type_database.bzl", "type_database") load("//tools/type_whisperer:proto_cc_source.bzl", "proto_cc_source") @@ -69,7 +70,7 @@ type_database( file_descriptor_set_text( name = "all_protos_pb_text", - deps = ["@envoy_api_canonical//:protos"], + deps = ["@envoy_api_canonical//:all_protos"], ) proto_cc_source( @@ -104,3 +105,16 @@ envoy_proto_library( srcs = ["api_type_db.proto"], deps = ["//tools/type_whisperer:types"], ) + +py_binary( + name = "proto_build_targets_gen", + srcs = ["proto_build_targets_gen.py"], + deps = [ + ":api_type_db_proto_py_proto", + ], +) + +api_build_file( + name = "api_build_file", + typedb = "//tools/type_whisperer:api_type_db", +) diff --git a/tools/type_whisperer/api_build_file.bzl b/tools/type_whisperer/api_build_file.bzl new file mode 100644 index 0000000000000..17ab0027d2df7 --- /dev/null +++ b/tools/type_whisperer/api_build_file.bzl @@ -0,0 +1,30 @@ +def _api_build_file(ctx): + pb_text_set = depset() + type_db_file = ctx.attr.typedb.files.to_list()[0] + args = [type_db_file.path, ctx.outputs.build.path] + ctx.actions.run( + executable = ctx.executable._proto_build_targets_gen, + arguments = args, + inputs = [type_db_file], + outputs = [ctx.outputs.build], + mnemonic = "ApiBuildFile", + use_default_shell_env = True, + ) + +api_build_file = rule( + attrs = { + "typedb": attr.label( + doc = "Type database label.", + mandatory = True, + ), + "_proto_build_targets_gen": attr.label( + default = Label("//tools/type_whisperer:proto_build_targets_gen"), + executable = True, + cfg = "exec", + ), + }, + outputs = { + "build": "BUILD.%{name}", + }, + implementation = _api_build_file, +) diff --git a/tools/type_whisperer/proto_build_targets_gen.py b/tools/type_whisperer/proto_build_targets_gen.py new file mode 100644 index 0000000000000..22df422666ab8 --- /dev/null +++ b/tools/type_whisperer/proto_build_targets_gen.py @@ -0,0 +1,95 @@ +# Generate api/BUILD based on API type database. This contains target for v2, v3 +# and all API protos. + +import os +import string +import sys + +from tools.type_whisperer.api_type_db_pb2 import TypeDb + +from google.protobuf import text_format + +API_BUILD_FILE_TEMPLATE = string.Template( + """# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@rules_proto//proto:defs.bzl", "proto_library") + +licenses(["notice"]) # Apache 2 + +proto_library( + name = "v2_protos", + visibility = ["//visibility:public"], + deps = [ +$v2_deps + ], +) + +proto_library( + name = "v3_protos", + visibility = ["//visibility:public"], + deps = [ +$v3_deps + ], +) + +proto_library( + name = "all_protos", + visibility = ["//visibility:public"], + deps = [ + ":v2_protos", + ":v3_protos", + ], +) +""") + + +def LoadTypeDb(type_db_path): + type_db = TypeDb() + with open(type_db_path, 'r') as f: + text_format.Merge(f.read(), type_db) + return type_db + + +# Key sort function to achieve consistent results with buildifier. +def BuildOrderKey(key): + return key.replace(':', '!') + + +# Remove any packages that are definitely non-root, e.g. annotations. +def FilterPkgs(pkgs): + + def AllowedPkg(pkg): + return not pkg.startswith('envoy.annotations') + + return filter(AllowedPkg, pkgs) + + +def DepsFormat(pkgs): + return '\n'.join(' "//%s:pkg",' % p.replace('.', '/') + for p in sorted(FilterPkgs(pkgs), key=BuildOrderKey)) + + +if __name__ == '__main__': + type_db_path, output_path = sys.argv[1:] + type_db = LoadTypeDb(type_db_path) + # TODO(htuch): generalize to > 2 versions + v2_packages = set([]) + v3_packages = set([]) + # Phase 1, we use the upgraded packages as a means to figure out which + # packages are explicitly in v2 vs. v3 by virtue of some breaking change. + for name, desc in type_db.types.items(): + if desc.next_version_type_name: + v2_packages.add(desc.qualified_package) + v3_packages.add(type_db.types[desc.next_version_type_name].qualified_package) + # Phase 2, we collect the rest of the packages not already binned and consider + # them to be both v2 and v3. + for name, desc in type_db.types.items(): + pkg = desc.qualified_package + if pkg not in v2_packages and pkg not in v3_packages: + v2_packages.add(pkg) + v3_packages.add(pkg) + # Generate BUILD file. + build_file_contents = API_BUILD_FILE_TEMPLATE.substitute(v2_deps=DepsFormat(v2_packages), + v3_deps=DepsFormat(v3_packages)) + with open(output_path, 'w') as f: + f.write(build_file_contents)