Updating docs to seperate api/references from concepts to be inline w…

…ith the new doc changes Signed-off-by: R-Lawton <[email protected]>
Kuadrant · Jan 14, 2025 · 530dae9 · 530dae9
1 parent 31587f8
commit 530dae9
Show file tree

Hide file tree

Showing 7 changed files with 248 additions and 243 deletions.
diff --git a/doc/overviews/auth.md b/doc/overviews/auth.md
@@ -42,130 +42,6 @@ Each auth rule can declare specific `when` conditions for the rule to apply.
 
 The auth scheme (`rules`), as well as conditions and named patterns can be declared at the top-level level of the spec (with the semantics of _defaults_) or alternatively within explicit `defaults` or `overrides` blocks.
 
-#### High-level example and field definition
-
-```yaml
-apiVersion: kuadrant.io/v1
-kind: AuthPolicy
-metadata:
-  name: my-auth-policy
-spec:
-  # Reference to an existing networking resource to attach the policy to. REQUIRED.
-  # 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
-
-  # Additional dynamic conditions to trigger the AuthPolicy.
-  # Use it for filtering 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.
-  # Equivalent to if otherwise declared within `defaults`.
-  when: […]
-
-  # Sets of common patterns of selector-operator-value triples, to be referred by name in `when` conditions
-  # and pattern-matching rules. Often employed to avoid repetition in the policy.
-  # Equivalent to if otherwise declared within `defaults`.
-  patterns: { … }
-
-  # The auth rules to apply to the network traffic routed through the targeted resource.
-  # Equivalent to if otherwise declared within `defaults`.
-  rules:
-    # 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.
-        apiKey: { … }
-
-        # 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
-
-        # Rule-level additional conditions.
-        when: […]
-
-        # Configs for caching the resolved object returned out of evaluating this auth rule.
-        cache: { … }
-
-    # 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.
-        http: { … }
-
-    # 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.
-        opa: { … }
-
-    # Customizations to the authorization response.
-    response:
-      # Custom denial status and other HTTP attributes for unauthenticated requests.
-      unauthenticated: { … }
-
-      # Custom denial status and other HTTP attributes for unauhtorized requests.
-      unauthorized: { … }
-
-      # Custom response items when access is granted.
-      success:
-        # Custom response items wrapped as HTTP headers to be injected in the request
-        headers:
-          "my-custom-header":
-            # One-of: plain, json, wristband.
-            plain: { … }
-
-        # Custom response items wrapped as envoy dynamic metadata.
-        dynamicMetadata:
-          # One-of: plain, json, wristband.
-          "my-custom-dyn-metadata":
-            json: { … }
-
-    # Rules for post-authorization callback requests to external services.
-    # Triggered regardless of the result of the authorization request.
-    callbacks:
-      "my-webhook":
-        http: { … }
-
-    # Explicit defaults. Used in policies that target a Gateway object to express default rules to be enforced on
-    # routes that lack a more specific policy attached to.
-    # Mutually exclusive with `overrides` and with declaring the `rules`, `when` and `patterns` at the top-level of
-    # the spec.
-    defaults:
-      rules:
-        authentication: { … }
-        metadata: { … }
-        authorization: { … }
-        response: { … }
-        callbacks: { … }
-      when: […]
-      patterns: { … }
-
-    # Overrides. Used in policies that target a Gateway object to be enforced on all routes linked to the gateway,
-    # thus also overriding any more specific policy occasionally attached to any of those routes.
-    # Mutually exclusive with `defaults` and with declaring `rules`, `when` and `patterns` at the top-level of
-    # the spec.
-    overrides:
-      rules:
-        authentication: { … }
-        metadata: { … }
-        authorization: { … }
-        response: { … }
-        callbacks: { … }
-      when: […]
-      patterns: { … }
-```
-
 Check out the [API reference](../reference/authpolicy.md) for a full specification of the AuthPolicy CRD.
 
 ## Using the AuthPolicy

diff --git a/doc/overviews/dns.md b/doc/overviews/dns.md
@@ -2,11 +2,11 @@
 
 A Kuadrant DNSPolicy custom resource:
 
-1. Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) to provide dns management by managing the lifecycle of dns records in external dns providers such as AWS Route53 and Google DNS.
+Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) to provide dns management by managing the lifecycle of dns records in external dns providers such as AWS Route53 and Google DNS.
 
 ## How it works
 
-A DNSPolicy and its targeted Gateway API networking resource contain all the statements to configure both the ingress gateway and the external DNS service. 
+A DNSPolicy and its targeted Gateway API networking resource contain all the statements to configure both the ingress gateway and the external DNS service.
 The needed dns names are gathered from the listener definitions and the IPAdresses | CNAME hosts are gathered from the status block of the gateway resource.
 
 ### The DNSPolicy custom resource
