WIP

Signed-off-by: R-Lawton <[email protected]>

doc/apis-overview/tls.md

@@ -2,7 +2,7 @@
 
 A Kuadrant TLSPolicy 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 tls for gateway listeners by managing the lifecycle of tls certificates using [`CertManager`](https://cert-manager.io).
+Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) to provide tls for gateway listeners by managing the lifecycle of tls certificates using [`CertManager`](https://cert-manager.io).
 
 ## How it works
 

doc/install/install-kubernetes.md

@@ -1,11 +1,9 @@
 # Install Kuadrant on a Kubernetes cluster
 
-!!! note
-
+>**Note:**
     You must perform these steps on each Kubernetes cluster where you want to use Kuadrant.
 
-!!! warning
-
+>**Warning:**
     Kuadrant uses a number of labels to search and filter resources on the cluster.
     All required labels are formatted as `kuadrant.io/*`.
     Removal of any labels with the prefix may cause unexpected behaviour and degradation of the product.
@@ -30,8 +28,7 @@ kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/downloa
 
 ### Install [OLM](https://olm.operatorframework.io/)
 
-!!! note
-
+>**Note:**
     Currently, we recommend installing our operator via OLM. We plan to support Helm soon.
 
 ```bash
@@ -40,13 +37,11 @@ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releas
 
 ### (Optional) Install Istio as a Gateway API provider
 
-!!! note
-
+>**Warning:**
     Skip this step if planing to use [Envoy Gateway](https://gateway.envoyproxy.io/) as Gateway API provider
 
-!!! note
 
-    There are several ways to install Istio (via `istioctl`, Helm chart or Operator) - this is just an example for starting from a bare Kubernetes cluster.
+There are several ways to install Istio (via `istioctl`, Helm chart or Operator) - this is just an example for starting from a bare Kubernetes cluster.
 
 ```bash
 curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.5 sh -
@@ -57,13 +52,10 @@ kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/ma
 
 ### (Optional) Install Envoy Gateway as a Gateway API provider
 
-!!! note
-
+>**Warning:**
     Skip this step if planing to use [Istio](https://istio.io/) as Gateway API provider
 
-!!! note
-
-    There are several ways to install Envoy Gateway (via `egctl`, Helm chart or Kubernetes yaml) - this is just an example for starting from a bare Kubernetes cluster.
+There are several ways to install Envoy Gateway (via `egctl`, Helm chart or Kubernetes yaml) - this is just an example for starting from a bare Kubernetes cluster.
 
 ```bash
 helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.1.0 -n envoy-gateway-system --create-namespace

doc/reference/ratelimitpolicy.md

@@ -11,11 +11,31 @@
 
 | **Field**   | **Type**                                                                                                                                    | **Required** | **Description**                                                                                                                                                                             |
 |-------------|---------------------------------------------------------------------------------------------------------------------------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `targetRef` | [LocalPolicyTargetReference](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.LocalPolicyTargetReference) | Yes          | Reference to a Kubernetes resource that the policy attaches to                                                                                                                              |
+| `targetRef` | [LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname) | Yes          | Reference to a Kubernetes resource that the policy attaches to. For more [info](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.LocalPolicyTargetReference)                                                                                                                              |
 | `defaults`  | [RateLimitPolicyCommonSpec](#rateLimitPolicyCommonSpec)                                                                                     | No           | Default limit definitions. This field is mutually exclusive with the `limits` field                                                                                                         |
 | `overrides` | [RateLimitPolicyCommonSpec](#rateLimitPolicyCommonSpec)                                                                                     | No           | Overrides limit definitions. This field is mutually exclusive with the `limits` field and `defaults` field. This field is only allowed for policies targeting `Gateway` in `targetRef.kind` |
 | `limits`    | Map<String: [Limit](#limit)>                                                                                                                | No           | Limit definitions. This field is mutually exclusive with the [`defaults`](#rateLimitPolicyCommonSpec) field                                                                                 |
 
+
+
+
+### LocalPolicyTargetReferenceWithSectionName
+| **Field**       | **Type**                                | **Required** | **Description**                                            |
+|------------------|-----------------------------------------|--------------|------------------------------------------------------------|
+| `LocalPolicyTargetReference`         | [LocalPolicyTargetReference](#localpolicytargetreference)          | Yes          | Reference to a local policy target.               |
+| `sectionName`    | [SectionName](#sectionname)                         | No           | Section name for further specificity (if needed). |
+
+### LocalPolicyTargetReference
+| **Field** | **Type**     | **Required** | **Description**                |
+|-----------|--------------|--------------|--------------------------------|
+| `group`   | `Group`      | Yes          | Group of the target resource. |
+| `kind`    | `Kind`       | Yes          | Kind of the target resource.  |
+| `name`    | `ObjectName` | Yes          | Name of the target resource.  |
+
+### SectionName
+| Field       | Type                     | Required | Description                                                                                                                                                                                                                         |
+|-------------|--------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| SectionName | v1.SectionName (String)  | Yes      | SectionName is the name of a section in a Kubernetes resource. <br>In the following resources, SectionName is interpreted as the following: <br>* Gateway: Listener name<br>* HTTPRoute: HTTPRouteRule name<br>* Service: Port name |
 ### RateLimitPolicyCommonSpec
 
 | **Field** | **Type**                     | **Required** | **Description**                                                                                                              |

doc/user-guides/dns/dns-excluding-specific-addresses.md

@@ -8,7 +8,7 @@ To prevent a gateway address being published to the DNS provider, you can set th
 
 Below is an example of a DNSPolicy excluding a hostname:
 
-```
+```sh
 apiVersion: kuadrant.io/v1
 kind: DNSPolicy
 metadata:

doc/user-guides/dns/gateway-dns.md

@@ -2,46 +2,32 @@
 
 This user guide walks you through an example of how to configure DNS for all routes attached to an ingress gateway.
 
-<br/>
-
 ## Requisites
 
 - [Docker](https://docker.io)
 - [Rout53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html)
 
-### Setup
-
-This step uses tooling from the Kuadrant Operator component to create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io),
-where it installs Istio, Kubernetes Gateway API and Kuadrant itself.
-
-Clone the project:
-
-```shell
-git clone https://github.com/Kuadrant/kuadrant-operator && cd kuadrant-operator
-```
-
-Setup the environment:
+### Setup the environment
 
-```shell
-make local-setup
-```
+Follow this [setup doc](https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/install/install-make-target.md) to set up your environment before continuing with this doc.
 
 Create a namespace:
+
 ```shell
 kubectl create namespace my-gateways
 ```
 
 Export a root domain and hosted zone id:
+
 ```shell
 export ROOT_DOMAIN=<ROOT_DOMAIN>
 ```
 
-> **Note:** ROOT_DOMAIN should be set to your AWS hosted zone *name*.
+> **Note:** ROOT_DOMAIN should be set to your AWS hosted zone _name_.
 
 ### Create a dns provider secret
 
-Create AWS provider secret. You should limit the permissions of this credential to only the zones you want us to access. 
-
+Create AWS provider secret. You should limit the permissions of this credential to only the zones you want us to access.
 
 ```shell
 export AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
@@ -55,6 +41,7 @@ kubectl -n my-gateways create secret generic aws-credentials \
 ### Create an ingress gateway
 
 Create a gateway using your ROOT_DOMAIN as part of a listener hostname:
+
 ```sh
 kubectl -n my-gateways apply -f - <<EOF
 apiVersion: gateway.networking.k8s.io/v1
@@ -75,10 +62,13 @@ EOF
 ```
 
 Check gateway status:
+
 ```shell
 kubectl get gateway prod-web -n my-gateways
 ```
+
 Response:
+
 ```shell
 NAME       CLASS   ADDRESS        PROGRAMMED   AGE
 prod-web   istio   172.18.200.1   True         25s
@@ -87,6 +77,7 @@ prod-web   istio   172.18.200.1   True         25s
 ### Enable DNS on the gateway
 
 Create a Kuadrant `DNSPolicy` to configure DNS:
+
 ```shell
 kubectl -n my-gateways apply -f - <<EOF
 apiVersion: kuadrant.io/v1
@@ -102,10 +93,13 @@ EOF
 ```
 
 Check policy status:
+
 ```shell
 kubectl get dnspolicy -o wide -n my-gateways
 ```
+
 Response:
+
 ```shell
 NAME       STATUS     TARGETREFKIND   TARGETREFNAME   AGE
 prod-web   Accepted   Gateway         prod-web        26s
@@ -114,12 +108,14 @@ prod-web   Accepted   Gateway         prod-web        26s
 ### Deploy a sample API to test DNS
 
 Deploy the sample API:
+
 ```shell
 kubectl -n my-gateways apply -f examples/toystore/toystore.yaml
 kubectl -n my-gateways wait --for=condition=Available deployments toystore --timeout=60s
 ```
 
 Route traffic to the API from our gateway:
+
 ```shell
 kubectl -n my-gateways apply -f - <<EOF
 apiVersion: gateway.networking.k8s.io/v1
@@ -140,6 +136,7 @@ EOF
 ```
 
 Verify a DNSRecord resource is created:
+
 ```shell
 kubectl get dnsrecords -n my-gateways
 NAME           READY
@@ -149,10 +146,13 @@ prod-web-api   True
 ### Verify DNS works by sending requests
 
 Verify DNS using dig:
+
 ```shell
 dig foo.$ROOT_DOMAIN +short
 ```
+
 Response:
+
 ```shell
 172.18.200.1
 ```
@@ -162,7 +162,9 @@ Verify DNS using curl:
 ```shell
 curl http://api.$ROOT_DOMAIN
 ```
+
 Response:
+
 ```shell
 {
   "method": "GET",

doc/user-guides/dns/orphan-dns-records.md

@@ -24,33 +24,37 @@ On cluster 2 the DNS Operator managing the existing DNSRecord in that cluster ha
 In prometheus alerts, it spots that the number of owners does not correlate to the number of DNSRecord resources and triggers an alert. 
 To remedy this rather than going to the DNS provider directly and trying to figure out which records to remove, you can instead follow the steps below.
 
-1) Get the owner id of the DNSRecord on cluster 2 for the shared host 
+Get the owner id of the DNSRecord on cluster 2 for the shared host 
 
-```
+```sh
 kubectl get dnsrecord somerecord -n my-gateway-ns -o=jsonpath='{.status.ownerID}'
 ```
 
-2) get all the owner ids
+Get all the owner ids
 
-```
+```sh
 kubectl get dnsrecord.kuadrant.io somerecord -n my-gateway-ns -o=jsonpath='{.status.domainOwners}'
 
-## output
-["26aacm1z","49qn0wp7"]
+# output
+# ["26aacm1z","49qn0wp7"]
 ```
 
-3) create a placeholder DNSRecord with none active ownerID
+Create a placeholder DNSRecord with none active ownerID
 
 
-for each owner id returned that isn't the owner id of the record we got earlier that we want to remove records for, we need to create a dnsrecord resource and delete it. This will trigger the running operator in this cluster to clean up those records.
+For each owner id returned that isn't the owner id of the record that we want to remove records for, we need to create a dnsrecord resource and delete it. This will trigger the running operator in this cluster to clean up those records.
+
+This is one of the owner id **not** in the existing dnsrecord on cluster
+```sh
 
-```
-# this is one of the owner id **not** in the existing dnsrecord on cluster
 export ownerID=26aacm1z  
 
 export rootHost=$(kubectl get dnsrecord.kuadrant.io somerecord -n  my-gateway-ns -o=jsonpath='{.spec.rootHost}')
+```
+
 
-# export a namespace with the aws credentials in it
+Export a namespace with the aws credentials in it
+```sh
 export targetNS=kuadrant-system 
 
 kubectl apply -f - <<EOF
@@ -74,21 +78,21 @@ EOF
 
 ```
 
-4) Delete the dnsrecord
+Delete the DNSrecord
 
-```
+```sh
 kubectl delete dnsrecord.kuadrant.io delete-old-loadbalanced-dnsrecord -n ${targetNS} 
 ```
 
-5) verify 
+Verification 
 
