docs: Add extension categories to extension docs (#14721)

Add information about known extension categories (types) to extension documentation

Signed-off-by: Ryan Northey <ryan@synca.io>

Mirrored from https://github.com/envoyproxy/envoy @ 7adc0393221467fcae18052c1f7caf0cb6048d2e

envoy/config/accesslog/v3/accesslog.proto

@@ -49,6 +49,7 @@ message AccessLog {
   //    <envoy_api_msg_extensions.access_loggers.grpc.v3.HttpGrpcAccessLogConfig>`
   // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig
   //    <envoy_api_msg_extensions.access_loggers.grpc.v3.TcpGrpcAccessLogConfig>`
+  // [#extension-category: envoy.access_loggers]
   oneof config_type {
     google.protobuf.Any typed_config = 4;
   }

envoy/config/accesslog/v4alpha/accesslog.proto

@@ -49,6 +49,7 @@ message AccessLog {
   //    <envoy_api_msg_extensions.access_loggers.grpc.v4alpha.HttpGrpcAccessLogConfig>`
   // #. "envoy.access_loggers.tcp_grpc": :ref:`TcpGrpcAccessLogConfig
   //    <envoy_api_msg_extensions.access_loggers.grpc.v4alpha.TcpGrpcAccessLogConfig>`
+  // [#extension-category: envoy.access_loggers]
   oneof config_type {
     google.protobuf.Any typed_config = 4;
   }

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

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

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.

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.

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;
         }

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;
     }

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;
         }

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;
     }

envoy/config/listener/v3/listener_components.proto

@@ -35,6 +35,7 @@ message Filter {
   // :ref:`supported filter <config_network_filters>`.
   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 <config_listener_filters>`.
+  // [#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;
   }

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;
   }

envoy/config/listener/v4alpha/listener_components.proto

@@ -35,6 +35,7 @@ message Filter {
   // :ref:`supported filter <config_network_filters>`.
   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 <config_listener_filters>`.
+  // [#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;
   }

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;
   }

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 <envoy_api_msg_config.metrics.v3.StatsdSink>` for an example.
+  // [#extension-category: envoy.stats_sinks]
   oneof config_type {
     google.protobuf.Any typed_config = 3;
   }

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 <envoy_api_msg_config.metrics.v4alpha.StatsdSink>` for an example.
+  // [#extension-category: envoy.stats_sinks]
   oneof config_type {
     google.protobuf.Any typed_config = 3;
   }

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;
   }

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

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

envoy/config/trace/v3/http_tracer.proto

@@ -62,6 +62,7 @@ message Tracing {
     // - :ref:`DatadogConfig <envoy_api_msg_config.trace.v3.DatadogConfig>`
     // - :ref:`OpenCensusConfig <envoy_api_msg_config.trace.v3.OpenCensusConfig>`
     // - :ref:`AWS X-Ray <envoy_api_msg_config.trace.v3.XRayConfig>`
+    // [#extension-category: envoy.tracers]
     oneof config_type {
       google.protobuf.Any typed_config = 3;
     }

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";

envoy/config/trace/v4alpha/http_tracer.proto

@@ -62,6 +62,7 @@ message Tracing {
     // - :ref:`DatadogConfig <envoy_api_msg_extensions.tracers.datadog.v4alpha.DatadogConfig>`
     // - :ref:`OpenCensusConfig <envoy_api_msg_extensions.tracers.opencensus.v4alpha.OpenCensusConfig>`
     // - :ref:`AWS X-Ray <envoy_api_msg_extensions.tracers.xray.v4alpha.XRayConfig>`
+    // [#extension-category: envoy.tracers]
     oneof config_type {
       google.protobuf.Any typed_config = 3;
     }

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";

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";

envoy/extensions/filters/http/compressor/v3/compressor.proto

@@ -96,6 +96,7 @@ message Compressor {
   // :ref:`envoy.compression.gzip.compressor<envoy_api_msg_extensions.compression.gzip.compressor.v3.Gzip>`
   // 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.

envoy/extensions/filters/http/compressor/v4alpha/compressor.proto

@@ -83,6 +83,7 @@ message Compressor {
   // :ref:`envoy.compression.gzip.compressor<envoy_api_msg_extensions.compression.gzip.compressor.v3.Gzip>`
   // 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.

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<envoy_api_msg_extensions.compression.gzip.decompressor.v3.Gzip>`
   // is included in Envoy.
+  // [#extension-category: envoy.compression.decompressor]
   config.core.v3.TypedExtensionConfig decompressor_library = 1
       [(validate.rules).message = {required: true}];
 

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 <arch_overview_http_filters_ordering>`
   // 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`

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 <arch_overview_http_filters_ordering>`
   // 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`

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.

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.

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";
 

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.