@@ -15,74 +15,22 @@ The needed dns names are gathered from the listener definitions and the IPAdress
 
 The `DNSPolicy` spec includes the following parts:
 
-* A reference to an existing Gateway API resource (`spec.targetRef`)
-* LoadBalancing specification (`spec.loadBalancing`)
-* HealthCheck specification (`spec.healthCheck`)
-
-#### High-level example and field definition
-
-```yaml
-apiVersion: kuadrant.io/v1
-kind: DNSPolicy
-metadata:
-  name: my-dns-policy
-spec:
-  # reference to an existing networking resource to attach the policy to
-  # it can only be a Gateway API Gateway resource
-  # it can only refer to objects in the same namespace as the DNSPolicy
-  # it can target a specific listener using sectionName 
-  targetRef:
-    group: gateway.networking.k8s.io
-    kind: Gateway
-    name: mygateway
-    sectionName: api # (optional) if not set policy applies to all listeners that do not have a policy attached directly
-
- # reference to an existing secret resource containing provider credentials and configuration
- # it can only refer to Secrets in the same namespace as the DNSPolicy that have the type kuadrant.io/(provider) e.g kuadrant.io/aws
-  providerRefs:
-   - name: my-aws-credentials
-
-  # (optional) loadbalancing specification
-  # use it for providing the specification of how dns will be configured in order to provide balancing of requests across multiple clusters. If not configured, a simple A or CNAME record will be created. If you have a policy with no loadbalancing defined and want to move to a loadbalanced configuration, you will need to delete and re-create the policy.
-  loadBalancing:
-    # is this the default geo to be applied to records. It is important that you set the default geo flag to true **Only** for the GEO value you wish to act as the catchall GEO, you should not set multiple GEO values as default for a given targeted listener. Example: policy 1 targets listener 1 with a geo of US and sets default to true. Policy 2 targets a listener on another cluster and set the geo to EU and default to false. It is fine for policies in the same default GEO to set the value to true. The main thing is to have only one unique GEO set as the default for any shared listener hostname.
-    defaultGeo: true
-    # weighted specification. This will apply the given weight to the records created based on the targeted gateway listeners. If you have multiple gateways that share a listener host, you can set different weight values to influence how much traffic will be brought to a given gateway.
-    weight: 100
-    # This is the actual GEO location to set for records created by this policy. This can and should be different if you have multiple gateways across multiple geographic areas. 
-
-    # AWS: To see all regions supported by AWS Route 53, please see the official (documentation)[https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-geo.html]. With Route 53 when setting a continent code use a "GEO-" prefix otherwise it will be considered a country code. 
-
-    # GCP: To see all regions supported by GCP Cloud DNS, please see the official (documentation)[https://cloud.google.com/compute/docs/regions-zones]
-
-    #To see the different values you can use for the geo based DNS with Azure take a look at the following (documentation)[https://learn.microsoft.com/en-us/azure/traffic-manager/traffic-manager-geographic-regions]
-    geo: IE
-
-  # (optional) health check specification
-  # health check probes with the following specification will be created for each DNS target, these probes constantly check that the endpoint can be reached. They will flag an unhealthy endpoint in the status. If no DNSRecord has yet been published and the endpoint is unhealthy, the record will not be published until the health check passes.
-  healthCheck:
-    # the path on the listener host(s) that you want to check. 
-    path: /health
-    # how many times does the health check need to fail before unhealthy.
-    failureThreshold: 3
-    # how often should it be checked.
-    interval: 5min
-    # additionalHeadersRef is reference to a local secret with a set of key value pairs to be used as headers when sending the health check request.
-    additionalHeadersRef:
-      name: headers
-```
+- A reference to an existing Gateway API resource (`spec.targetRef`)
+- LoadBalancing specification (`spec.loadBalancing`)
+- HealthCheck specification (`spec.healthCheck`)
 
 Check out the [API reference](../reference/dnspolicy.md) for a full specification of the DNSPolicy CRD.
 
 ## Using the DNSPolicy
 
 ### DNS Provider Setup
 
-A DNSPolicy acts against a target Gateway by processing its listeners for hostnames that it can create dns records for. 
+A DNSPolicy acts against a target Gateway by processing its listeners for hostnames that it can create dns records for.
 In order for it to do this, it must know about the dns provider.
 This is done through the creation of dns provider secrets containing the credentials and configuration for the dns provider account.
 
 If for example a Gateway is created with a listener with a hostname of `echo.apps.hcpapps.net`:
+
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
@@ -114,7 +62,7 @@ data:
 type: kuadrant.io/aws
 ```
 
-By default, Kuadrant will list the available zones and find the matching zone based on the listener host in the gateway listener. If it finds more than one matching zone for a given listener host, it will not update any of those zones. 
+By default, Kuadrant will list the available zones and find the matching zone based on the listener host in the gateway listener. If it finds more than one matching zone for a given listener host, it will not update any of those zones.
 When providing a credential you should limit that credential down to just have write access to the zones you want Kuadrant to manage. Below is an example of a an AWS policy for doing this type of thing:
 
 ```
@@ -162,7 +110,6 @@ When providing a credential you should limit that credential down to just have w
 }
 ```
 
-
 ### Targeting a Gateway networking resource
 
 When a DNSPolicy targets a Gateway, the policy will be enforced on all gateway listeners.
@@ -198,13 +145,12 @@ spec:
     sectionName: <myListenerName>
 ```
 
-
-
 ### DNSRecord Resource
 
 The DNSPolicy will create a DNSRecord resource for each listener hostname. The DNSPolicy resource uses the status of the Gateway to determine what dns records need to be created based on the clusters it has been placed onto.
 
 Given the following multi cluster gateway status:
+
 ```yaml
 status:
   addresses:
@@ -220,12 +166,13 @@ status:
     - attachedRoutes: 1
       conditions: []
       name: kind-mgc-workload-2.api
-      supportedKinds: []        
+      supportedKinds: []
 ```
 
 A DNSPolicy targeting this gateway would create an appropriate DNSRecord based on the routing strategy selected.
 
 #### loadbalanced
+
 ```yaml
 apiVersion: kuadrant.io/v1alpha1
 kind: DNSRecord
@@ -291,6 +238,7 @@ lrnse3.lb-2903yb.echo.apps.hcpapps.net.
 ```
 
 #### simple
+
 ```yaml
 apiVersion: kuadrant.io/v1alpha1
 kind: DNSRecord
@@ -306,7 +254,7 @@ spec:
         - 172.31.201.1
         - 172.31.202.1
   providerRefs:
-   - name: my-aws-credentials 
+    - name: my-aws-credentials
 ```
 
 After DNSRecord reconciliation the listener hostname should be resolvable through dns:

diff --git a/doc/overviews/rate-limiting.md b/doc/overviews/rate-limiting.md
@@ -44,53 +44,8 @@ The limit definitions (`limits`) can be declared at the top-level level of the s
   </tbody>
 </table>
 
-#### High-level example and field definition
+Check out the [API reference](../reference/ratelimitpolicy.md) for a full specification of the RateLimitPolicy CRD.
 
-```yaml
-apiVersion: kuadrant.io/v1
-kind: RateLimitPolicy
-metadata:
-  name: my-rate-limit-policy
-spec:
-  # Reference to an existing networking resource to attach the policy to. REQUIRED.
-  # It can be a Gateway API HTTPRoute or Gateway resource.
-  # It can only refer to objects in the same namespace as the RateLimitPolicy.
-  targetRef:
-    group: gateway.networking.k8s.io
-    kind: HTTPRoute / Gateway
-    name: myroute / mygateway
-
-  # The limits definitions to apply to the network traffic routed through the targeted resource.
-  # Equivalent to if otherwise declared within `defaults`.
-  limits:
-    "my_limit":
-      # The rate limits associated with this limit definition. REQUIRED.
-      # E.g., to specify a 50rps rate limit, add `{ limit: 50, duration: 1, unit: secod }`
-      rates: […]
-
-      # Counter qualifiers.
-      # Each dynamic value in the data plane starts a separate counter, combined with each rate limit.
-      # E.g., to define a separate rate limit for each user name detected by the auth layer, add `metadata.filter_metadata.envoy\.filters\.http\.ext_authz.username`.
-      # 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.
-      counters: […]
-
-      # Additional dynamic conditions to trigger the limit.
-      # Use it for filtering attributes not supported by HTTPRouteRule or with RateLimitPolicies 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.
-      when: […]
-
-    # Explicit defaults. Used in policies that target a Gateway object to express default rules to be enforced on
-    # routes that lack a more specific policy attached to.
-    # Mutually exclusive with `overrides` and with declaring `limits` at the top-level of the spec.
-    defaults:
-      limits: { … }
-
-    # Overrides. Used in policies that target a Gateway object to be enforced on all routes linked to the gateway,
-    # thus also overriding any more specific policy occasionally attached to any of those routes.
-    # Mutually exclusive with `defaults` and with declaring `limits` at the top-level of the spec.
-    overrides:
-      limits: { … }
-```
 
 ## Using the RateLimitPolicy