-We can verify by checking the dnsrecord again. Note it may take a several minutes for the other record to update. We can force it by adding a label to the record
+We can verify that the steps worked correctly, by checking the DNSRecord again. Note it may take a several minutes for the other record to update. We can force it by adding a label to the record
 
-```
+```sh
 kubectl label dnsrecord.kuadrant.io somerecord test=test -n ${targetNS}
 
 kubectl get dnsrecord.kuadrant.io somerecord -n my-gateway-ns -o=jsonpath='{.status.domainOwners}'
 
 ```
 
-We should also see our alert eventually stop triggering.
+You should also see your alert eventually stop triggering.

doc/user-guides/dnspolicy/basic-dns-configuration.md

@@ -87,7 +87,7 @@ spec:
 
 This resource also needs to be created in the same namespace as your Gateway and the `targetRef` needs to reference your gateway. When this is done we can check the status of the DNSPolicy and the Gateway to check when it is ready.
 
-```
+```sh
 kubectl wait dnspolicy/basic-dnspolicy -n my-gateway-namespace --for="condition=Ready=true" --timeout=300s
 
 ```
@@ -105,7 +105,7 @@ If you look at the gateway status you should also see:
 
 DNS is now setup for your Gateway. After allowing a little time for the DNS propagate to the nameservers, you should be able to test the DNS using a dig command alternatively you can curl your endpoint.
 
