api/docs: v3 API reference documentation.

.clang-format

@@ -12,4 +12,5 @@ Language: Proto
 ColumnLimit: 100
 SpacesInContainerLiterals: false
 AllowShortFunctionsOnASingleLine: false
+ReflowComments: false
 ...

BUILD

@@ -1,3 +1,6 @@
 licenses(["notice"])  # Apache 2
 
-exports_files(["VERSION"])
+exports_files([
+    "VERSION",
+    ".clang-format",
+])

api/BUILD

@@ -5,11 +5,10 @@ load("@rules_proto//proto:defs.bzl", "proto_library")
 licenses(["notice"])  # Apache 2
 
 proto_library(
-    name = "protos",
+    name = "v2_protos",
     visibility = ["//visibility:public"],
     deps = [
         "//envoy/admin/v2alpha:pkg",
-        "//envoy/admin/v3:pkg",
         "//envoy/api/v2:pkg",
         "//envoy/api/v2/auth:pkg",
         "//envoy/api/v2/cluster:pkg",
@@ -19,17 +18,12 @@ proto_library(
         "//envoy/api/v2/ratelimit:pkg",
         "//envoy/api/v2/route:pkg",
         "//envoy/config/accesslog/v2:pkg",
-        "//envoy/config/accesslog/v3:pkg",
         "//envoy/config/bootstrap/v2:pkg",
-        "//envoy/config/bootstrap/v3:pkg",
         "//envoy/config/cluster/aggregate/v2alpha:pkg",
         "//envoy/config/cluster/dynamic_forward_proxy/v2alpha:pkg",
         "//envoy/config/cluster/redis:pkg",
-        "//envoy/config/cluster/v3:pkg",
         "//envoy/config/common/dynamic_forward_proxy/v2alpha:pkg",
         "//envoy/config/common/tap/v2alpha:pkg",
-        "//envoy/config/core/v3:pkg",
-        "//envoy/config/endpoint/v3:pkg",
         "//envoy/config/filter/accesslog/v2:pkg",
         "//envoy/config/filter/dubbo/router/v2alpha1:pkg",
         "//envoy/config/filter/fault/v2:pkg",
@@ -84,37 +78,70 @@ proto_library(
         "//envoy/config/filter/thrift/router/v2alpha1:pkg",
         "//envoy/config/filter/udp/udp_proxy/v2alpha:pkg",
         "//envoy/config/grpc_credential/v2alpha:pkg",
-        "//envoy/config/grpc_credential/v3:pkg",
         "//envoy/config/health_checker/redis/v2:pkg",
         "//envoy/config/listener/v2:pkg",
-        "//envoy/config/listener/v3:pkg",
         "//envoy/config/metrics/v2:pkg",
-        "//envoy/config/metrics/v3:pkg",
         "//envoy/config/overload/v2alpha:pkg",
-        "//envoy/config/overload/v3:pkg",
         "//envoy/config/ratelimit/v2:pkg",
-        "//envoy/config/ratelimit/v3:pkg",
         "//envoy/config/rbac/v2:pkg",
-        "//envoy/config/rbac/v3:pkg",
         "//envoy/config/resource_monitor/fixed_heap/v2alpha:pkg",
         "//envoy/config/resource_monitor/injected_resource/v2alpha:pkg",
         "//envoy/config/retry/omit_canary_hosts/v2:pkg",
         "//envoy/config/retry/previous_hosts/v2:pkg",
         "//envoy/config/retry/previous_priorities:pkg",
-        "//envoy/config/route/v3:pkg",
-        "//envoy/config/tap/v3:pkg",
         "//envoy/config/trace/v2:pkg",
         "//envoy/config/trace/v2alpha:pkg",
-        "//envoy/config/trace/v3:pkg",
         "//envoy/config/transport_socket/alts/v2alpha:pkg",
         "//envoy/config/transport_socket/raw_buffer/v2:pkg",
         "//envoy/config/transport_socket/tap/v2alpha:pkg",
         "//envoy/data/accesslog/v2:pkg",
-        "//envoy/data/accesslog/v3:pkg",
         "//envoy/data/cluster/v2alpha:pkg",
         "//envoy/data/core/v2alpha:pkg",
-        "//envoy/data/core/v3:pkg",
         "//envoy/data/tap/v2alpha:pkg",
+        "//envoy/service/accesslog/v2:pkg",
+        "//envoy/service/auth/v2:pkg",
+        "//envoy/service/discovery/v2:pkg",
+        "//envoy/service/load_stats/v2:pkg",
+        "//envoy/service/metrics/v2:pkg",
+        "//envoy/service/ratelimit/v2:pkg",
+        "//envoy/service/tap/v2alpha:pkg",
+        "//envoy/service/trace/v2:pkg",
+        "//envoy/type:pkg",
+        "//envoy/type/matcher:pkg",
+        "//envoy/type/metadata/v2:pkg",
+        "//envoy/type/tracing/v2:pkg",
+    ],
+)
+
+proto_library(
+    name = "v3_protos",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//envoy/admin/v3:pkg",
+        "//envoy/config/accesslog/v3:pkg",
+        "//envoy/config/bootstrap/v3:pkg",
+        "//envoy/config/cluster/v3:pkg",
+        "//envoy/config/core/v3:pkg",
+        "//envoy/config/endpoint/v3:pkg",
+        "//envoy/config/filter/thrift/router/v2alpha1:pkg",
+        "//envoy/config/filter/udp/udp_proxy/v2alpha:pkg",
+        "//envoy/config/grpc_credential/v3:pkg",
+        "//envoy/config/health_checker/redis/v2:pkg",
+        "//envoy/config/listener/v3:pkg",
+        "//envoy/config/metrics/v3:pkg",
+        "//envoy/config/overload/v3:pkg",
+        "//envoy/config/ratelimit/v3:pkg",
+        "//envoy/config/rbac/v3:pkg",
+        "//envoy/config/resource_monitor/fixed_heap/v2alpha:pkg",
+        "//envoy/config/resource_monitor/injected_resource/v2alpha:pkg",
+        "//envoy/config/retry/omit_canary_hosts/v2:pkg",
+        "//envoy/config/retry/previous_hosts/v2:pkg",
+        "//envoy/config/route/v3:pkg",
+        "//envoy/config/tap/v3:pkg",
+        "//envoy/config/trace/v3:pkg",
+        "//envoy/data/accesslog/v3:pkg",
+        "//envoy/data/cluster/v3:pkg",
+        "//envoy/data/core/v3:pkg",
         "//envoy/data/tap/v3:pkg",
         "//envoy/extensions/access_loggers/file/v3:pkg",
         "//envoy/extensions/access_loggers/grpc/v3:pkg",
@@ -179,34 +206,33 @@ proto_library(
         "//envoy/extensions/transport_sockets/raw_buffer/v3:pkg",
         "//envoy/extensions/transport_sockets/tap/v3:pkg",
         "//envoy/extensions/transport_sockets/tls/v3:pkg",
-        "//envoy/service/accesslog/v2:pkg",
         "//envoy/service/accesslog/v3:pkg",
-        "//envoy/service/auth/v2:pkg",
         "//envoy/service/auth/v3:pkg",
         "//envoy/service/cluster/v3:pkg",
-        "//envoy/service/discovery/v2:pkg",
         "//envoy/service/discovery/v3:pkg",
         "//envoy/service/endpoint/v3:pkg",
         "//envoy/service/health/v3:pkg",
         "//envoy/service/listener/v3:pkg",
-        "//envoy/service/load_stats/v2:pkg",
         "//envoy/service/load_stats/v3:pkg",
-        "//envoy/service/metrics/v2:pkg",
         "//envoy/service/metrics/v3:pkg",
-        "//envoy/service/ratelimit/v2:pkg",
         "//envoy/service/ratelimit/v3:pkg",
         "//envoy/service/route/v3:pkg",
         "//envoy/service/runtime/v3:pkg",
         "//envoy/service/secret/v3:pkg",
-        "//envoy/service/tap/v2alpha:pkg",
         "//envoy/service/tap/v3:pkg",
-        "//envoy/service/trace/v2:pkg",
         "//envoy/service/trace/v3:pkg",
-        "//envoy/type:pkg",
-        "//envoy/type/matcher:pkg",
         "//envoy/type/matcher/v3:pkg",
-        "//envoy/type/metadata/v2:pkg",
-        "//envoy/type/tracing/v2:pkg",
+        "//envoy/type/metadata/v3:pkg",
+        "//envoy/type/tracing/v3:pkg",
         "//envoy/type/v3:pkg",
     ],
 )
+
+proto_library(
+    name = "all_protos",
+    visibility = ["//visibility:public"],
+    deps = [
+        ":v2_protos",
+        ":v3_protos",
+    ],
+)

api/envoy/admin/v3/config_dump.proto

@@ -91,9 +91,9 @@ message ListenersConfigDump {
         "envoy.admin.v2alpha.ListenersConfigDump.DynamicListenerState";
 
     // This is the per-resource version information. This version is currently taken from the
-    // :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.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
-  // <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.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
-  // <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>`
-    // field at the time that the route configuration was loaded.
+    // :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.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 <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>`
-    // field at the time that the scoped routes configuration was loaded.
+    // :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>` field at the time that
+    // the scoped routes configuration was loaded.
     string version_info = 2;
 
     // The scoped route configurations.

api/envoy/api/v2/auth/cert.proto

@@ -192,8 +192,8 @@ message CertificateValidationContext {
   // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_spki>`,
   // :ref:`verify_certificate_hash
   // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>`, or
-  // :ref:`verify_subject_alt_name
-  // <envoy_api_field_auth.CertificateValidationContext.verify_subject_alt_name>`) is also
+  // :ref:`match_subject_alt_names
+  // <envoy_api_field_auth.CertificateValidationContext.match_subject_alt_names>`) is also
   // specified.
   //
   // It can optionally contain certificate revocation lists, in which case Envoy will verify

api/envoy/api/v2/cluster.proto

@@ -558,15 +558,12 @@ message Cluster {
   // :ref:`STATIC<envoy_api_enum_value_Cluster.DiscoveryType.STATIC>`,
   // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`
   // or :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.LOGICAL_DNS>` clusters.
-  // This field supersedes :ref:`hosts<envoy_api_field_Cluster.hosts>` field.
-  // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log<deprecated>`
-  // 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<envoy_api_msg_ClusterLoadAssignment>`.
-  //   Setting this overrides :ref:`hosts<envoy_api_field_Cluster.hosts>` values.
   //
   ClusterLoadAssignment load_assignment = 33;
 

api/envoy/api/v2/core/base.proto

@@ -134,7 +134,8 @@ message Node {
   // Defines the local service cluster name where Envoy is running. Though
   // optional, it should be set if any of the following features are used:
   // :ref:`statsd <arch_overview_statistics>`, :ref:`health check cluster
-  // verification <envoy_api_field_core.HealthCheck.HttpHealthCheck.service_name>`,
+  // verification
+  // <envoy_api_field_core.HealthCheck.HttpHealthCheck.service_name_matcher>`,
   // :ref:`runtime override directory <envoy_api_msg_config.bootstrap.v2.Runtime>`,
   // :ref:`user agent addition
   // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.add_user_agent>`,

api/envoy/api/v2/core/health_check.proto

@@ -116,10 +116,7 @@ message HealthCheck {
     // range are required. Only statuses in the range [100, 600) are allowed.
     repeated type.Int64Range expected_statuses = 9;
 
-    // Use specified application protocol for health checks. This is to replace
-    // :ref:`use_http2
-    // <envoy_api_field_core.HealthCheck.HttpHealthCheck.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

api/envoy/api/v2/route/route_components.proto

@@ -508,7 +508,7 @@ message CorsPolicy {
     // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS
     // filter will be enabled for 100% of the requests.
     //
-    // If :ref:`runtime_key <envoy_api_field_core.runtimefractionalpercent.runtime_key>` is
+    // If :ref:`runtime_key <envoy_api_field_core.RuntimeFractionalPercent.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 <envoy_api_field_core.runtimefractionalpercent.runtime_key>` is specified,
+  // If :ref:`runtime_key <envoy_api_field_core.RuntimeFractionalPercent.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
-    //   <envoy_api_field_route.RouteAction.RequestMirrorPolicy.runtime_fraction>` field instead.
+    //   <envoy_api_field_route.RouteAction.RequestMirrorPolicy.runtime_fraction>`
+    //   field instead. Mirroring occurs if both this and
+    //   <envoy_api_field_route.RouteAction.RequestMirrorPolicy.runtime_fraction>`
+    //   are not set.
     string runtime_key = 2 [deprecated = true, (envoy.annotations.disallowed_by_default) = true];
 
-    // If both :ref:`runtime_key
-    // <envoy_api_field_route.RouteAction.RequestMirrorPolicy.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
-  // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.tracing.custom_tags>`
+  // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing.custom_tags>`
   // 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.

api/envoy/config/bootstrap/v2/bootstrap.proto

@@ -26,9 +26,9 @@ option java_multiple_files = true;
 // [#protodoc-title: Bootstrap]
 // This proto is supplied via the :option:`-c` CLI flag and acts as the root
 // of the Envoy v2 configuration. See the :ref:`v2 configuration overview
-// <config_overview_v2_bootstrap>` for more detail.
+// <config_overview_bootstrap>` for more detail.
 
-// Bootstrap :ref:`configuration overview <config_overview_v2_bootstrap>`.
+// Bootstrap :ref:`configuration overview <config_overview_bootstrap>`.
 // [#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 <config_overview_v2_ads>` source may be optionally
+    // A single :ref:`ADS <config_overview_ads>` source may be optionally
     // specified. This must have :ref:`api_type
     // <envoy_api_field_core.ApiConfigSource.api_type>` :ref:`GRPC
     // <envoy_api_enum_value_core.ApiConfigSource.ApiType.GRPC>`. Only

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -28,9 +28,9 @@ option java_multiple_files = true;
 // [#protodoc-title: Bootstrap]
 // This proto is supplied via the :option:`-c` CLI flag and acts as the root
 // of the Envoy v2 configuration. See the :ref:`v2 configuration overview
-// <config_overview_v2_bootstrap>` for more detail.
+// <config_overview_bootstrap>` for more detail.
 
-// Bootstrap :ref:`configuration overview <config_overview_v2_bootstrap>`.
+// Bootstrap :ref:`configuration overview <config_overview_bootstrap>`.
 // [#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 <config_overview_v2_ads>` source may be optionally
+    // A single :ref:`ADS <config_overview_ads>` source may be optionally
     // specified. This must have :ref:`api_type
     // <envoy_api_field_config.core.v3.ApiConfigSource.api_type>` :ref:`GRPC
     // <envoy_api_enum_value_config.core.v3.ApiConfigSource.ApiType.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 <envoy_api_field_config.cluster.v3.Cluster.dns_resolvers>` and
-  // :ref:`use_tcp_for_dns_lookups
-  // <envoy_api_field_config.cluster.v3.Cluster.use_tcp_for_dns_lookups>` are specified.
+  // :ref:`use_tcp_for_dns_lookups <envoy_api_field_config.cluster.v3.Cluster.use_tcp_for_dns_lookups>` are
+  // specified.
   bool use_tcp_for_dns_lookups = 20;
 }