Skip to content

Commit

Permalink
api/docs: v3 API reference documentation. (envoyproxy#9719)
Browse files Browse the repository at this point in the history 
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 envoyproxy#8087

Signed-off-by: Harvey Tuch <[email protected]>
  • Loading branch information
@htuch
htuch authored Jan 20, 2020
1 parent a2e0f78 commit ac88316
Show file tree
Hide file tree
Showing 169 changed files with 2,136 additions and 758 deletions.
1 change: 1 addition & 0 deletions .clang-format
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,5 @@ Language: Proto
ColumnLimit: 100
SpacesInContainerLiterals: false
AllowShortFunctionsOnASingleLine: false
ReflowComments: false
...
5 changes: 4 additions & 1 deletion BUILD
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
licenses(["notice"]) # Apache 2

exports_files(["VERSION"])
exports_files([
"VERSION",
".clang-format",
])
86 changes: 56 additions & 30 deletions api/BUILD
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
],
)
32 changes: 16 additions & 16 deletions api/envoy/admin/v3/config_dump.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions api/envoy/api/v2/auth/cert.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 1 addition & 4 deletions api/envoy/api/v2/cluster.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
3 changes: 2 additions & 1 deletion api/envoy/api/v2/core/base.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>`,
Expand Down
5 changes: 1 addition & 4 deletions api/envoy/api/v2/core/health_check.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 8 additions & 7 deletions api/envoy/api/v2/route/route_components.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand All @@ -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;
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions api/envoy/config/bootstrap/v2/bootstrap.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions api/envoy/config/bootstrap/v3/bootstrap.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
}

Expand Down
Loading

0 comments on commit ac88316

Please sign in to comment.