ext_authz: v2Alpha migration and documentation improvements (#5672)

Signed-off-by: Gabriel <gsagula@gmail.com>

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

docs/BUILD

@@ -35,7 +35,7 @@ proto_library(
         "//envoy/config/bootstrap/v2:bootstrap",
         "//envoy/config/filter/accesslog/v2:accesslog",
         "//envoy/config/filter/http/buffer/v2:buffer",
-        "//envoy/config/filter/http/ext_authz/v2alpha:ext_authz",
+        "//envoy/config/filter/http/ext_authz/v2:ext_authz",
         "//envoy/config/filter/http/fault/v2:fault",
         "//envoy/config/filter/http/gzip/v2:gzip",
         "//envoy/config/filter/http/header_to_metadata/v2:header_to_metadata",
@@ -77,8 +77,8 @@ proto_library(
         "//envoy/data/tap/v2alpha:http",
         "//envoy/data/tap/v2alpha:wrapper",
         "//envoy/service/accesslog/v2:als",
-        "//envoy/service/auth/v2alpha:attribute_context",
+        "//envoy/service/auth/v2:attribute_context",
-        "//envoy/service/auth/v2alpha:external_auth",
+        "//envoy/service/auth/v2:external_auth",
         "//envoy/service/discovery/v2:ads",
         "//envoy/service/load_stats/v2:lrs",
         "//envoy/service/metrics/v2:metrics_service",

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

@@ -0,0 +1,147 @@
+syntax = "proto3";
+
+package envoy.config.filter.http.ext_authz.v2;
+option java_package = "io.envoyproxy.envoy.config.filter.http.ext_authz.v2";
+option java_multiple_files = true;
+option go_package = "v2";
+
+import "envoy/api/v2/core/base.proto";
+import "envoy/api/v2/core/grpc_service.proto";
+import "envoy/api/v2/core/http_uri.proto";
+
+import "envoy/type/matcher/string.proto";
+
+import "validate/validate.proto";
+
+// [#protodoc-title: External Authorization]
+// ExtAuthz :ref:`configuration overview <config_http_filters_ext_authz>`.
+message ExtAuthz {
+  // External authorization service configuration.
+  oneof services {
+    // gRPC service configuration (default timeout: 200ms).
+    envoy.api.v2.core.GrpcService grpc_service = 1;
+
+    // HTTP service configuration (default timeout: 200ms).
+    HttpService http_service = 3;
+  }
+
+  //  Changes filter's behaviour on errors:
+  //
+  //  1. When set to true, the filter will *accept* client request even if the communication with
+  //  the authorization service has failed, or if the authorization service has returned a HTTP 5xx
+  //  error.
+  //
+  //  2. When set to false, ext-authz will *reject* client requests and return a *Forbidden*
+  //  response if the communication with the authorization service has failed, or if the
+  //  authorization service has returned a HTTP 5xx error.
+  //
+  // Note that errors can be *always* tracked in the :ref:`stats
+  // <config_http_filters_ext_authz_stats>`.
+  bool failure_mode_allow = 2;
+}
+
+// HttpService is used for raw HTTP comunication between the filter and the authorization service.
+// When configured, the filter will parse the client request and use these attributes to call the
+// authorization server. Depending on the response, the filter may reject or accept the client
+// request. Note that in any of these events, metadata can be added, removed or overriden by the
+// filter:
+//
+// *On authorization request*, a list of allowed request headers may be supplied. See
+// :ref:`allowed_headers
+// <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationRequest.allowed_headers>`
+// for details. Additional headers metadata may be added to the authorization resquest. See
+// :ref:`headers_to_add
+// <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationRequest.headers_to_add>` for
+// details.
+//
+// On authorization response status HTTP 200 OK, the filter will allow traffic to the upstream and
+// additional headers metadata may be added to the original client request. See
+// :ref:`allowed_upstream_headers
+// <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_upstream_headers>`
+// for details.
+//
+// On other authorization response statuses, the filter will not allow traffic. Additional headers
+// metadata as well as body may be added to the client's response. See :ref:`allowed_client_headers
+// <envoy_api_field_config.filter.http.ext_authz.v2.AuthorizationResponse.allowed_client_headers>`
+// for details.
+message HttpService {
+  // Sets the HTTP server URI which the authorization requests must be sent to.
+  envoy.api.v2.core.HttpUri server_uri = 1;
+
+  // Sets a prefix to the value of authorization request header *Path*.
+  string path_prefix = 2;
+
+  reserved 3;
+  reserved 4;
+  reserved 5;
+  reserved 6;
+
+  // Settings used for controlling authorization request metadata.
+  AuthorizationRequest authorization_request = 7;
+
+  // Settings used for controlling authorization response metadata.
+  AuthorizationResponse authorization_response = 8;
+}
+
+message AuthorizationRequest {
+  // Authorization request will include the client request headers that have a correspondent match
+  // in the :ref:`list <envoy_api_msg_type.matcher.ListStringMatcher>`. Note that in addition to the
+  // user's supplied matchers:
+  //
+  // 1. *Host*, *Method*, *Path* and *Content-Length* are automatically included to the list.
+  //
+  // 2. *Content-Length* will be set to 0 and the request to the authorization service will not have
+  // a message body.
+  //
+  envoy.type.matcher.ListStringMatcher allowed_headers = 1;
+
+  // Sets a list of headers that will be included to the request to authorization service. Note that
+  // client request of the same key will be overriden.
+  repeated envoy.api.v2.core.HeaderValue headers_to_add = 2;
+}
+
+message AuthorizationResponse {
+  // When this :ref:`list <envoy_api_msg_type.matcher.ListStringMatcher>` is set, authorization
+  // response headers that have a correspondent match will be added to the original client request.
+  // Note that coexistent headers will be overriden.
+  envoy.type.matcher.ListStringMatcher allowed_upstream_headers = 1;
+
+  // When this :ref:`list <envoy_api_msg_type.matcher.ListStringMatcher>`. is set, authorization
+  // response headers that have a correspondent match will be added to the client's response. Note
+  // that when this list is *not* set, all the authorization response headers, except *Authority
+  // (Host)* will be in the response to the client. When a header is included in this list, *Path*,
+  // *Status*, *Content-Length*, *WWWAuthenticate* and *Location* are automatically added.
+  envoy.type.matcher.ListStringMatcher allowed_client_headers = 2;
+}
+
+// Extra settings on a per virtualhost/route/weighter-cluster level.
+message ExtAuthzPerRoute {
+  oneof override {
+    option (validate.required) = true;
+
+    // Disable the ext auth filter for this particular vhost or route.
+    // If disabled is specified in multiple per-filter-configs, the most specific one will be used.
+    bool disabled = 1 [(validate.rules).bool.const = true];
+
+    // Check request settings for this route.
+    CheckSettings check_settings = 2 [(validate.rules).message.required = true];
+  }
+}
+
+// Extra settings for the check request. You can use this to provide extra context for the
+// external authorization server on specific virtual hosts \ routes. For example, adding a context
+// extension on the virtual host level can give the ext-authz server information on what virtual
+// host is used without needing to parse the host header. If CheckSettings is specified in multiple
+// per-filter-configs, they will be merged in order, and the result will be be used.
+message CheckSettings {
+  // Context extensions to set on the CheckRequest's
+  // :ref:`AttributeContext.context_extensions<envoy_api_field_service.auth.v2.AttributeContext.context_extensions>`
+  //
+  // Merge semantics for this field are such that keys from more specific configs override.
+  //
+  // .. note::
+  //
+  //   These settings are only applied to a filter configured with a
+  //   :ref:`grpc_service<envoy_api_field_config.filter.http.ext_authz.v2.ExtAuthz.grpc_service>`.
+  map<string, string> context_extensions = 1;
+}

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

@@ -1,150 +0,0 @@
-syntax = "proto3";
-
-package envoy.config.filter.http.ext_authz.v2alpha;
-option java_package = "io.envoyproxy.envoy.config.filter.http.ext_authz.v2alpha";
-option go_package = "v2alpha";
-
-import "envoy/api/v2/core/base.proto";
-import "envoy/api/v2/core/grpc_service.proto";
-import "envoy/api/v2/core/http_uri.proto";
-
-import "envoy/type/matcher/string.proto";
-
-import "validate/validate.proto";
-
-// [#protodoc-title: External Authorization ]
-// The external authorization service configuration
-// :ref:`configuration overview <config_http_filters_ext_authz>`.
-
-// External Authorization filter calls out to an external service over either
-// gRPC or raw HTTP clients.
-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.
-    // The default timeout is set to 200ms by this filter.
-    HttpService http_service = 3;
-  }
-
-  // Allows bypassing the filter on errors during the authorization process.
-  //
-  //  1. When *failure_mode_allow* is true, traffic will be allowed in the presence of an error.
-  //  This includes any of the HTTP 5xx errors, or a communication failure between the filter and
-  //  the authorization server.
-  //  2. When *failure_mode_allow* is false, the filter will *always* return a *Forbidden response*
-  //  to the client. It will *not allow* traffic to the upstream in the presence of an error. This
-  //  includes any of the HTTP 5xx errors, or a communication failure between the filter and the
-  //  authorization server.
-  //
-  // Note that filter will produce stats on error. See *Statistics* at :ref:`configuration overview
-  // <config_http_filters_ext_authz>`.
-  bool failure_mode_allow = 2;
-}
-
-// External Authorization filter calls an authorization server by passing the raw
-// HTTP request headers to the server. This allows the authorization service to take a decision
-// whether the request should be authorized or not.
-//
-// A successful check allows the authorization service adding or overriding headers from the
-// original request before dispatching them to the upstream. This is done by configuring which
-// headers in the authorization response should be sent to the upstream. See
-// :ref:`allowed_upstream_headers
-// <envoy_api_field_config.filter.http.ext_authz.v2alpha.AuthorizationResponse.allowed_upstream_headers>`
-// for more details.
-//
-// A failed check will cause this filter to close the HTTP request with 403 (Forbidden),
-// unless a different status code has been indicated by the authorization server via response
-// headers. In addition to the the status code and with exception of the *Authority*, the filter
-// will send all headers from the authorization server back to the client by default. See
-// :ref:`allowed_client_headers
-// <envoy_api_field_config.filter.http.ext_authz.v2alpha.AuthorizationResponse.allowed_client_headers>`
-// for more details.
-//
-//  .. note::
-//
-//    Unlike the gRPC client that request and response headers are passed in the message,
-//    headers forwarded by via the raw HTTP client will affect the request or the response.
-message HttpService {
-  // Sets the HTTP server URI which the authorization requests must be sent to.
-  envoy.api.v2.core.HttpUri server_uri = 1;
-
-  // Sets an optional prefix to the value of authorization request header *Path*.
-  string path_prefix = 2;
-
-  reserved 3;
-  reserved 4;
-  reserved 5;
-  reserved 6;
-
-  // Settings for controlling request headers forwarded from the filter to the authorization server.
-  AuthorizationRequest authorization_request = 7;
-
-  // Settings for controlling authorization response forwarded from the filter to a client,
-  // or to an upstream service.
-  AuthorizationResponse authorization_response = 8;
-}
-
-message AuthorizationRequest {
-  // Sets a list of matchers that are used to determine which client request headers should
-  // be forwarded *from the filter* to the authorization server. Note that *Content-Length*,
-  // *Authority*, *Method*, *Path* and *Authorization* are always dispatched to the authorization
-  // server by default. The message will not contain body data and the *Content-Length* will be set
-  // to zero.
-  envoy.type.matcher.ListStringMatcher allowed_headers = 1;
-
-  // Sets a list of headers and their values that will be added to the request to external
-  // authorization server. Note that these will override the headers coming from the downstream.
-  repeated envoy.api.v2.core.HeaderValue headers_to_add = 2;
-}
-
-message AuthorizationResponse {
-  // Sets a list of matchers that are used to determine which authorization response headers should
-  // be forwarded *from the filter* to the upstream service only when the HTTP status is a 200 OK.
-  // Note that these headers will override that the original request headers when respectively
-  // matched.
-  envoy.type.matcher.ListStringMatcher allowed_upstream_headers = 1;
-
-  // Sets a list of keys that are used to determine which authorization response headers should
-  // be forwarded *from the filter* to the client when the HTTP status is *NOT* a 200 OK. Note that
-  // when this list is empty, all the authorization response headers, except *Authority* will be
-  // sent to the client (default). When a header is included in this list, *Path*, *Status*,
-  // *Content-Length*, *WWWAuthenticate* and *Location* are automatically added.
-  envoy.type.matcher.ListStringMatcher allowed_client_headers = 2;
-}
-
-// Extra settings on a per virtualhost/route/weighter-cluster level.
-message ExtAuthzPerRoute {
-  oneof override {
-    option (validate.required) = true;
-
-    // Disable the ext auth filter for this particular vhost or route.
-    // If disabled is specified in multiple per-filter-configs, the most specific one will be used.
-    bool disabled = 1 [(validate.rules).bool.const = true];
-
-    // Check request settings for this route.
-    CheckSettings check_settings = 2 [(validate.rules).message.required = true];
-  }
-}
-
-// Extra settings for the check request. You can use this to provide extra context for the
-// ext-authz server on specific virtual hosts \ routes. For example, adding a context extension on
-// the virtual host level can give the ext-authz server information on what virtual host is used
-// without needing to parse the host header.
-// If CheckSettings is specified in multiple per-filter-configs, they will be merged in order,
-// and the result will be be used.
-message CheckSettings {
-  // Context extensions to set on the CheckRequest's
-  // :ref:`AttributeContext.context_extensions<envoy_api_field_service.auth.v2alpha.AttributeContext.context_extensions>`
-  //
-  // Merge semantics for this field are such that keys from more specific configs override.
-  //
-  // .. note::
-  //
-  //   These settings are only applied to a filter configured with a
-  //   :ref:`grpc_service<envoy_api_field_config.filter.http.ext_authz.v2alpha.ExtAuthz.grpc_service>`.
-  map<string, string> context_extensions = 1;
-}

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

@@ -14,7 +14,7 @@ import "validate/validate.proto";
 
 // 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>`.
+// :ref:`CheckRequest <envoy_api_msg_service.auth.v2.CheckRequest>`.
 // A failed check will cause this filter to close the TCP connection.
 message ExtAuthz {
   // The prefix to use when emitting statistics.

envoy/service/auth/v2/attribute_context.proto

@@ -1,7 +1,7 @@
 syntax = "proto3";
 
-package envoy.service.auth.v2alpha;
+package envoy.service.auth.v2;
-option java_package = "io.envoyproxy.envoy.service.auth.v2alpha";
+option java_package = "io.envoyproxy.envoy.service.auth.v2";
 
 import "envoy/api/v2/core/address.proto";
 

envoy/service/auth/v2/external_auth.proto

@@ -1,13 +1,13 @@
 syntax = "proto3";
 
-package envoy.service.auth.v2alpha;
+package envoy.service.auth.v2;
-option java_package = "io.envoyproxy.envoy.service.auth.v2alpha";
+option java_package = "io.envoyproxy.envoy.service.auth.v2";
-option go_package = "v2alpha";
+option go_package = "v2";
 option java_generic_services = true;
 
 import "envoy/api/v2/core/base.proto";
 import "envoy/type/http_status.proto";
-import "envoy/service/auth/v2alpha/attribute_context.proto";
+import "envoy/service/auth/v2/attribute_context.proto";
 
 import "google/rpc/status.proto";
 import "validate/validate.proto";