-```
+```sh
 dig test.example.com +short
 
 curl -v test.example.com/toy

doc/user-guides/dnspolicy/dnshealthchecks.md

@@ -130,7 +130,7 @@ If one or more of the health checks are failing you will see a status in the DNS
 
 Finally, you can also take a look at the underlying individual health check status by inspecting the `dnshealthcheckprobe` resource:
 
->Note: These resources are for view only interactions as they are controlled by the Kuadrant Operator based on the DNSPolicy API
+>**Note**: These resources are for view only interactions as they are controlled by the Kuadrant Operator based on the DNSPolicy API
 
 ```bash
 kubectl get dnshealthcheckprobes n my-dns-policy-namespace -o=wide

doc/user-guides/full-walkthrough/secure-protect-connect-single-multi-cluster.md → doc/user-guides/full-walkthrough/secure-protect-connect-openshift.md

@@ -68,8 +68,8 @@ kubectl create ns ${gatewayNS}
 
 Create the secret credentials as follows:
 
-```
-kubectl -n ${gatewayNS} create secret generic aws-credentials \
+```sh
+kubectl -n cert-manager create secret generic aws-credentials \
   --type=kuadrant.io/aws \
   --from-literal=AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
   --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY

doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md → doc/user-guides/ratelimiting/authenticated-rl-for-app.md

@@ -1,4 +1,4 @@
-# Authenticated Rate Limiting for Application Developers
+# Authenticated Rate Limiting for Applications
 
 This user guide walks you through an example of how to configure authenticated rate limiting for an application using Kuadrant.