Add documentation for external authorization filter. (#3379)

Signed-off-by: Saurabh Mohan <saurabh+github@tigera.io>

Mirrored from https://github.com/envoyproxy/envoy @ a2abe7a4fae83cc2ad45700e59f4be52cbd3baac

docs/BUILD

@@ -58,6 +58,8 @@ proto_library(
         "//envoy/data/accesslog/v2:accesslog",
         "//envoy/data/tap/v2alpha:capture",
         "//envoy/service/accesslog/v2:als",
+        "//envoy/service/auth/v2alpha:attribute_context",
+        "//envoy/service/auth/v2alpha:external_auth",
         "//envoy/service/discovery/v2:ads",
         "//envoy/service/load_stats/v2:lrs",
         "//envoy/service/metrics/v2:metrics_service",

envoy/api/v2/core/http_uri.proto

@@ -7,8 +7,9 @@ import "gogoproto/gogo.proto";
 
 import "validate/validate.proto";
 
+// [#protodoc-title: HTTP Service URI ]
+
 // Envoy external URI descriptor
-// [#not-implemented-hide:]
 message HttpUri {
   // The HTTP server URI. It should be a full FQDN with protocol, host and path.
   //

envoy/config/filter/http/ext_authz/v2alpha/ext_authz.proto

@@ -6,7 +6,12 @@ option go_package = "v2alpha";
 import "envoy/api/v2/core/grpc_service.proto";
 import "envoy/api/v2/core/http_uri.proto";
 
-// The external authorization HTTP service configuration.
+// [#protodoc-title: HTTP External Authorization ]
+// The external authorization HTTP service configuration
+// :ref:`configuration overview <config_http_filters_ext_authz>`.
+
+// [#not-implemented-hide:]
+// [#comment: The HttpService is under development and will be supported soon.]
 message HttpService {
   // Sets the HTTP server URI which the authorization requests must be sent to.
   envoy.api.v2.core.HttpUri server_uri = 1;
@@ -15,20 +20,25 @@ message HttpService {
   string path_prefix = 2;
 }
 
+// External Authorization filter calls out to an external service over the
+// gRPC Authorization API defined by
+// :ref:`CheckRequest <envoy_api_msg_service.auth.v2alpha.CheckRequest>`.
+// A failed check will cause this filter to close the HTTP request with 403(Forbidden).
 message ExtAuthz {
 
   oneof services {
     // The external authorization gRPC service configuration.
+    // The default timeout is set to 200ms by this filter.
     envoy.api.v2.core.GrpcService grpc_service = 1;
 
     // The external authorization HTTP service configuration.
+    // [#not-implemented-hide:]
     HttpService http_service = 3;
   }
 
   // The filter's behaviour in case the external authorization service does
-  // not respond back. If set to true then in case of failure to get a
+  // not respond back. When it is set to true, Envoy will also allow traffic in case of
-  // response back from the authorization service or getting a response that
+  // communication failure between authorization service and the proxy.
-  // is NOT denied then traffic will be permitted.
   // Defaults to false.
   bool failure_mode_allow = 2;
 }

envoy/config/filter/network/ext_authz/v2/ext_authz.proto

@@ -7,22 +7,25 @@ import "envoy/api/v2/core/grpc_service.proto";
 
 import "validate/validate.proto";
 
-// [#not-implemented-hide:]
+// [#protodoc-title: Network External Authorization ]
+// The network layer external authorization service configuration
+// :ref:`configuration overview <config_network_filters_ext_authz>`.
+
 // External Authorization filter calls out to an external service over the
 // gRPC Authorization API defined by
-// :ref:`external_auth <envoy_api_msg_auth.CheckRequest>`.
+// :ref:`CheckRequest <envoy_api_msg_service.auth.v2alpha.CheckRequest>`.
 // A failed check will cause this filter to close the TCP connection.
 message ExtAuthz {
   // The prefix to use when emitting statistics.
   string stat_prefix = 1 [(validate.rules).string.min_bytes = 1];
 
   // The external authorization gRPC service configuration.
+  // The default timeout is set to 200ms by this filter.
   envoy.api.v2.core.GrpcService grpc_service = 2;
 
   // The filter's behaviour in case the external authorization service does
-  // not respond back. If set to true then in case of failure to get a
+  // not respond back. When it is set to true, Envoy will also allow traffic in case of
-  // response back from the authorization service or getting a response that
+  // communication failure between authorization service and the proxy.
-  // is NOT denied then traffic will be permitted.
   // Defaults to false.
   bool failure_mode_allow = 3;
 }

envoy/service/auth/v2alpha/attribute_context.proto

@@ -1,13 +1,16 @@
 syntax = "proto3";
 
-// [#proto-status: draft]
-
 package envoy.service.auth.v2alpha;
 
 import "envoy/api/v2/core/address.proto";
 
 import "google/protobuf/timestamp.proto";
 
+// [#protodoc-title: Attribute Context ]
+
+// See :ref:`network filter configuration overview <config_network_filters_ext_authz>`
+// and :ref:`HTTP filter configuration overview <config_http_filters_ext_authz>`.
+
 // An attribute is a piece of metadata that describes an activity on a network.
 // For example, the size of an HTTP request, or the status code of an HTTP response.
 //
@@ -115,8 +118,8 @@ message AttributeContext {
 
   // This is analogous to http_request.headers, however these contents will not be sent to the
   // upstream server. Context_extensions provide an extension mechanism for sending additional
-  // information to the auth server without modifying the proto definition. It maps to the internal
+  // information to the auth server without modifying the proto definition. It maps to the
-  // opaque context in the filter chain.
+  // internal opaque context in the filter chain.
   map<string, string> context_extensions = 10;
 }
 

envoy/service/auth/v2alpha/external_auth.proto

@@ -1,7 +1,5 @@
 syntax = "proto3";
 
-// [#proto-status: draft]
-
 package envoy.service.auth.v2alpha;
 option go_package = "v2alpha";
 option java_generic_services = true;
@@ -11,6 +9,11 @@ import "envoy/service/auth/v2alpha/attribute_context.proto";
 import "google/rpc/status.proto";
 import "validate/validate.proto";
 
+// [#protodoc-title: Authorization Service ]
+
+// The authorization service request messages used by external authorization :ref:`network filter
+// <config_network_filters_ext_authz>` and :ref:`HTTP filter <config_http_filters_ext_authz>`.
+
 // A generic interface for performing authorization check on incoming
 // requests to a networked service.
 service Authorization {