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