docs: addressing suggestions of enhancements to the authpolicy docs

Kuadrant · Oct 18, 2023 · b4525c1 · b4525c1
1 parent 7d52a85
commit b4525c1
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 48 deletions.
diff --git a/doc/auth.md b/doc/auth.md
@@ -2,10 +2,10 @@
 
 A Kuadrant AuthPolicy custom resource:
 
-1. Allows it to target Gateway API networking resources such as [HTTPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute) and [Gateways](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway), using these resources to obtain additional context, i.e., which traffic workload (HTTP attributes, hostnames, user attributes, etc) to enforce auth.
-2. Allows to specify which specific subsets of the targeted network resource to apply the auth rules to.
+1. Targets Gateway API networking resources such as [HTTPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute) and [Gateways](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway), using these resources to obtain additional context, i.e., which traffic workload (HTTP attributes, hostnames, user attributes, etc) to enforce auth.
+2. Supports targeting subsets (sections) of a network resource to apply the auth rules to.
 3. Abstracts the details of the underlying external authorization protocol and configuration resources, that have a much broader remit and surface area.
-4. Supports cluster operators to set overrides (soon) and defaults that govern what can be done at the lower levels.
+4. Enables cluster operators to set defaults that govern behavior at the lower levels of the network, until a more specific policy is applied.
 
 ## How it works
 
@@ -28,7 +28,7 @@ The `AuthPolicy` spec includes the following parts:
 * Authentication/authorization scheme (`spec.rules`)
 * Top-level route selectors (`spec.routeSelectors`)
 * Top-level additional conditions (`spec.when`)
-* List of stored named patterns (`spec.patterns`)
+* List of named patterns (`spec.patterns`)
 
 The auth scheme specify rules for:
 * Authentication (`spec.rules.authentication`)
@@ -37,7 +37,7 @@ The auth scheme specify rules for:
 * Custom response items (`spec.rules.response`)
 * Callbacks (`spec.rules.callbacks`)
 
-where each auth rule can declare specific `routeSelectors` and `when` conditions for the rule to apply.
+Each auth rule can declare specific `routeSelectors` and `when` conditions for the rule to apply.
 
 #### High-level example and field definition
 
@@ -47,94 +47,97 @@ kind: AuthPolicy
 metadata:
   name: my-auth-policy
 spec:
-  # reference to an existing networking resource to attach the policy to
-  # it can be a Gateway API HTTPRoute or Gateway resource
-  # it can only refer to objects in the same namespace as the AuthPolicy
+  # Reference to an existing networking resource to attach the policy to.
+  # It can be a Gateway API HTTPRoute or Gateway resource.
+  # It can only refer to objects in the same namespace as the AuthPolicy.
   targetRef:
     group: gateway.networking.k8s.io
     kind: HTTPRoute / Gateway
     name: myroute / mygateway
 
-  # (optional) selectors of HTTPRouteRules within the targeted HTTPRoute that activate the AuthPolicy
-  # each element contains a HTTPRouteMatch object that will be used to select HTTPRouteRules that include at least one identical HTTPRouteMatch
-  # the HTTPRouteMatch part does not have to be fully identical, but the what's stated in the selector must be identically stated in the HTTPRouteRule
-  # do not use it on AuthPolicies that target a Gateway
+  # Selectors of HTTPRouteRules within the targeted HTTPRoute that activate the AuthPolicy.
+  # Each element contains a HTTPRouteMatch object that will be used to select HTTPRouteRules that include at least
+  # one identical HTTPRouteMatch.
+  # The HTTPRouteMatch part does not have to be fully identical, but the what's stated in the selector must be
+  # identically stated in the HTTPRouteRule.
+  # Do not use it on AuthPolicies that target a Gateway.
   routeSelectors:
   - matches:
     - path:
         type: PathPrefix
         value: "/admin"
 
-  # (optional) additional dynamic conditions to trigger the AuthPolicy.
-  # use it for filterring attributes not supported by HTTPRouteRule or with AuthPolicies that target a Gateway
-  # check out Kuadrant RFC 0002 (https://github.com/Kuadrant/architecture/blob/main/rfcs/0002-well-known-attributes.md) to learn more about the Well-known Attributes that can be used in this field
+  # Additional dynamic conditions to trigger the AuthPolicy.
+  # Use it for filterring attributes not supported by HTTPRouteRule or with AuthPolicies that target a Gateway.
+  # Check out https://github.com/Kuadrant/architecture/blob/main/rfcs/0002-well-known-attributes.md to learn more
+  # about the Well-known Attributes that can be used in this field.
   when: […]
 
-  # the auth rules to apply to the network traffic routed through the targeted resource
+  # The auth rules to apply to the network traffic routed through the targeted resource
   rules:
-    # (optional) authentication rules to enforce.
-    # at least one config must evaluate to a valid identity object for the auth request to be successful.
-    # if omitted or empty, anonymous access is assumed.
+    # Authentication rules to enforce.
+    # At least one config must evaluate to a valid identity object for the auth request to be successful.
+    # If omitted or empty, anonymous access is assumed.
     authentication:
       "my-authn-rule":
-        # the authentication method of this rule
-        # one-of: apiKey, jwt, oauth2Introspection, kubernetesTokenReview, x509, plain, anonymous
+        # The authentication method of this rule.
+        # One-of: apiKey, jwt, oauth2Introspection, kubernetesTokenReview, x509, plain, anonymous.
         apiKey: {…}
 
