diff --git a/api/envoy/config/accesslog/v3/accesslog.proto b/api/envoy/config/accesslog/v3/accesslog.proto index b709e8919944b..6d494be4aea6d 100644 --- a/api/envoy/config/accesslog/v3/accesslog.proto +++ b/api/envoy/config/accesslog/v3/accesslog.proto @@ -49,6 +49,7 @@ message AccessLog { // ` // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig // ` + // [#extension-category: envoy.access_loggers] oneof config_type { google.protobuf.Any typed_config = 4; } diff --git a/api/envoy/config/accesslog/v4alpha/accesslog.proto b/api/envoy/config/accesslog/v4alpha/accesslog.proto index b812d77e446aa..62bc8af6913bb 100644 --- a/api/envoy/config/accesslog/v4alpha/accesslog.proto +++ b/api/envoy/config/accesslog/v4alpha/accesslog.proto @@ -49,6 +49,7 @@ message AccessLog { // ` // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig // ` + // [#extension-category: envoy.access_loggers] oneof config_type { google.protobuf.Any typed_config = 4; } diff --git a/api/envoy/config/bootstrap/v3/bootstrap.proto b/api/envoy/config/bootstrap/v3/bootstrap.proto index 476d841bf2516..7b2ab471c47bf 100644 --- a/api/envoy/config/bootstrap/v3/bootstrap.proto +++ b/api/envoy/config/bootstrap/v3/bootstrap.proto @@ -190,6 +190,7 @@ message Bootstrap { // Optional watchdogs configuration. // This is used for specifying different watchdogs for the different subsystems. + // [#extension-category: envoy.guarddog_actions] Watchdogs watchdogs = 27; // Configuration for an external tracing provider. @@ -249,6 +250,7 @@ message Bootstrap { // Specifies optional bootstrap extensions to be instantiated at startup time. // Each item contains extension specific configuration. + // [#extension-category: envoy.bootstrap] repeated core.v3.TypedExtensionConfig bootstrap_extensions = 21; // Specifies optional extensions instantiated at startup time and diff --git a/api/envoy/config/bootstrap/v4alpha/bootstrap.proto b/api/envoy/config/bootstrap/v4alpha/bootstrap.proto index 9d9552e425c20..0b055dac26810 100644 --- a/api/envoy/config/bootstrap/v4alpha/bootstrap.proto +++ b/api/envoy/config/bootstrap/v4alpha/bootstrap.proto @@ -180,6 +180,7 @@ message Bootstrap { // Optional watchdogs configuration. // This is used for specifying different watchdogs for the different subsystems. + // [#extension-category: envoy.guarddog_actions] Watchdogs watchdogs = 27; // Configuration for the runtime configuration provider. If not @@ -232,6 +233,7 @@ message Bootstrap { // Specifies optional bootstrap extensions to be instantiated at startup time. // Each item contains extension specific configuration. + // [#extension-category: envoy.bootstrap] repeated core.v4alpha.TypedExtensionConfig bootstrap_extensions = 21; // Specifies optional extensions instantiated at startup time and diff --git a/api/envoy/config/cluster/v3/cluster.proto b/api/envoy/config/cluster/v3/cluster.proto index 145a8b6951971..6b89257cb23ae 100644 --- a/api/envoy/config/cluster/v3/cluster.proto +++ b/api/envoy/config/cluster/v3/cluster.proto @@ -158,6 +158,7 @@ message Cluster { google.protobuf.Struct match = 2; // The configuration of the transport socket. + // [#extension-category: envoy.transport_sockets.upstream] core.v3.TransportSocket transport_socket = 3; } @@ -171,6 +172,7 @@ message Cluster { // Cluster specific configuration which depends on the cluster being instantiated. // See the supported cluster for further documentation. + // [#extension-category: envoy.clusters] google.protobuf.Any typed_config = 2; } @@ -1004,6 +1006,7 @@ message Cluster { // If users desire custom connection pool or upstream behavior, for example terminating // CONNECT only if a custom filter indicates it is appropriate, the custom factories // can be registered and configured here. + // [#extension-category: envoy.upstreams] core.v3.TypedExtensionConfig upstream_config = 48; // Configuration to track optional cluster stats. diff --git a/api/envoy/config/cluster/v4alpha/cluster.proto b/api/envoy/config/cluster/v4alpha/cluster.proto index 4e6015b815958..062123fc42060 100644 --- a/api/envoy/config/cluster/v4alpha/cluster.proto +++ b/api/envoy/config/cluster/v4alpha/cluster.proto @@ -160,6 +160,7 @@ message Cluster { google.protobuf.Struct match = 2; // The configuration of the transport socket. + // [#extension-category: envoy.transport_sockets.upstream] core.v4alpha.TransportSocket transport_socket = 3; } @@ -173,6 +174,7 @@ message Cluster { // Cluster specific configuration which depends on the cluster being instantiated. // See the supported cluster for further documentation. + // [#extension-category: envoy.clusters] google.protobuf.Any typed_config = 2; } @@ -945,6 +947,7 @@ message Cluster { // If users desire custom connection pool or upstream behavior, for example terminating // CONNECT only if a custom filter indicates it is appropriate, the custom factories // can be registered and configured here. + // [#extension-category: envoy.upstreams] core.v4alpha.TypedExtensionConfig upstream_config = 48; // Configuration to track optional cluster stats. diff --git a/api/envoy/config/core/v3/grpc_service.proto b/api/envoy/config/core/v3/grpc_service.proto index e3730d017410b..103c8b90f6349 100644 --- a/api/envoy/config/core/v3/grpc_service.proto +++ b/api/envoy/config/core/v3/grpc_service.proto @@ -124,6 +124,7 @@ message GrpcService { string name = 1; + // [#extension-category: envoy.grpc_credentials] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/core/v3/health_check.proto b/api/envoy/config/core/v3/health_check.proto index e4ad7429e0d6a..27710830536c8 100644 --- a/api/envoy/config/core/v3/health_check.proto +++ b/api/envoy/config/core/v3/health_check.proto @@ -189,6 +189,7 @@ message HealthCheck { // A custom health checker specific configuration which depends on the custom health checker // being instantiated. See :api:`envoy/config/health_checker` for reference. + // [#extension-category: envoy.health_checkers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/core/v4alpha/grpc_service.proto b/api/envoy/config/core/v4alpha/grpc_service.proto index 9ea35b4564709..c7c284f1bdcd8 100644 --- a/api/envoy/config/core/v4alpha/grpc_service.proto +++ b/api/envoy/config/core/v4alpha/grpc_service.proto @@ -124,6 +124,7 @@ message GrpcService { string name = 1; + // [#extension-category: envoy.grpc_credentials] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/core/v4alpha/health_check.proto b/api/envoy/config/core/v4alpha/health_check.proto index 8d870680a466d..ddc7d65e00075 100644 --- a/api/envoy/config/core/v4alpha/health_check.proto +++ b/api/envoy/config/core/v4alpha/health_check.proto @@ -189,6 +189,7 @@ message HealthCheck { // A custom health checker specific configuration which depends on the custom health checker // being instantiated. See :api:`envoy/config/health_checker` for reference. + // [#extension-category: envoy.health_checkers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/listener/v3/listener_components.proto b/api/envoy/config/listener/v3/listener_components.proto index 4ee2f1b53fde5..952056ddce0e8 100644 --- a/api/envoy/config/listener/v3/listener_components.proto +++ b/api/envoy/config/listener/v3/listener_components.proto @@ -35,6 +35,7 @@ message Filter { // :ref:`supported filter `. string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.filters.network] oneof config_type { // Filter specific configuration which depends on the filter being // instantiated. See the supported filters for further documentation. @@ -331,10 +332,12 @@ message ListenerFilter { // The name of the filter to instantiate. The name must match a // :ref:`supported filter `. + // [#extension-category: envoy.transport_sockets.downstream] string name = 1 [(validate.rules).string = {min_len: 1}]; // Filter specific configuration which depends on the filter being instantiated. // See the supported filters for further documentation. + // [#extension-category: envoy.filters.listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/listener/v3/udp_listener_config.proto b/api/envoy/config/listener/v3/udp_listener_config.proto index fe39be9b35258..058bca55acfdb 100644 --- a/api/envoy/config/listener/v3/udp_listener_config.proto +++ b/api/envoy/config/listener/v3/udp_listener_config.proto @@ -30,6 +30,7 @@ message UdpListenerConfig { // Used to create a specific listener factory. To some factory, e.g. // "raw_udp_listener", config is not needed. + // [#extension-category: envoy.filters.udp_listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/listener/v4alpha/listener_components.proto b/api/envoy/config/listener/v4alpha/listener_components.proto index 04d8ef644300a..682334b3fdb5b 100644 --- a/api/envoy/config/listener/v4alpha/listener_components.proto +++ b/api/envoy/config/listener/v4alpha/listener_components.proto @@ -35,6 +35,7 @@ message Filter { // :ref:`supported filter `. string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.filters.network] oneof config_type { // Filter specific configuration which depends on the filter being // instantiated. See the supported filters for further documentation. @@ -323,10 +324,12 @@ message ListenerFilter { // The name of the filter to instantiate. The name must match a // :ref:`supported filter `. + // [#extension-category: envoy.transport_sockets.downstream] string name = 1 [(validate.rules).string = {min_len: 1}]; // Filter specific configuration which depends on the filter being instantiated. // See the supported filters for further documentation. + // [#extension-category: envoy.filters.listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/listener/v4alpha/udp_listener_config.proto b/api/envoy/config/listener/v4alpha/udp_listener_config.proto index 96eebee2d237e..9d6a3917a1526 100644 --- a/api/envoy/config/listener/v4alpha/udp_listener_config.proto +++ b/api/envoy/config/listener/v4alpha/udp_listener_config.proto @@ -30,6 +30,7 @@ message UdpListenerConfig { // Used to create a specific listener factory. To some factory, e.g. // "raw_udp_listener", config is not needed. + // [#extension-category: envoy.filters.udp_listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/metrics/v3/stats.proto b/api/envoy/config/metrics/v3/stats.proto index 16335b2a1c13d..307805e65ad8e 100644 --- a/api/envoy/config/metrics/v3/stats.proto +++ b/api/envoy/config/metrics/v3/stats.proto @@ -41,6 +41,7 @@ message StatsSink { // Stats sink specific configuration which depends on the sink being instantiated. See // :ref:`StatsdSink ` for an example. + // [#extension-category: envoy.stats_sinks] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/metrics/v4alpha/stats.proto b/api/envoy/config/metrics/v4alpha/stats.proto index 02d7c18db5ce6..3a351cdd094c6 100644 --- a/api/envoy/config/metrics/v4alpha/stats.proto +++ b/api/envoy/config/metrics/v4alpha/stats.proto @@ -41,6 +41,7 @@ message StatsSink { // Stats sink specific configuration which depends on the sink being instantiated. See // :ref:`StatsdSink ` for an example. + // [#extension-category: envoy.stats_sinks] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/overload/v3/overload.proto b/api/envoy/config/overload/v3/overload.proto index 7c51d493b4918..8817fe0c291b4 100644 --- a/api/envoy/config/overload/v3/overload.proto +++ b/api/envoy/config/overload/v3/overload.proto @@ -41,6 +41,7 @@ message ResourceMonitor { string name = 1 [(validate.rules).string = {min_len: 1}]; // Configuration for the resource monitor being instantiated. + // [#extension-category: envoy.resource_monitors] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/route/v3/route_components.proto b/api/envoy/config/route/v3/route_components.proto index 8fe650ceb9864..9c83bee9ca95f 100644 --- a/api/envoy/config/route/v3/route_components.proto +++ b/api/envoy/config/route/v3/route_components.proto @@ -1128,6 +1128,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_priorities] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1143,6 +1144,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_host_predicates] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1756,6 +1758,7 @@ message RateLimit { MetaData metadata = 8; // Rate limit descriptor extension. See the rate limit descriptor extensions documentation. + // [#extension-category: envoy.rate_limit_descriptors] core.v3.TypedExtensionConfig extension = 9; } } @@ -1947,6 +1950,7 @@ message InternalRedirectPolicy { // Specifies a list of predicates that are queried when an upstream response is deemed // to trigger an internal redirect by all other criteria. Any predicate in the list can reject // the redirect, causing the response to be proxied to downstream. + // [#extension-category: envoy.internal_redirect_predicates] repeated core.v3.TypedExtensionConfig predicates = 3; // Allow internal redirect to follow a target URI with a different scheme than the value of diff --git a/api/envoy/config/route/v4alpha/route_components.proto b/api/envoy/config/route/v4alpha/route_components.proto index f91aa7d16e4b3..034820fcdc63f 100644 --- a/api/envoy/config/route/v4alpha/route_components.proto +++ b/api/envoy/config/route/v4alpha/route_components.proto @@ -1070,6 +1070,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_priorities] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1085,6 +1086,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_host_predicates] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1708,6 +1710,7 @@ message RateLimit { MetaData metadata = 8; // Rate limit descriptor extension. See the rate limit descriptor extensions documentation. + // [#extension-category: envoy.rate_limit_descriptors] core.v4alpha.TypedExtensionConfig extension = 9; } } @@ -1910,6 +1913,7 @@ message InternalRedirectPolicy { // Specifies a list of predicates that are queried when an upstream response is deemed // to trigger an internal redirect by all other criteria. Any predicate in the list can reject // the redirect, causing the response to be proxied to downstream. + // [#extension-category: envoy.internal_redirect_predicates] repeated core.v4alpha.TypedExtensionConfig predicates = 3; // Allow internal redirect to follow a target URI with a different scheme than the value of diff --git a/api/envoy/config/trace/v3/http_tracer.proto b/api/envoy/config/trace/v3/http_tracer.proto index 7146687b831db..d0ba3ba6e4fdb 100644 --- a/api/envoy/config/trace/v3/http_tracer.proto +++ b/api/envoy/config/trace/v3/http_tracer.proto @@ -62,6 +62,7 @@ message Tracing { // - :ref:`DatadogConfig ` // - :ref:`OpenCensusConfig ` // - :ref:`AWS X-Ray ` + // [#extension-category: envoy.tracers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/config/trace/v3/xray.proto b/api/envoy/config/trace/v3/xray.proto index a904a10892360..208170b60c3f7 100644 --- a/api/envoy/config/trace/v3/xray.proto +++ b/api/envoy/config/trace/v3/xray.proto @@ -21,6 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: AWS X-Ray Tracer Configuration] // Configuration for AWS X-Ray tracer +// [#extension: envoy.tracers.xray] message XRayConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2alpha.XRayConfig"; diff --git a/api/envoy/config/trace/v4alpha/http_tracer.proto b/api/envoy/config/trace/v4alpha/http_tracer.proto index 2a7d3134312ba..4b8c681688425 100644 --- a/api/envoy/config/trace/v4alpha/http_tracer.proto +++ b/api/envoy/config/trace/v4alpha/http_tracer.proto @@ -62,6 +62,7 @@ message Tracing { // - :ref:`DatadogConfig ` // - :ref:`OpenCensusConfig ` // - :ref:`AWS X-Ray ` + // [#extension-category: envoy.tracers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/api/envoy/extensions/filters/http/cache/v3alpha/cache.proto b/api/envoy/extensions/filters/http/cache/v3alpha/cache.proto index 9260abe94a96c..9e140a38a902e 100644 --- a/api/envoy/extensions/filters/http/cache/v3alpha/cache.proto +++ b/api/envoy/extensions/filters/http/cache/v3alpha/cache.proto @@ -18,8 +18,8 @@ option (udpa.annotations.file_status).work_in_progress = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: HTTP Cache Filter] -// [#extension: envoy.filters.http.cache] +// [#extension: envoy.filters.http.cache.simple_http_cache] message CacheConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.cache.v2alpha.CacheConfig"; diff --git a/api/envoy/extensions/filters/http/cache/v4alpha/cache.proto b/api/envoy/extensions/filters/http/cache/v4alpha/cache.proto index ad9bb4c639a4d..283e8f53aebb2 100644 --- a/api/envoy/extensions/filters/http/cache/v4alpha/cache.proto +++ b/api/envoy/extensions/filters/http/cache/v4alpha/cache.proto @@ -18,8 +18,8 @@ option (udpa.annotations.file_status).work_in_progress = true; option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE; // [#protodoc-title: HTTP Cache Filter] -// [#extension: envoy.filters.http.cache] +// [#extension: envoy.filters.http.cache.simple_http_cache] message CacheConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.filters.http.cache.v3alpha.CacheConfig"; diff --git a/api/envoy/extensions/filters/http/compressor/v3/compressor.proto b/api/envoy/extensions/filters/http/compressor/v3/compressor.proto index 766560d9b5864..ed347cc439eb7 100644 --- a/api/envoy/extensions/filters/http/compressor/v3/compressor.proto +++ b/api/envoy/extensions/filters/http/compressor/v3/compressor.proto @@ -96,6 +96,7 @@ message Compressor { // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. // This field is ignored if used in the context of the gzip http-filter, but is mandatory otherwise. + // [#extension-category: envoy.compression.compressor] config.core.v3.TypedExtensionConfig compressor_library = 6; // Configuration for request compression. Compression is disabled by default if left empty. diff --git a/api/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto b/api/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto index 419c27da2efb1..d379bf48ce699 100644 --- a/api/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto +++ b/api/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto @@ -83,6 +83,7 @@ message Compressor { // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. // This field is ignored if used in the context of the gzip http-filter, but is mandatory otherwise. + // [#extension-category: envoy.compression.compressor] config.core.v4alpha.TypedExtensionConfig compressor_library = 6; // Configuration for request compression. Compression is disabled by default if left empty. diff --git a/api/envoy/extensions/filters/http/decompressor/v3/decompressor.proto b/api/envoy/extensions/filters/http/decompressor/v3/decompressor.proto index 058172fbaf64f..54d5f23bc449e 100644 --- a/api/envoy/extensions/filters/http/decompressor/v3/decompressor.proto +++ b/api/envoy/extensions/filters/http/decompressor/v3/decompressor.proto @@ -43,6 +43,7 @@ message Decompressor { // A decompressor library to use for both request and response decompression. Currently only // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. + // [#extension-category: envoy.compression.decompressor] config.core.v3.TypedExtensionConfig decompressor_library = 1 [(validate.rules).message = {required: true}]; diff --git a/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index 877569ee470e0..8c6e430e178a0 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -268,6 +268,7 @@ message HttpConnectionManager { // A list of individual HTTP filters that make up the filter chain for // requests made to the connection manager. :ref:`Order matters ` // as the filters are processed sequentially as request events happen. + // [#extension-category: envoy.filters.http] repeated HttpFilter http_filters = 5; // Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent` diff --git a/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto b/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto index fe245ce2fce87..7d4198fbf681e 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto +++ b/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto @@ -267,6 +267,7 @@ message HttpConnectionManager { // A list of individual HTTP filters that make up the filter chain for // requests made to the connection manager. :ref:`Order matters ` // as the filters are processed sequentially as request events happen. + // [#extension-category: envoy.filters.http] repeated HttpFilter http_filters = 5; // Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent` diff --git a/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto b/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto index 11d87e986fd59..659ee14604401 100644 --- a/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto +++ b/api/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto @@ -80,6 +80,7 @@ message ThriftProxy { // Thrift proxy. Order matters as the filters are processed sequentially. For backwards // compatibility, if no thrift_filters are specified, a default Thrift router filter // (`envoy.filters.thrift.router`) is used. + // [#extension-category: envoy.thrift_proxy.filters] repeated ThriftFilter thrift_filters = 5; // If set to true, Envoy will try to skip decode data after metadata in the Thrift message. diff --git a/api/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto b/api/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto index 05f8c54f6c63b..1834202272362 100644 --- a/api/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto +++ b/api/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto @@ -80,6 +80,7 @@ message ThriftProxy { // Thrift proxy. Order matters as the filters are processed sequentially. For backwards // compatibility, if no thrift_filters are specified, a default Thrift router filter // (`envoy.filters.thrift.router`) is used. + // [#extension-category: envoy.thrift_proxy.filters] repeated ThriftFilter thrift_filters = 5; // If set to true, Envoy will try to skip decode data after metadata in the Thrift message. diff --git a/api/envoy/extensions/tracers/xray/v4alpha/xray.proto b/api/envoy/extensions/tracers/xray/v4alpha/xray.proto index c21ce9a7cf828..649f294b4273b 100644 --- a/api/envoy/extensions/tracers/xray/v4alpha/xray.proto +++ b/api/envoy/extensions/tracers/xray/v4alpha/xray.proto @@ -19,6 +19,7 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // [#protodoc-title: AWS X-Ray Tracer Configuration] // Configuration for AWS X-Ray tracer +// [#extension: envoy.tracers.xray] message XRayConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v3.XRayConfig"; diff --git a/api/envoy/extensions/wasm/v3/wasm.proto b/api/envoy/extensions/wasm/v3/wasm.proto index 12cc06739ddd1..dc2844d24748d 100644 --- a/api/envoy/extensions/wasm/v3/wasm.proto +++ b/api/envoy/extensions/wasm/v3/wasm.proto @@ -81,6 +81,7 @@ message VmConfig { // (proxy_on_start). `google.protobuf.Struct` is serialized as JSON before // passing it to the plugin. `google.protobuf.BytesValue` and // `google.protobuf.StringValue` are passed directly without the wrapper. + // [#extension-category: envoy.wasm.runtime] google.protobuf.Any configuration = 4; // Allow the wasm file to include pre-compiled code on VMs which support it. diff --git a/bazel/envoy_library.bzl b/bazel/envoy_library.bzl index d052c481ace5c..0131f3c132c75 100644 --- a/bazel/envoy_library.bzl +++ b/bazel/envoy_library.bzl @@ -77,14 +77,12 @@ EXTENSION_CATEGORIES = [ "envoy.filters.listener", "envoy.filters.network", "envoy.filters.udp_listener", - "envoy.formatter", "envoy.grpc_credentials", "envoy.guarddog_actions", "envoy.health_checkers", "envoy.internal_redirect_predicates", "envoy.io_socket", "envoy.rate_limit_descriptors", - "envoy.resolvers", "envoy.resource_monitors", "envoy.retry_host_predicates", "envoy.retry_priorities", diff --git a/docs/generate_extension_db.py b/docs/generate_extension_db.py index f1cf8d8cd0d90..19b87f3fa7224 100755 --- a/docs/generate_extension_db.py +++ b/docs/generate_extension_db.py @@ -3,6 +3,7 @@ # Generate an extension database, a JSON file mapping from qualified well known # extension name to metadata derived from the envoy_cc_extension target. +import ast import json import os import pathlib @@ -53,18 +54,25 @@ def GetExtensionMetadata(target): if not BUILDOZER_PATH: raise ExtensionDbError('Buildozer not found!') r = subprocess.run( - [BUILDOZER_PATH, '-stdout', 'print security_posture status undocumented', target], + [BUILDOZER_PATH, '-stdout', 'print security_posture status undocumented category', target], stdout=subprocess.PIPE, stderr=subprocess.PIPE) - security_posture, status, undocumented = r.stdout.decode('utf-8').strip().split(' ') + rout = r.stdout.decode('utf-8').strip().split(' ') + security_posture, status, undocumented = rout[:3] + categories = ' '.join(rout[3:]) if IsMissing(security_posture): raise ExtensionDbError( 'Missing security posture for %s. Please make sure the target is an envoy_cc_extension and security_posture is set' % target) + # evaluate tuples/lists + # wrap strings in a list + categories = (ast.literal_eval(categories) if + ('[' in categories or '(' in categories) else [categories]) return { 'security_posture': security_posture, 'undocumented': False if IsMissing(undocumented) else bool(undocumented), 'status': 'stable' if IsMissing(status) else status, + 'categories': categories, } diff --git a/generated_api_shadow/BUILD b/generated_api_shadow/BUILD index e2e5b3bfeb772..046fac3d012de 100644 --- a/generated_api_shadow/BUILD +++ b/generated_api_shadow/BUILD @@ -145,7 +145,6 @@ proto_library( "//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_hosts/v3:pkg", "//envoy/config/route/v3:pkg", "//envoy/config/tap/v3:pkg", "//envoy/config/trace/v3:pkg", diff --git a/generated_api_shadow/envoy/config/accesslog/v3/accesslog.proto b/generated_api_shadow/envoy/config/accesslog/v3/accesslog.proto index 3d8f3bb8e16e2..b266ea21b9886 100644 --- a/generated_api_shadow/envoy/config/accesslog/v3/accesslog.proto +++ b/generated_api_shadow/envoy/config/accesslog/v3/accesslog.proto @@ -46,6 +46,7 @@ message AccessLog { // ` // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig // ` + // [#extension-category: envoy.access_loggers] oneof config_type { google.protobuf.Any typed_config = 4; diff --git a/generated_api_shadow/envoy/config/accesslog/v4alpha/accesslog.proto b/generated_api_shadow/envoy/config/accesslog/v4alpha/accesslog.proto index b812d77e446aa..62bc8af6913bb 100644 --- a/generated_api_shadow/envoy/config/accesslog/v4alpha/accesslog.proto +++ b/generated_api_shadow/envoy/config/accesslog/v4alpha/accesslog.proto @@ -49,6 +49,7 @@ message AccessLog { // ` // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig // ` + // [#extension-category: envoy.access_loggers] oneof config_type { google.protobuf.Any typed_config = 4; } diff --git a/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto b/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto index 9ac8927e19840..30b03dae8a3be 100644 --- a/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto +++ b/generated_api_shadow/envoy/config/bootstrap/v3/bootstrap.proto @@ -189,6 +189,7 @@ message Bootstrap { // Optional watchdogs configuration. // This is used for specifying different watchdogs for the different subsystems. + // [#extension-category: envoy.guarddog_actions] Watchdogs watchdogs = 27; // Configuration for an external tracing provider. @@ -248,6 +249,7 @@ message Bootstrap { // Specifies optional bootstrap extensions to be instantiated at startup time. // Each item contains extension specific configuration. + // [#extension-category: envoy.bootstrap] repeated core.v3.TypedExtensionConfig bootstrap_extensions = 21; // Specifies optional extensions instantiated at startup time and diff --git a/generated_api_shadow/envoy/config/bootstrap/v4alpha/bootstrap.proto b/generated_api_shadow/envoy/config/bootstrap/v4alpha/bootstrap.proto index 69c499186bb5d..5928b89f00494 100644 --- a/generated_api_shadow/envoy/config/bootstrap/v4alpha/bootstrap.proto +++ b/generated_api_shadow/envoy/config/bootstrap/v4alpha/bootstrap.proto @@ -186,6 +186,7 @@ message Bootstrap { // Optional watchdogs configuration. // This is used for specifying different watchdogs for the different subsystems. + // [#extension-category: envoy.guarddog_actions] Watchdogs watchdogs = 27; // Configuration for an external tracing provider. @@ -245,6 +246,7 @@ message Bootstrap { // Specifies optional bootstrap extensions to be instantiated at startup time. // Each item contains extension specific configuration. + // [#extension-category: envoy.bootstrap] repeated core.v4alpha.TypedExtensionConfig bootstrap_extensions = 21; // Specifies optional extensions instantiated at startup time and diff --git a/generated_api_shadow/envoy/config/cluster/v3/cluster.proto b/generated_api_shadow/envoy/config/cluster/v3/cluster.proto index 894ab6c188be9..e47d3bf00e114 100644 --- a/generated_api_shadow/envoy/config/cluster/v3/cluster.proto +++ b/generated_api_shadow/envoy/config/cluster/v3/cluster.proto @@ -159,6 +159,7 @@ message Cluster { google.protobuf.Struct match = 2; // The configuration of the transport socket. + // [#extension-category: envoy.transport_sockets.upstream] core.v3.TransportSocket transport_socket = 3; } @@ -172,6 +173,7 @@ message Cluster { // Cluster specific configuration which depends on the cluster being instantiated. // See the supported cluster for further documentation. + // [#extension-category: envoy.clusters] google.protobuf.Any typed_config = 2; } @@ -1003,6 +1005,7 @@ message Cluster { // If users desire custom connection pool or upstream behavior, for example terminating // CONNECT only if a custom filter indicates it is appropriate, the custom factories // can be registered and configured here. + // [#extension-category: envoy.upstreams] core.v3.TypedExtensionConfig upstream_config = 48; // Configuration to track optional cluster stats. diff --git a/generated_api_shadow/envoy/config/cluster/v4alpha/cluster.proto b/generated_api_shadow/envoy/config/cluster/v4alpha/cluster.proto index 3ffa88ddde6a6..ddac036831180 100644 --- a/generated_api_shadow/envoy/config/cluster/v4alpha/cluster.proto +++ b/generated_api_shadow/envoy/config/cluster/v4alpha/cluster.proto @@ -161,6 +161,7 @@ message Cluster { google.protobuf.Struct match = 2; // The configuration of the transport socket. + // [#extension-category: envoy.transport_sockets.upstream] core.v4alpha.TransportSocket transport_socket = 3; } @@ -174,6 +175,7 @@ message Cluster { // Cluster specific configuration which depends on the cluster being instantiated. // See the supported cluster for further documentation. + // [#extension-category: envoy.clusters] google.protobuf.Any typed_config = 2; } @@ -1017,6 +1019,7 @@ message Cluster { // If users desire custom connection pool or upstream behavior, for example terminating // CONNECT only if a custom filter indicates it is appropriate, the custom factories // can be registered and configured here. + // [#extension-category: envoy.upstreams] core.v4alpha.TypedExtensionConfig upstream_config = 48; // Configuration to track optional cluster stats. diff --git a/generated_api_shadow/envoy/config/core/v3/grpc_service.proto b/generated_api_shadow/envoy/config/core/v3/grpc_service.proto index fb05f3b73a5fd..648a972031cad 100644 --- a/generated_api_shadow/envoy/config/core/v3/grpc_service.proto +++ b/generated_api_shadow/envoy/config/core/v3/grpc_service.proto @@ -120,6 +120,7 @@ message GrpcService { string name = 1; + // [#extension-category: envoy.grpc_credentials] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/core/v3/health_check.proto b/generated_api_shadow/envoy/config/core/v3/health_check.proto index 5f8fd325aa959..2e72212d31f11 100644 --- a/generated_api_shadow/envoy/config/core/v3/health_check.proto +++ b/generated_api_shadow/envoy/config/core/v3/health_check.proto @@ -187,6 +187,7 @@ message HealthCheck { // A custom health checker specific configuration which depends on the custom health checker // being instantiated. See :api:`envoy/config/health_checker` for reference. + // [#extension-category: envoy.health_checkers] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/core/v4alpha/grpc_service.proto b/generated_api_shadow/envoy/config/core/v4alpha/grpc_service.proto index 9ea35b4564709..c7c284f1bdcd8 100644 --- a/generated_api_shadow/envoy/config/core/v4alpha/grpc_service.proto +++ b/generated_api_shadow/envoy/config/core/v4alpha/grpc_service.proto @@ -124,6 +124,7 @@ message GrpcService { string name = 1; + // [#extension-category: envoy.grpc_credentials] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/config/core/v4alpha/health_check.proto b/generated_api_shadow/envoy/config/core/v4alpha/health_check.proto index 8d870680a466d..ddc7d65e00075 100644 --- a/generated_api_shadow/envoy/config/core/v4alpha/health_check.proto +++ b/generated_api_shadow/envoy/config/core/v4alpha/health_check.proto @@ -189,6 +189,7 @@ message HealthCheck { // A custom health checker specific configuration which depends on the custom health checker // being instantiated. See :api:`envoy/config/health_checker` for reference. + // [#extension-category: envoy.health_checkers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/config/listener/v3/listener_components.proto b/generated_api_shadow/envoy/config/listener/v3/listener_components.proto index f96647e5d0b11..1124e820467db 100644 --- a/generated_api_shadow/envoy/config/listener/v3/listener_components.proto +++ b/generated_api_shadow/envoy/config/listener/v3/listener_components.proto @@ -35,6 +35,7 @@ message Filter { // :ref:`supported filter `. string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.filters.network] oneof config_type { // Filter specific configuration which depends on the filter being // instantiated. See the supported filters for further documentation. @@ -328,10 +329,12 @@ message ListenerFilter { // The name of the filter to instantiate. The name must match a // :ref:`supported filter `. + // [#extension-category: envoy.transport_sockets.downstream] string name = 1 [(validate.rules).string = {min_len: 1}]; // Filter specific configuration which depends on the filter being instantiated. // See the supported filters for further documentation. + // [#extension-category: envoy.filters.listener] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto b/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto index 7d9bef4b67690..8573e240d3c57 100644 --- a/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto +++ b/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto @@ -27,6 +27,7 @@ message UdpListenerConfig { // Used to create a specific listener factory. To some factory, e.g. // "raw_udp_listener", config is not needed. + // [#extension-category: envoy.filters.udp_listener] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/listener/v4alpha/listener_components.proto b/generated_api_shadow/envoy/config/listener/v4alpha/listener_components.proto index 2b3c218c7bdfe..bb03a9226834f 100644 --- a/generated_api_shadow/envoy/config/listener/v4alpha/listener_components.proto +++ b/generated_api_shadow/envoy/config/listener/v4alpha/listener_components.proto @@ -35,6 +35,7 @@ message Filter { // :ref:`supported filter `. string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.filters.network] oneof config_type { // Filter specific configuration which depends on the filter being // instantiated. See the supported filters for further documentation. @@ -335,10 +336,12 @@ message ListenerFilter { // The name of the filter to instantiate. The name must match a // :ref:`supported filter `. + // [#extension-category: envoy.transport_sockets.downstream] string name = 1 [(validate.rules).string = {min_len: 1}]; // Filter specific configuration which depends on the filter being instantiated. // See the supported filters for further documentation. + // [#extension-category: envoy.filters.listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto b/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto index 96eebee2d237e..9d6a3917a1526 100644 --- a/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto +++ b/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto @@ -30,6 +30,7 @@ message UdpListenerConfig { // Used to create a specific listener factory. To some factory, e.g. // "raw_udp_listener", config is not needed. + // [#extension-category: envoy.filters.udp_listener] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/config/metrics/v3/stats.proto b/generated_api_shadow/envoy/config/metrics/v3/stats.proto index 2d53df66f9c11..77da528d50269 100644 --- a/generated_api_shadow/envoy/config/metrics/v3/stats.proto +++ b/generated_api_shadow/envoy/config/metrics/v3/stats.proto @@ -38,6 +38,7 @@ message StatsSink { // Stats sink specific configuration which depends on the sink being instantiated. See // :ref:`StatsdSink ` for an example. + // [#extension-category: envoy.stats_sinks] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/metrics/v4alpha/stats.proto b/generated_api_shadow/envoy/config/metrics/v4alpha/stats.proto index 02d7c18db5ce6..3a351cdd094c6 100644 --- a/generated_api_shadow/envoy/config/metrics/v4alpha/stats.proto +++ b/generated_api_shadow/envoy/config/metrics/v4alpha/stats.proto @@ -41,6 +41,7 @@ message StatsSink { // Stats sink specific configuration which depends on the sink being instantiated. See // :ref:`StatsdSink ` for an example. + // [#extension-category: envoy.stats_sinks] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/config/overload/v3/overload.proto b/generated_api_shadow/envoy/config/overload/v3/overload.proto index 567f9405c693f..ae23dd3c69bb1 100644 --- a/generated_api_shadow/envoy/config/overload/v3/overload.proto +++ b/generated_api_shadow/envoy/config/overload/v3/overload.proto @@ -38,6 +38,7 @@ message ResourceMonitor { string name = 1 [(validate.rules).string = {min_len: 1}]; // Configuration for the resource monitor being instantiated. + // [#extension-category: envoy.resource_monitors] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/route/v3/route_components.proto b/generated_api_shadow/envoy/config/route/v3/route_components.proto index e551c126ac553..118973b5874a5 100644 --- a/generated_api_shadow/envoy/config/route/v3/route_components.proto +++ b/generated_api_shadow/envoy/config/route/v3/route_components.proto @@ -1136,6 +1136,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_priorities] oneof config_type { google.protobuf.Any typed_config = 3; @@ -1149,6 +1150,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_host_predicates] oneof config_type { google.protobuf.Any typed_config = 3; @@ -1769,6 +1771,7 @@ message RateLimit { MetaData metadata = 8; // Rate limit descriptor extension. See the rate limit descriptor extensions documentation. + // [#extension-category: envoy.rate_limit_descriptors] core.v3.TypedExtensionConfig extension = 9; } } @@ -1966,6 +1969,7 @@ message InternalRedirectPolicy { // Specifies a list of predicates that are queried when an upstream response is deemed // to trigger an internal redirect by all other criteria. Any predicate in the list can reject // the redirect, causing the response to be proxied to downstream. + // [#extension-category: envoy.internal_redirect_predicates] repeated core.v3.TypedExtensionConfig predicates = 3; // Allow internal redirect to follow a target URI with a different scheme than the value of diff --git a/generated_api_shadow/envoy/config/route/v4alpha/route_components.proto b/generated_api_shadow/envoy/config/route/v4alpha/route_components.proto index 2c4f12acb60ab..ec52cb00d78f2 100644 --- a/generated_api_shadow/envoy/config/route/v4alpha/route_components.proto +++ b/generated_api_shadow/envoy/config/route/v4alpha/route_components.proto @@ -1137,6 +1137,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_priorities] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1152,6 +1153,7 @@ message RetryPolicy { string name = 1 [(validate.rules).string = {min_len: 1}]; + // [#extension-category: envoy.retry_host_predicates] oneof config_type { google.protobuf.Any typed_config = 3; } @@ -1778,6 +1780,7 @@ message RateLimit { MetaData metadata = 8; // Rate limit descriptor extension. See the rate limit descriptor extensions documentation. + // [#extension-category: envoy.rate_limit_descriptors] core.v4alpha.TypedExtensionConfig extension = 9; } } @@ -1980,6 +1983,7 @@ message InternalRedirectPolicy { // Specifies a list of predicates that are queried when an upstream response is deemed // to trigger an internal redirect by all other criteria. Any predicate in the list can reject // the redirect, causing the response to be proxied to downstream. + // [#extension-category: envoy.internal_redirect_predicates] repeated core.v4alpha.TypedExtensionConfig predicates = 3; // Allow internal redirect to follow a target URI with a different scheme than the value of diff --git a/generated_api_shadow/envoy/config/trace/v3/http_tracer.proto b/generated_api_shadow/envoy/config/trace/v3/http_tracer.proto index 23d0efc47a38e..b679310769a57 100644 --- a/generated_api_shadow/envoy/config/trace/v3/http_tracer.proto +++ b/generated_api_shadow/envoy/config/trace/v3/http_tracer.proto @@ -59,6 +59,7 @@ message Tracing { // - :ref:`DatadogConfig ` // - :ref:`OpenCensusConfig ` // - :ref:`AWS X-Ray ` + // [#extension-category: envoy.tracers] oneof config_type { google.protobuf.Any typed_config = 3; diff --git a/generated_api_shadow/envoy/config/trace/v3/xray.proto b/generated_api_shadow/envoy/config/trace/v3/xray.proto index a904a10892360..208170b60c3f7 100644 --- a/generated_api_shadow/envoy/config/trace/v3/xray.proto +++ b/generated_api_shadow/envoy/config/trace/v3/xray.proto @@ -21,6 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: AWS X-Ray Tracer Configuration] // Configuration for AWS X-Ray tracer +// [#extension: envoy.tracers.xray] message XRayConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2alpha.XRayConfig"; diff --git a/generated_api_shadow/envoy/config/trace/v4alpha/http_tracer.proto b/generated_api_shadow/envoy/config/trace/v4alpha/http_tracer.proto index 2a7d3134312ba..4b8c681688425 100644 --- a/generated_api_shadow/envoy/config/trace/v4alpha/http_tracer.proto +++ b/generated_api_shadow/envoy/config/trace/v4alpha/http_tracer.proto @@ -62,6 +62,7 @@ message Tracing { // - :ref:`DatadogConfig ` // - :ref:`OpenCensusConfig ` // - :ref:`AWS X-Ray ` + // [#extension-category: envoy.tracers] oneof config_type { google.protobuf.Any typed_config = 3; } diff --git a/generated_api_shadow/envoy/extensions/filters/http/cache/v3alpha/cache.proto b/generated_api_shadow/envoy/extensions/filters/http/cache/v3alpha/cache.proto index 9260abe94a96c..9e140a38a902e 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/cache/v3alpha/cache.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/cache/v3alpha/cache.proto @@ -18,8 +18,8 @@ option (udpa.annotations.file_status).work_in_progress = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: HTTP Cache Filter] -// [#extension: envoy.filters.http.cache] +// [#extension: envoy.filters.http.cache.simple_http_cache] message CacheConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.cache.v2alpha.CacheConfig"; diff --git a/generated_api_shadow/envoy/extensions/filters/http/cache/v4alpha/cache.proto b/generated_api_shadow/envoy/extensions/filters/http/cache/v4alpha/cache.proto index ad9bb4c639a4d..283e8f53aebb2 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/cache/v4alpha/cache.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/cache/v4alpha/cache.proto @@ -18,8 +18,8 @@ option (udpa.annotations.file_status).work_in_progress = true; option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE; // [#protodoc-title: HTTP Cache Filter] -// [#extension: envoy.filters.http.cache] +// [#extension: envoy.filters.http.cache.simple_http_cache] message CacheConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.filters.http.cache.v3alpha.CacheConfig"; diff --git a/generated_api_shadow/envoy/extensions/filters/http/compressor/v3/compressor.proto b/generated_api_shadow/envoy/extensions/filters/http/compressor/v3/compressor.proto index 766560d9b5864..ed347cc439eb7 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/compressor/v3/compressor.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/compressor/v3/compressor.proto @@ -96,6 +96,7 @@ message Compressor { // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. // This field is ignored if used in the context of the gzip http-filter, but is mandatory otherwise. + // [#extension-category: envoy.compression.compressor] config.core.v3.TypedExtensionConfig compressor_library = 6; // Configuration for request compression. Compression is disabled by default if left empty. diff --git a/generated_api_shadow/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto b/generated_api_shadow/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto index 40dfaa636408e..419e690051e38 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/compressor/v4alpha/compressor.proto @@ -106,6 +106,7 @@ message Compressor { // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. // This field is ignored if used in the context of the gzip http-filter, but is mandatory otherwise. + // [#extension-category: envoy.compression.compressor] config.core.v4alpha.TypedExtensionConfig compressor_library = 6; // Configuration for request compression. Compression is disabled by default if left empty. diff --git a/generated_api_shadow/envoy/extensions/filters/http/decompressor/v3/decompressor.proto b/generated_api_shadow/envoy/extensions/filters/http/decompressor/v3/decompressor.proto index 058172fbaf64f..54d5f23bc449e 100644 --- a/generated_api_shadow/envoy/extensions/filters/http/decompressor/v3/decompressor.proto +++ b/generated_api_shadow/envoy/extensions/filters/http/decompressor/v3/decompressor.proto @@ -43,6 +43,7 @@ message Decompressor { // A decompressor library to use for both request and response decompression. Currently only // :ref:`envoy.compression.gzip.compressor` // is included in Envoy. + // [#extension-category: envoy.compression.decompressor] config.core.v3.TypedExtensionConfig decompressor_library = 1 [(validate.rules).message = {required: true}]; diff --git a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index eece51219ca54..7b065043f9877 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -272,6 +272,7 @@ message HttpConnectionManager { // A list of individual HTTP filters that make up the filter chain for // requests made to the connection manager. :ref:`Order matters ` // as the filters are processed sequentially as request events happen. + // [#extension-category: envoy.filters.http] repeated HttpFilter http_filters = 5; // Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent` diff --git a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto index fe245ce2fce87..7d4198fbf681e 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto @@ -267,6 +267,7 @@ message HttpConnectionManager { // A list of individual HTTP filters that make up the filter chain for // requests made to the connection manager. :ref:`Order matters ` // as the filters are processed sequentially as request events happen. + // [#extension-category: envoy.filters.http] repeated HttpFilter http_filters = 5; // Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent` diff --git a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto index 4fc04f2d88033..8485693caaf9e 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v3/thrift_proxy.proto @@ -81,6 +81,7 @@ message ThriftProxy { // Thrift proxy. Order matters as the filters are processed sequentially. For backwards // compatibility, if no thrift_filters are specified, a default Thrift router filter // (`envoy.filters.thrift.router`) is used. + // [#extension-category: envoy.thrift_proxy.filters] repeated ThriftFilter thrift_filters = 5; // If set to true, Envoy will try to skip decode data after metadata in the Thrift message. diff --git a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto index 05f8c54f6c63b..1834202272362 100644 --- a/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto +++ b/generated_api_shadow/envoy/extensions/filters/network/thrift_proxy/v4alpha/thrift_proxy.proto @@ -80,6 +80,7 @@ message ThriftProxy { // Thrift proxy. Order matters as the filters are processed sequentially. For backwards // compatibility, if no thrift_filters are specified, a default Thrift router filter // (`envoy.filters.thrift.router`) is used. + // [#extension-category: envoy.thrift_proxy.filters] repeated ThriftFilter thrift_filters = 5; // If set to true, Envoy will try to skip decode data after metadata in the Thrift message. diff --git a/generated_api_shadow/envoy/extensions/tracers/xray/v4alpha/xray.proto b/generated_api_shadow/envoy/extensions/tracers/xray/v4alpha/xray.proto index c21ce9a7cf828..649f294b4273b 100644 --- a/generated_api_shadow/envoy/extensions/tracers/xray/v4alpha/xray.proto +++ b/generated_api_shadow/envoy/extensions/tracers/xray/v4alpha/xray.proto @@ -19,6 +19,7 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // [#protodoc-title: AWS X-Ray Tracer Configuration] // Configuration for AWS X-Ray tracer +// [#extension: envoy.tracers.xray] message XRayConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v3.XRayConfig"; diff --git a/generated_api_shadow/envoy/extensions/wasm/v3/wasm.proto b/generated_api_shadow/envoy/extensions/wasm/v3/wasm.proto index 12cc06739ddd1..dc2844d24748d 100644 --- a/generated_api_shadow/envoy/extensions/wasm/v3/wasm.proto +++ b/generated_api_shadow/envoy/extensions/wasm/v3/wasm.proto @@ -81,6 +81,7 @@ message VmConfig { // (proxy_on_start). `google.protobuf.Struct` is serialized as JSON before // passing it to the plugin. `google.protobuf.BytesValue` and // `google.protobuf.StringValue` are passed directly without the wrapper. + // [#extension-category: envoy.wasm.runtime] google.protobuf.Any configuration = 4; // Allow the wasm file to include pre-compiled code on VMs which support it. diff --git a/tools/api_proto_plugin/annotations.py b/tools/api_proto_plugin/annotations.py index 48452742125a7..cb8abdf3b91be 100644 --- a/tools/api_proto_plugin/annotations.py +++ b/tools/api_proto_plugin/annotations.py @@ -10,6 +10,9 @@ # Page/section titles with special prefixes in the proto comments DOC_TITLE_ANNOTATION = 'protodoc-title' +# Specify the type of extensions at extension points +EXTENSION_CATEGORY_ANNOTATION = 'extension-category' + # When documenting an extension, this should be used to specify the qualified # name that the extension registers as in the static registry, e.g. # envoy.filters.network.http_connection_manager. @@ -32,6 +35,7 @@ VALID_ANNOTATIONS = set([ DOC_TITLE_ANNOTATION, EXTENSION_ANNOTATION, + EXTENSION_CATEGORY_ANNOTATION, NOT_IMPLEMENTED_HIDE_ANNOTATION, NEXT_FREE_FIELD_ANNOTATION, NEXT_MAJOR_VERSION_ANNOTATION, diff --git a/tools/protodoc/protodoc.py b/tools/protodoc/protodoc.py index 10faf4473fe63..7911d33e89426 100755 --- a/tools/protodoc/protodoc.py +++ b/tools/protodoc/protodoc.py @@ -63,6 +63,25 @@ """) +# Template for formating extension's category/ies. +EXTENSION_CATEGORIES_TEMPLATE = string.Template(""" +.. tip:: + $message: + +$categories + +""") + +# Template for formating an extension category. +EXTENSION_CATEGORY_TEMPLATE = string.Template("""$anchor + +.. tip:: + This extension category has the following known extensions: + +$extensions + +""") + # A map from the extension security postures (as defined in the # envoy_cc_extension build macro) to human readable text for extension docs. EXTENSION_SECURITY_POSTURES = { @@ -92,6 +111,14 @@ 'This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.', } +EXTENSION_DB = json.loads(pathlib.Path(os.getenv('EXTENSION_DB_PATH')).read_text()) + +# create an index of extension categories from extension db +EXTENSION_CATEGORIES = {} +for _k, _v in EXTENSION_DB.items(): + for _cat in _v['categories']: + EXTENSION_CATEGORIES.setdefault(_cat, []).append(_k) + class ProtodocError(Exception): """Base error class for the protodoc module.""" @@ -132,7 +159,12 @@ def FormatCommentWithAnnotations(comment, type_name=''): if annotations.EXTENSION_ANNOTATION in comment.annotations: extension = comment.annotations[annotations.EXTENSION_ANNOTATION] formatted_extension = FormatExtension(extension) - return annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n') + formatted_extension + formatted_extension_category = '' + if annotations.EXTENSION_CATEGORY_ANNOTATION in comment.annotations: + formatted_extension_category = FormatExtensionCategory( + comment.annotations[annotations.EXTENSION_CATEGORY_ANNOTATION]) + comment = annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n') + return comment + formatted_extension + formatted_extension_category def MapLines(f, s): @@ -189,21 +221,51 @@ def FormatExtension(extension): RST formatted extension description. """ try: - extension_metadata = json.loads(pathlib.Path( - os.getenv('EXTENSION_DB_PATH')).read_text())[extension] + extension_metadata = EXTENSION_DB[extension] anchor = FormatAnchor('extension_' + extension) status = EXTENSION_STATUS_VALUES.get(extension_metadata['status'], '') security_posture = EXTENSION_SECURITY_POSTURES[extension_metadata['security_posture']] - return EXTENSION_TEMPLATE.substitute(anchor=anchor, - extension=extension, - status=status, - security_posture=security_posture) + extension = EXTENSION_TEMPLATE.substitute(anchor=anchor, + extension=extension, + status=status, + security_posture=security_posture) + + categories = FormatExtensionList(extension_metadata["categories"], "extension_category") + cat_or_cats = "categories" if len(categories) > 1 else "category" + category_message = f"This extension extends and can be used with the following extension {cat_or_cats}" + extension_category = EXTENSION_CATEGORIES_TEMPLATE.substitute(message=category_message, + categories=categories) + return f"{extension}\n\n{extension_category}" except KeyError as e: sys.stderr.write( '\n\nDid you forget to add an entry to source/extensions/extensions_build_config.bzl?\n\n') exit(1) # Raising the error buries the above message in tracebacks. +def FormatExtensionList(items, prefix="extension", indent=2): + indent = " " * indent + formatted_list = "\n".join(f"{indent}- :ref:`{ext} <{prefix}_{ext}>`" for ext in items) + return f"{formatted_list}\n{indent}\n" + + +def FormatExtensionCategory(extension_category): + """Format extension metadata as RST. + + Args: + extension_category: the name of the extension_category, e.g. com.acme. + + Returns: + RST formatted extension category description. + """ + try: + extensions = EXTENSION_CATEGORIES[extension_category] + except KeyError as e: + raise ProtodocError(f"\n\nUnable to find extension category: {extension_category}\n\n") + anchor = FormatAnchor('extension_category_' + extension_category) + extensions = FormatExtensionList(sorted(extensions)) + return EXTENSION_CATEGORY_TEMPLATE.substitute(anchor=anchor, extensions=extensions) + + def FormatHeaderFromFile(style, source_code_info, proto_name): """Format RST header based on special file level title diff --git a/tools/spelling/spelling_dictionary.txt b/tools/spelling/spelling_dictionary.txt index e0c0a95c61068..503670c0a19c6 100644 --- a/tools/spelling/spelling_dictionary.txt +++ b/tools/spelling/spelling_dictionary.txt @@ -116,6 +116,7 @@ FQDN FREEBIND FUZZER FUZZERS +guarddog GC GCC GCE