-        # (optional) where credentials are required to be passed in the request for authentication based on this rule
-        # one-of: authorizationHeader, customHeader, queryString, cookie
+        # Where credentials are required to be passed in the request for authentication based on this rule.
+        # One-of: authorizationHeader, customHeader, queryString, cookie.
         credentials:
           authorizationHeader:
             prefix: APIKEY
 
-        # (optional) rule-level route selectors
+        # Rule-level route selectors.
         routeSelectors: […]
 
-        # (optional) rule-level additional conditions
+        # Rule-level additional conditions.
         when: […]
 
-        # (optional) configs for caching the resolved object returned out of evaluating this auth rule
+        # Configs for caching the resolved object returned out of evaluating this auth rule.
         cache: {…}
 
-    # (optional) rules for fetching auth metadata from external sources.
+    # Rules for fetching auth metadata from external sources.
     metadata:
       "my-external-source":
-        # the method for fetching metadata from the external source
-        # one-of: http: userInfo, uma
+        # The method for fetching metadata from the external source.
+        # One-of: http: userInfo, uma.
         http: {…}
 
-    # (optional) authorization rules to enforce.
-    # all policies must allow access for the auth request be successful.
+    # Authorization rules to enforce.
+    # All policies must allow access for the auth request be successful.
     authorization:
       "my-authz-rule":
-        # the authorization method of this rule
-        # one-of: patternMatching, opa, kubernetesSubjectAccessReview, spicedb
+        # The authorization method of this rule.
+        # One-of: patternMatching, opa, kubernetesSubjectAccessReview, spicedb.
         opa: {…}
 
-    # (optional) customizations to the authorization response
+    # Customizations to the authorization response.
     response:
-      # custom denial status and other HTTP attributes for unauthenticated requests.
+      # Custom denial status and other HTTP attributes for unauthenticated requests.
       unauthenticated: {…}
 
-      # custom denial status and other HTTP attributes for unauhtorized requests.
+      # Custom denial status and other HTTP attributes for unauhtorized requests.
       unauthorized: {…}
 
-      # custom response items when access is granted.
+      # Custom response items when access is granted.
       success:
-        # custom response items wrapped as HTTP headers to be injected in the request
+        # Custom response items wrapped as HTTP headers to be injected in the request
         headers:
           "my-custom-header":
-            # one-of: plain, json, wristband
+            # One-of: plain, json, wristband.
             plain: {…}
 
-        # custom response items wrapped as envoy dynamic metadata
+        # Custom response items wrapped as envoy dynamic metadata.
         dynamicMetadata:
-          # one-of: plain, json, wristband
+          # One-of: plain, json, wristband.
           "my-custom-dyn-metadata":
             json: {…}
 
-    # (optional) rules for post-authorization callback requests to external services.
-    # triggered regardless of the result of the authorization request.
+    # Rules for post-authorization callback requests to external services.
+    # Triggered regardless of the result of the authorization request.
     callbacks:
       "my-webhook":
         http: {…}

diff --git a/doc/rate-limiting.md b/doc/rate-limiting.md
@@ -2,10 +2,10 @@
 
 A Kuadrant RateLimitPolicy custom resource, often abbreviated "RLP":
 
-1. Allows it to target Gateway API networking resources such as [HTTPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute) and [Gateways](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway), using these resources to obtain additional context, i.e., which traffic workload (HTTP attributes, hostnames, user attributes, etc) to rate limit.
-2. Allows to specify which specific subsets of the targeted network resource to apply the limits to.
+1. Targets Gateway API networking resources such as [HTTPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute) and [Gateways](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway), using these resources to obtain additional context, i.e., which traffic workload (HTTP attributes, hostnames, user attributes, etc) to rate limit.
+2. Supports targeting subsets (sections) of a network resource resource to apply the limits to.
 3. Abstracts the details of the underlying Rate Limit protocol and configuration resources, that have a much broader remit and surface area.
-4. Supports cluster operators to set overrides (soon) and defaults that govern what can be done at the lower levels.
+4. Enables cluster operators to set defaults that govern behavior at the lower levels of the network, until a more specific policy is applied.
 
 ## How it works
 

diff --git a/doc/reference/authpolicy.md b/doc/reference/authpolicy.md
@@ -9,7 +9,7 @@
     - [AuthorizationRule](#authorizationrule)
     - [ResponseSpec](#responsespec)
       - [SuccessResponseSpec](#successresponsespec)
-      - [SuccessResponseItem](#successresponseitem)
+        - [SuccessResponseItem](#successresponseitem)
     - [CallbackRule](#callbackrule)
   - [NamedPattern](#namedpattern)
 - [AuthPolicyStatus](#authpolicystatus)
@@ -102,7 +102,7 @@
 | `headers`         | Map<String: [SuccessResponseItem](#successresponseitem)> | No           | Custom success response items wrapped as HTTP headers to be injected in the request.                                                              |
 | `dynamicMetadata` | Map<String: [SuccessResponseItem](#successresponseitem)> | No           | Custom success response items wrapped as Envoy Dynamic Metadata. Use it to pass data along to other proxy filters, such as the rate-limit filter. |
 
-##### SuccessResponseItem
+###### SuccessResponseItem
 
 | **Field**   | **Type**                                                                                                                                                             | **Required** | **Description**                                                                                                                                                               |
 |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|