From 39ecfe8dbda2788facadea9fe3db220664fde084 Mon Sep 17 00:00:00 2001
From: Stephen McCarthy <29098561+smccarthy-ie@users.noreply.github.com>
Date: Mon, 13 May 2024 13:58:47 +0100
Subject: [PATCH] docs: add numbering to headers to help navigation and
 readability (#639)

* docs: add numbering to headers to help navigation and readability, minor edits

* docs: add line break to fix bullet list format on kuadrant docs site

* Update doc/user-guides/secure-protect-connect-single-multi-cluster.md

Co-authored-by: Craig Brookes <maleck13@users.noreply.github.com>

---------

Co-authored-by: Craig Brookes <maleck13@users.noreply.github.com>
---
 doc/install/install-openshift.md              |  98 ++++---
 ...re-protect-connect-single-multi-cluster.md | 241 ++++++++++--------
 doc/user-guides/secure-protect-connect.md     |   6 +-
 3 files changed, 194 insertions(+), 151 deletions(-)

diff --git a/doc/install/install-openshift.md b/doc/install/install-openshift.md
index fdb7d9da0..2a4992368 100644
--- a/doc/install/install-openshift.md
+++ b/doc/install/install-openshift.md
@@ -1,34 +1,39 @@
 # Install Kuadrant on an OpenShift cluster
 
-NOTE: You must perform these steps on each cluster that you want to use Kuadrant on.
+NOTE: You must perform these steps on each OpenShift cluster that you want to use Kuadrant on.
 
 ## Prerequisites
 
-- OpenShift Container Platform 4.14.x or later with community Operator catalog available
-- AWS account with Route 53 and zone 
-- Accessible Redis Instance
+- OpenShift Container Platform 4.14.x or later with community Operator catalog available.
+- AWS account with Route 53 and zone. 
+- Accessible Redis instance.
 
-## Set up your environment
+
+## Procedure
+
+### Step 1 - Set up your environment
 
 ```bash
 export AWS_ACCESS_KEY_ID=xxxxxxx # Key ID from AWS with Route 53 access
-export AWS_SECRET_ACCESS_KEY=xxxxxxx # Access Key from AWS with Route 53 access
+export AWS_SECRET_ACCESS_KEY=xxxxxxx # Access key from AWS with Route 53 access
 export REDIS_URL=redis://user:xxxxxx@some-redis.com:10340 # A Redis cluster URL
 ```
 
-## Install the dependencies
-
-Kuadrant integrates with Istio as a Gateway API provider. Before you can use Kuadrant, you must set up an Istio-based Gateway API provider. For this step, you will use the Sail Operator.
+### Step 2 - Install Gateway API v1
 
-### Install v1 of Gateway API:
+Before you can use Kuadrant, you must install Gateway API v1 as follows:
 
 ```bash
 kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
 ```
 
-### Install and configure Istio with the Sail Operator
+### Step 3 - Install and configure Istio with the Sail Operator
+
+Kuadrant integrates with Istio as a Gateway API provider. You can set up an Istio-based Gateway API provider by using the Sail Operator. 
+
+#### Install Istio
 
-To install Istio, run the following command:
+To install the Istio Gateway provider, run the following commands:
 
 ```bash
 kubectl create ns istio-system
@@ -58,7 +63,7 @@ spec:
 EOF
 ```
 
-To check the status of the install, you can run:
+Check the status of the installation as follows:
 
 ```bash
 kubectl get installplan -n istio-system -o=jsonpath='{.items[0].status.phase}'
@@ -68,6 +73,8 @@ When ready, the status will change from `installing` to `complete`.
 
 #### Configure Istio
 
+To configure the Istio Gateway API provider, run the following command:
+
 ```bash
 kubectl apply -f - <<EOF
 apiVersion: operator.istio.io/v1alpha1
@@ -84,53 +91,52 @@ spec:
 EOF
 ```
 
-Wait for Istio to be ready:
+Wait for Istio to be ready as follows:
 
 ```bash
 kubectl wait istio/default -n istio-system --for="condition=Ready=true"
 ```
 
+### Step 4 - Optional: Configure observability and metrics
 
-### Best practices for metrics and observability
-
-Kuadrant provides a set of sample dashboards that use known metrics exported by Kuadrant and Gateway components to provide insight into different areas of your APIs and Gateways. While not essential, it is best to set up an observability stack. This section provides links to OpenShift and Thanos documentation on configuring monitoring and metrics storage.
+Kuadrant provides a set of example dashboards that use known metrics exported by Kuadrant and Gateway components to provide insight into different components of your APIs and Gateways. While not essential, it is best to set up an OpenShift monitoring stack. This section provides links to OpenShift and Thanos documentation on configuring monitoring and metrics storage.
 
-OpenShift supports a user facing monitoring stack. This can be cofigured and setup this documentation:
+You can set up user-facing monitoring by following the steps in the OpenShift documentation on [configuring the monitoring stack](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html). 
 
-https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html
+If you have user workload monitoring enabled, it is best to configure remote writes to a central storage system such as Thanos:
 
-If you have user workload monitoring enabled. We Recommend configuring remote write to a central storage system such as Thanos:
-
-- [Remote Write Config](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html#configuring_remote_write_storage_configuring-the-monitoring-stack)
+- [OpenShift remote write configuration](https://docs.openshift.com/container-platform/latest/observability/monitoring/configuring-the-monitoring-stack.html#configuring_remote_write_storage_configuring-the-monitoring-stack)
 - [Kube Thanos](https://github.com/thanos-io/kube-thanos)
 
-There are a set of [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples/) for observing Kuadrant functionality.
-These dashboards and alerts make use of low level cpu, metrics and network metrics available from the user monitoring stack in Openshift. They also make use of resource state metrics from Gateway API and Kuadrant resources.
-To scrape these additional metrics, you can install a kube-state-metrics instance, with a custom resource config:
+The [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples/) for observing Kuadrant functionality use low-level CPU metrics and network metrics available from the user monitoring stack in OpenShift. They also use resource state metrics from Gateway API and Kuadrant resources. 
+
+To scrape these additional metrics, you can install a `kube-state-metrics instance`, with a custom resource configuration as follows:
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/observability/openshift/kube-state-metrics.yaml
 kubectl apply -k https://github.com/Kuadrant/gateway-api-state-metrics?ref=main
 ```
 
-To enable request metrics in Istio, you will need to create a Telemetry resource:
+To enable request metrics in Istio, you must create a `telemetry` resource as follows:
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/observability/openshift/telemetry.yaml
 ```
 
-The [dashboards](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples) can be imported into Grafana, if you have it installed in your cluster.
-You'll find an example of how to install Grafana on Openshift [here](https://cloud.redhat.com/experts/o11y/ocp-grafana/). Once installed, you will need to add your Thanos instance as a data source to Grafana. Alternatively, if you are just using the user workload monitoring stack in your Openshift cluster (and not writing metrics to an external thanos instance), you can set up a data source to the [thanos-querier route in the Openshift cluster](https://docs.openshift.com/container-platform/4.15/observability/monitoring/accessing-third-party-monitoring-apis.html#accessing-metrics-from-outside-cluster_accessing-monitoring-apis-by-using-the-cli).
+If you have Grafana installed in your cluster, you can import the [example dashboards and alerts](https://docs.kuadrant.io/kuadrant-operator/doc/observability/examples).
 
-### Install Kuadrant
+For example installation details, see [installing Grafana on OpenShift](https://cloud.redhat.com/experts/o11y/ocp-grafana/). When installed, you must add your Thanos instance as a data source to Grafana. Alternatively, if you are using only the user workload monitoring stack in your OpenShift cluster, and not writing metrics to an external Thanos instance, you can [set up a data source to the thanos-querier route in the OpenShift cluster](https://docs.openshift.com/container-platform/4.15/observability/monitoring/accessing-third-party-monitoring-apis.html#accessing-metrics-from-outside-cluster_accessing-monitoring-apis-by-using-the-cli).
 
-To install Kuadrant, use the Kuadrant Operator. Before installing, you will set up some secrets that you will use later:
+
+### Step 5 - Create secrets for your credentials 
+
+Before installing the Kuadrant Operator, you must enter the following commands to set up secrets that you will use later:
 
 ```bash
 kubectl create ns kuadrant-system
 ```
 
-Setup a catalogsource:
+Set up a `CatalogSource` as follows:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -150,7 +156,9 @@ spec:
 EOF      
 ```      
 
-AWS Route 53 credentials for TLS verification:
+#### AWS Route 53 credentials for TLS
+
+Set the AWS Route 53 credentials for TLS verification as follows:
 
 ```bash
 kubectl -n kuadrant-system create secret generic aws-credentials \
@@ -159,19 +167,23 @@ kubectl -n kuadrant-system create secret generic aws-credentials \
   --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
 ```
 
-Redis credentials for shared multicluster counters for Kuadrant's Limitador component:
+#### Redis credentials for rate limiting counters
+
+Set the Redis credentials for shared multicluster counters for the Kuadrant Limitador component as follows:
 
 ```bash
 kubectl -n kuadrant-system create secret generic redis-config \
   --from-literal=URL=$REDIS_URL  
 ```  
 
+#### AWS Route 53 credentials for DNS
+
+Set the AWS Route 53 credentials for managing DNS records as follows:
+
 ```bash
 kubectl create ns ingress-gateway
 ```
 
-AWS Route 53 credentials for managing DNS records:
-
 ```bash
 kubectl -n ingress-gateway create secret generic aws-credentials \
   --type=kuadrant.io/aws \
@@ -179,7 +191,9 @@ kubectl -n ingress-gateway create secret generic aws-credentials \
   --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
 ```  
 
-Finally, to install the Kuadrant Operator:
+### Step 6 - Install the Kuadrant Operator 
+
+To install the Kuadrant Operator, enter the following command:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -205,15 +219,17 @@ spec:
 EOF
 ```  
 
-Wait for Kuadrant Operators to be installed:
+Wait for the Kuadrant Operators to be installed as follows:
 
 ```bash
 kubectl get installplan -n kuadrant-system -o=jsonpath='{.items[0].status.phase}'
 ```
 
-After some time, this should return `complete`.
+After some time, this command should return `complete`.
+
+### Step 7 - Configure Kuadrant
 
-#### Configure Kuadrant
+To configure your Kuadrant deployment, enter the following command:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -231,7 +247,7 @@ spec:
 EOF          
 ```      
 
-Wait for Kuadrant to be ready:
+Wait for Kuadrant to be ready as follows:
 
 ```bash
 kubectl wait kuadrant/kuadrant --for="condition=Ready=true" -n kuadrant-system --timeout=300s
@@ -240,4 +256,4 @@ kubectl wait kuadrant/kuadrant --for="condition=Ready=true" -n kuadrant-system -
 Kuadrant is now ready to use.
 
 ## Next steps 
-- [Secure, protect, and connect APIs on single or multiple clusters](../user-guides/secure-protect-connect-single-multi-cluster.md)
+- [Secure, protect, and connect APIs with Kuadrant on OpenShift](../user-guides/secure-protect-connect-single-multi-cluster.md)
diff --git a/doc/user-guides/secure-protect-connect-single-multi-cluster.md b/doc/user-guides/secure-protect-connect-single-multi-cluster.md
index 8473f01f7..5801ad5eb 100644
--- a/doc/user-guides/secure-protect-connect-single-multi-cluster.md
+++ b/doc/user-guides/secure-protect-connect-single-multi-cluster.md
@@ -1,43 +1,46 @@
-# Secure, protect, and connect APIs with Kuadrant
+# Secure, protect, and connect APIs with Kuadrant on OpenShift
 
 ## Overview
 
-This guide walks you through using Kuadrant to secure, protect, and connect an API exposed by a Gateway using Kubernetes Gateway API. You can use this walkthrough for a Gateway on a single cluster or a Gateway distributed across multiple clusters with a shared listener hostname. This guide shows how specific user personas can each use Kuadrant to achieve their goals.
-
-## Prerequisites
-
-This guide expects that you have successfully installed Kuadrant on at least one cluster:
-- You have completed the steps in [Install Kuadrant on an OpenShift cluster](../install/install-openshift.md) for one or more clusters.
-- For multicluster scenarios, you have installed Kuadrant on at least two different clusters, and have a shared accessible Redis store.
-- `kubectl` command line tool is installed.
-- (Optional) User workload monitoring is configured to remote write to a central storage system such as Thanos (also covered in the installation steps).
+This guide walks you through using Kuadrant on OpenShift to secure, protect, and connect an API exposed by a Gateway that is based on Kubernetes Gateway API. You can use this walkthrough for a Gateway deployed on a single OpenShift cluster or a Gateway distributed across multiple OpenShift clusters with a shared listener hostname. This guide shows how the platform engineer and application developer user roles can each use Kuadrant to achieve their goals.
 
 ### What Kuadrant can do for you in a multicluster environment
 
 You can leverage Kuadrant's capabilities in single or multiple clusters. The following features are designed to work across multiple clusters as well as in a single-cluster environment.
 
-- **Multicluster ingress:** Kuadrant provides multicluster ingress connectivity using DNS to bring traffic to your Gateways using a strategy defined in a `DNSPolicy`. 
-- **Global rate limiting:** Kuadrant can enable global rate limiting use cases when configured to use a shared  Redis store for counters based on limits defined by a `RateLimitPolicy`.
-- **Global auth:** You can configure Kuadrant's `AuthPolicy` to leverage external auth providers to ensure different clusters exposing the same API are authenticating and authorizing in the same way. 
+- **Multicluster ingress:** Kuadrant provides multicluster ingress connectivity using DNS to bring traffic to your Gateways by using a strategy defined in a `DNSPolicy`. 
+- **Global rate limiting:** Kuadrant can enable global rate limiting use cases when configured to use a shared Redis store for counters based on limits defined by a `RateLimitPolicy`.
+- **Global auth:** You can configure a Kuadrant `AuthPolicy` to leverage external auth providers to ensure that different clusters exposing the same API authenticate and authorize in the same way. 
 - **Integration with federated metrics stores:** Kuadrant has example dashboards and metrics for visualizing your Gateways and observing traffic hitting those Gateways across multiple clusters. 
 
-**Platform engineer user**
+### User roles
+
+- **Platform engineer**: This guide walks you through deploying a Gateway that provides secure communication and is protected and ready for use by application development teams to deploy an API. It then walks through using this Gateway in clusters in different geographic regions, leveraging Kuadrant to bring specific traffic to your geo-located Gateways to reduce latency and distribute load, while still being protected and secured with global rate limiting and auth. 
+
+- **Application developer**: This guide walks through how you can use the Kuadrant OpenAPI Specification (OAS) extensions and `kuadrantctl` CLI to generate an `HTTPRoute` for your API and to add specific auth and rate limiting requirements.
 
-This guide walks you through deploying a Gateway that provides secure communication and is protected and ready for use by development teams to deploy an API. It then walks through using this Gateway in clusters in different geographic regions, leveraging Kuadrant to bring specific traffic to your geo-located Gateways to reduce latency and distribute load, while still being protected and secured with global rate limiting and auth.
+As an optional extra, this guide highlights how both user roles can observe and monitor these Gateways when the OpenShift user workload monitoring and observability stack is deployed. 
 
-As an optional extra this guide highlights how, with the user workload monitoring observability stack deployed, these Gateways can then be observed and monitored. 
+### Deployment management tooling
+
+While this document uses `kubectl` commands for simplicity, working with multiple clusters is complex, and it is best to use a tool such as Argo CD to manage the deployment of resources to multiple clusters.
+
+## Prerequisites
 
-**Application developer user**
+This guide expects that you have successfully installed Kuadrant on at least one OpenShift cluster:
 
-This guide walks through how you can use the Kuadrant OAS extensions and CLI to generate an `HTTPRoute` for your API and add specific auth and rate limiting requirements to your API.
+- You have completed the steps in [Install Kuadrant on an OpenShift cluster](../install/install-openshift.md) for one or more clusters.
+- For multicluster scenarios, you have installed Kuadrant on at least two different OpenShift clusters, and have a shared accessible Redis store.
+- You have the `kubectl` command line installed.
+- Optional: User workload monitoring is configured to remote write to a central storage system such as Thanos, as described in [Install Kuadrant on an OpenShift cluster](../install/install-openshift.md).
 
 ## Platform engineer workflow
 
-You must perform the following steps in each cluster individually unless specifically excluded. 
+NOTE: You must perform the following steps in each cluster individually, unless specifically excluded. 
 
-### Environment variables
+### Step 1 - Set your environment variables
 
-For convenience, this guide uses the following environment variables:
+Set the following environment variables used for convenience in this guide:
 ```bash
 export zid=change-this-to-your-zone-id
 export rootDomain=example.com
@@ -51,22 +54,19 @@ export clusterIssuerName=lets-encrypt
 export EMAIL=foo@example.com
 ```
 
-### Deployment management tooling
+### Step 2 - Set up a managed DNS zone
 
-While this document uses `kubectl`, working with multiple clusters is complex, and it is best to use a tool such as Argo CD to manage the deployment of resources to multiple clusters.
-### Set up a managed DNS zone
+The managed DNS zone declares a zone and credentials to access the zone that Kuadrant can use to set up DNS configuration.
 
-The managed DNS zone declares a zone and credentials to access that zone that Kuadrant can use to set up DNS configuration.
+#### Create the ManagedZone resource
 
-**Create the ManagedZone resource**
-
-Apply the following `ManagedZone` resource and aws credentials to each cluster or, if you are adding an additional cluster, add it to the new cluster:
+Apply the following `ManagedZone` resource and AWS credentials to each cluster. Alternatively, if you are adding an additional cluster, add it to the new cluster:
 
 ```bash
 kubectl create ns ${gatewayNS}
 ```
 
-Ensure the zone credential is created:
+Create the zone credentials as follows:
 
 ```
 kubectl -n ${gatewayNS} create secret generic aws-credentials \
@@ -76,7 +76,7 @@ kubectl -n ${gatewayNS} create secret generic aws-credentials \
 
 ```
 
-Then create a `ManagedZone`:
+Then create a `ManagedZone` as follows:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -94,17 +94,17 @@ spec:
 EOF
 ```
 
-Wait for the `ManagedZone` to be ready in your cluster(s):
+Wait for the `ManagedZone` to be ready in each cluster as follows:
 
 ```bash
 kubectl wait managedzone/managedzone --for=condition=ready=true -n ${gatewayNS}
 ```
 
-### Add a TLS issuer
+### Step 3 - Add a TLS issuer
 
 To secure communication to the Gateways, you will define a TLS issuer for TLS certificates. This example uses Let's Encrypt, but you can use any issuer supported by `cert-manager`.
 
-The following example uses Let's Encrypt staging, which should also be applied to all clusters.
+The following example uses Let's Encrypt staging, which you must also apply to all clusters:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -132,15 +132,15 @@ spec:
 EOF
 ```
 
-Then wait for the `ClusterIssuer` to become ready:
+Then wait for the `ClusterIssuer` to become ready as follows:
 
 ```bash
 kubectl wait clusterissuer/${clusterIssuerName} --for=condition=ready=true
 ```
 
-### Set up a Gateway
+### Step 4 - Set up a Gateway
 
-For Kuadrant to balance traffic using DNS across two or more clusters, you must define a Gateway with a shared host. You will define this by using an HTTPS listener with a wildcard hostname based on the root domain. As mentioned earlier, these resources must be applied to all clusters. 
+For Kuadrant to balance traffic using DNS across two or more clusters, you must define a Gateway with a shared host. You will define this by using an HTTPS listener with a wildcard hostname based on the root domain. As mentioned earlier, you must apply these resources to all clusters. 
 
 NOTE: For now, the Gateway is set to accept an `HTTPRoute` from the same namespace only. This allows you to restrict who can use the Gateway until it is ready for general use.
 
@@ -172,30 +172,30 @@ spec:
 EOF
 ```
 
-Check the status of your Gateway:
+Check the status of your Gateway as follows:
 
 ```bash
 kubectl get gateway ${gatewayName} -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}'
 kubectl get gateway ${gatewayName} -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Programmed")].message}'
 ```
 
-Our gateway should be accepted and programmed (i.e. valid and assigned an external address).
-
-However, if we check our listener status we will it is not yet "programmed" or ready to accept traffic due to bad TLS configuration.
+Your Gateway should be accepted and programmed (valid and assigned an external address). However, if you check your listener status as follows, you will see that it is not yet programmed or ready to accept traffic due to bad TLS configuration:
 
 ```bash
 kubectl get gateway ${gatewayName} -n ${gatewayNS} -o=jsonpath='{.status.listeners[0].conditions[?(@.type=="Programmed")].message}'
 ```
 
-Kuadrant can help with this via TLSPolicy.
+Kuadrant can help with this by using a TLSPolicy.
 
-### Secure and protect the Gateway with TLS rate limiting and auth policies.
+### Step 5 - Secure and protect the Gateway with auth, TLS, rate limit, and DNS policies
 
 While your Gateway is now deployed, it has no exposed endpoints and your listener is not programmed. Next, you can set up a `TLSPolicy` that leverages your CertificateIssuer to set up your listener certificates. 
 
 You will also define an `AuthPolicy` that will set up a default `403` response for any unprotected endpoints, as well as a `RateLimitPolicy` that will set up a default artificially low global limit to further protect any endpoints exposed by this Gateway.
 
-Set up a default, deny-all `AuthPolicy` for your Gateway as follows:
+#### Set the Auth policy
+
+Set a default, deny-all `AuthPolicy` for your Gateway as follows:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -218,13 +218,17 @@ spec:
 EOF
 ```
 
-Check that your policy was accepted by the controller:
+Check that your auth policy was accepted by the controller as follows:
 
 ```bash
 kubectl get authpolicy ${gatewayName}-auth -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}'
 
 ```
 
+#### Set the TLS policy
+
+Set the `TLSPolicy` for your Gateway as follows:
+
 ```bash
 kubectl apply -f - <<EOF
 apiVersion: kuadrant.io/v1alpha1
@@ -244,12 +248,15 @@ spec:
 EOF
 ```
 
-Check that your policy was accepted by the controller:
+Check that your TLS policy was accepted by the controller as follows:
 
 ```bash
 kubectl get tlspolicy ${gatewayName}-tls -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}'
 ```
 
+#### Set the rate limit policy
+
+Set the default `RateLimitPolicy` for your Gateway as follows:
 
 ```bash
 kubectl apply -f  - <<EOF
@@ -273,13 +280,16 @@ spec:
 EOF
 ```
 
-
 To check your rate limits have been accepted, enter the following command:
 
 ```bash
 kubectl get ratelimitpolicy ${gatewayName}-rlp -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}'
 ```
 
+#### Set the DNS policy
+
+Set the `DNSPolicy` for your Gateway as follows:
+
 ```bash
 kubectl apply -f - <<EOF
 apiVersion: kuadrant.io/v1alpha1
@@ -303,12 +313,16 @@ EOF
 
 NOTE:  The `DNSPolicy` will leverage the `ManagedZone` that you defined earlier based on the listener hosts defined in the Gateway.
 
-Check that your `DNSPolicy` has been accepted:
+Check that your `DNSPolicy` has been accepted as follows:
 
 ```bash
 kubectl get dnspolicy ${gatewayName}-dnspolicy -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}'
 ```
 
+#### Create an HTTP route
+
+Create an `HTTPRoute` for your Gateway as follows:
+
 ```bash
 kubectl apply -f - <<EOF
 apiVersion: gateway.networking.k8s.io/v1
@@ -329,7 +343,7 @@ spec:
 EOF
 ```
 
-Check your Gateway policies are enforced:
+Check your Gateway policies are enforced as follows:
 
 ```bash
 kubectl get dnspolicy ${gatewayName}-dnspolicy -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Enforced")].message}'
@@ -337,38 +351,37 @@ kubectl get authpolicy ${gatewayName}-auth -n ${gatewayNS} -o=jsonpath='{.status
 kubectl get ratelimitpolicy ${gatewayName}-rlp -n ${gatewayNS} -o=jsonpath='{.status.conditions[?(@.type=="Enforced")].message}'
 ```
 
-Check your listener is ready:
+Check your listener is ready as follows:
 
 ```
 kubectl get gateway ${gatewayName} -n ${gatewayNS} -o=jsonpath='{.status.listeners[0].conditions[?(@.type=="Programmed")].message}'
 ```
 
-### Test connectivity and deny all auth 
+### Step 6 - Test connectivity and deny all auth 
 
-You can use `curl` to hit your endpoint. You should see a `403` Because this example uses Let's Encrypt staging, you can pass the `-k` flag:
+You can use `curl` to hit your endpoint. You should see a `403`. Because this example uses Let's Encrypt staging, you can pass the `-k` flag:
 
 ```bash
 curl -k -w "%{http_code}" https://$(kubectl get httproute test -n ${gatewayNS} -o=jsonpath='{.spec.hostnames[0]}')
 ```
 
+### Step 7 - Opening up the Gateway for other namespaces
 
-### Opening up the Gateway for other namespaces:
-
-As you have now configured the Gateway, secured it with Kuadrant policies and tested it, you can now open it up for use by other teams in other namespaces:
+Because you have configured the Gateway, secured it with Kuadrant policies, and tested it, you can now open it up for use by other teams in other namespaces:
 
 ```bash
 kubectl patch gateway ${gatewayName} -n ${gatewayNS} --type='json' -p='[{"op": "replace", "path": "/spec/listeners/0/allowedRoutes/namespaces/from", "value":"All"}]'
 ```
 
-### Extending this Gateway to multiple clusters and configuring geo-based routing
+### Step 8 - Extending this Gateway to multiple clusters and configuring geo-based routing
 
 To distribute this Gateway across multiple clusters, repeat this setup process for each cluster. By default, this will implement a round-robin DNS strategy to distribute traffic evenly across the different clusters. Setting up your Gateways to serve clients based on their geographic location is straightforward with your current configuration.
 
-Assuming you have deployed Gateway instances across multiple clusters as per this guide, the next step involves updating the DNS controller with the geographic regions of the visible Gateways.
+Assuming that you have deployed Gateway instances across multiple clusters as per this guide, the next step involves updating the DNS controller with the geographic regions of the visible Gateways.
 
 For instance, if you have one cluster in North America and another in the EU, you can direct traffic to these Gateways based on their location by applying the appropriate labels:
 
-For your North American cluster:
+For your North American cluster, enter the following command:
 
 ```bash
 kubectl label --overwrite gateway ${gatewayName} kuadrant.io/lb-attribute-geo-code=US -n ${gatewayNS}
@@ -376,30 +389,34 @@ kubectl label --overwrite gateway ${gatewayName} kuadrant.io/lb-attribute-geo-co
 
 ## Application developer workflow
 
-This section of the walkthrough focuses on using an OpenAPI Specification (OAS) to define an API. You will use Kuadrant OAS extensions to specify the routing, authentication, and rate-limiting requirements. Next, you will use the `kuadrantctl` tool to generate an `AuthPolicy`, an `HTTPRoute`, and a `RateLimitPolicy`, which you will then apply to your cluster to enforce the settings defined in your OAS.
+This section of the walkthrough focuses on using an OpenAPI Specification (OAS) to define an API. You will use Kuadrant OAS extensions to specify the routing, authentication, and rate limiting requirements. Next, you will use the `kuadrantctl` tool to generate an `AuthPolicy`, an `HTTPRoute`, and a `RateLimitPolicy`, which you will then apply to your cluster to enforce the settings defined in your OAS.
 
 NOTE: While this section uses the `kuadrantctl` tool, this is not essential. You can also create and apply an `AuthPolicy`, `RateLimitPolicy`, and `HTTPRoute` by using the `oc` or `kubectl` commands.
 
-To begin, you will deploy a new version of the `toystore` app to a developer namespace:
+### Prerequisites
+
+- You have installed `kuadrantctl`. You can find a compatible binary and download it from the [kuadrantctl releases page](https://github.com/Kuadrant/kuadrantctl/releases/tag/v0.2.2).
+- You have the ability to distribute resources generated by `kuadrantctl` to multiple clusters, as though you are a platform engineer.
+
+
+### Step 1 - Deploy the toystore app
+
+To begin, deploy a new version of the `toystore` app to a developer namespace as follows:
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/Kuadrant/Kuadrant-operator/main/examples/toystore/toystore.yaml -n ${devNS}
 ```
 
-### Prerequisites
-
-- Install `kuadrantctl`. You can find a compatible binary and download it from the [kuadrantctl releases page](https://github.com/Kuadrant/kuadrantctl/releases/tag/v0.2.2).
-- Ability to distribute resources generated by `kuadrantctl` to multiple clusters, as though you are a platform engineer.
 
-### Set up HTTPRoute and backend
+### Step 2 - Set up HTTPRoute and backend
 
 Copy at least one of the following example OAS to a local location:
 
-- [Sample OAS for rate-limiting and API Key](../../examples/oas-apikey.yaml)
+- [Sample OAS for rate limiting with API key](../../examples/oas-apikey.yaml)
 
-- [Sample OAS for rate-limiting and OIDC](../../examples/oas-oidc.yaml)
+- [Sample OAS for rate limiting with OIDC](../../examples/oas-oidc.yaml)
 
-Set up some new environment variables:
+Set up some new environment variables as follows:
 
 ```bash
 export oasPath=examples/oas-apikey.yaml
@@ -408,26 +425,27 @@ export rootDomain=example.com
 export gatewayNS=api-gateway
 ```
 
-### Use OAS to define our HTTPRoute rules
+### Step 3 - Use OAS to define your HTTPRoute rules
 
 You can generate Kuadrant and Gateway API resources directly from OAS documents by using an `x-kuadrant` extension.
 
 NOTE: For a more in-depth look at the OAS extension, see the [kuadrantctl documentation](https://docs.kuadrant.io/kuadrantctl/).
 
-Use `kuadrantctl` to generate your `HTTPRoute`.
+You will use `kuadrantctl` to generate your `HTTPRoute`.
 
 NOTE: The sample OAS has some placeholders for namespaces and domains. You will inject valid values into these placeholders based on your previous environment variables.
 
-Generate the resource from your OAS, (`envsubst` will replace the placeholders):
+Generate the resource from your OAS as follows, (`envsubst` will replace the placeholders):
 
 ```bash
-cat $oasPath | envsubst | kuadrantctl generate gatewayapi httproute --oas -
+cat $oasPath | envsubst | kuadrantctl generate gatewayapi httproute --oas - | kubectl apply -f -
+```
 
 ```bash
 kubectl get httproute toystore -n ${devNS} -o=yaml
 ```
 
-We should see that this route is affected by the `AuthPolicy` and `RateLimitPolicy` defined as defaults on the gateway in the gateway namespace.
+You should see that this route is affected by the `AuthPolicy` and `RateLimitPolicy` defined as defaults on the Gateway in the Gateway namespace.
 
 ```yaml
 - lastTransitionTime: "2024-04-26T13:37:43Z"
@@ -444,21 +462,24 @@ We should see that this route is affected by the `AuthPolicy` and `RateLimitPoli
         type: kuadrant.io/RateLimitPolicyAffected        
 ```
 
-### Test connectivity and deny-all auth 
+### Step 4 - Test connectivity and deny-all auth 
 
-We'll use `curl` to hit an endpoint in the toystore app. As we are using LetsEncrypt staging in this example, we pass the `-k` flag:
+You can use `curl` to hit an endpoint in the toystore app. Because you are using Let's Encrypt staging in this example, you can pass the `-k` flag as follows:
 
 ```bash
 curl -s -k -o /dev/null -w "%{http_code}" "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
 ```
 
-We are getting a `403` because of the existing default, deny-all `AuthPolicy` applied at the Gateway. Let's override this for our `HTTPRoute`.
+You are getting a `403` because of the existing default, deny-all `AuthPolicy` applied at the Gateway. You can override this for your `HTTPRoute`.
 
 Choose one of the following options:
 
-### API key auth flow
+- API key auth flow
+- OpenID Connect auth flow 
 
-Set up an example API key in your cluster(s):
+### Step 5 - Set up API key auth flow
+
+Set up an example API key in each cluster as follows:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -476,85 +497,88 @@ type: Opaque
 EOF
 ```
 
-Next, generate an `AuthPolicy` that uses secrets in our cluster as APIKeys:
+Next, generate an `AuthPolicy` that uses secrets in your cluster as API keys as follows:
 
 ```bash
 cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas -
 ```
 
-From this, you can see an `AuthPolicy` generated based on your OAS that will look for API keys in secrets labeled `api_key` and look for that key in the header `api_key`. You can now apply this to the Gateway:
-
+From this, you can see an `AuthPolicy` generated based on your OAS that will look for API keys in secrets labeled `api_key` and look for that key in the header `api_key`. You can now apply this to the Gateway as follows:
 
 ```bash
 cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas -  | kubectl apply -f -
 ```
 
-We should get a `200` from the `GET`, as it has no auth requirement:
+You should get a `200` from the following `GET` because it has no auth requirement:
 
 ```bash
 curl -s -k -o /dev/null -w "%{http_code}" "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
 ```
 
-We should get a `401` for a `POST` request, as it does not have any auth requirements:
+You should get a `401` for the following `POST` request because it does not have any auth requirements:
 
 ```bash
 curl -XPOST -s -k -o /dev/null -w "%{http_code}" "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
 ```
 
-Finally, if we add our API key header, with a valid key, we should get a `200` response:
+Finally, if you add your API key header, with a valid key as follows, you should get a `200` response:
 
 ```bash
 curl -XPOST -H 'api_key: secret' -s -k -o /dev/null -w "%{http_code}" "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
 ```
 
-### OpenID Connect auth flow (skip if interested in API key only)
+### Optional: Step 6 - Set up OpenID Connect auth flow (skip if using API key only)
 
 This section of the walkthrough uses the `kuadrantctl` tool to create an `AuthPolicy` that integrates with an OpenID provider and a `RateLimitPolicy` that leverages JWT values for per-user rate limiting. It is important to note that OpenID requires an external provider. Therefore, you should adapt the following example to suit your specific needs and provider.
 
-The platform engineer workflow established some default policies for authentication and rate limiting at your Gateway. The new developer-defined policies, which you will create, are intended to target your HTTPRoute and will supersede the existing policies for requests to your API endpoints, similar to your previous API key example.
+The platform engineer workflow established default policies for authentication and rate limiting at your Gateway. The new developer-defined policies, which you will create, are intended to target your HTTPRoute and will supersede the existing policies for requests to your API endpoints, similar to your previous API key example.
 
 The example OAS uses Kuadrant-based extensions. These extensions enable you to define routing and service protection requirements. For more details, see [OpenAPI Kuadrant extensions](https://docs.kuadrant.io/kuadrantctl/doc/openapi-kuadrant-extensions/).
 
+#### Prerequisites
 
-### Prerequisites
-
-- You have installed and configured an OpenID Connect provider, such as https://www.keycloak.org/. 
-- You have a realm, client, and users set up. This example assumes a realm in a Keycloak instance called `toystore`
+- You have installed and configured an OpenID Connect provider, such as <https://www.keycloak.org/>. 
+- You have a realm, client, and users set up. This example assumes a realm in a Keycloak instance called `toystore`.
 - Copy the OAS from [sample OAS for rate-limiting and OIDC](../../examples/oas-oidc.yaml) to a local location.
-### Set up an OpenID AuthPolicy
+
+#### Set up an OpenID AuthPolicy
+
+Set the following environment variables:
 
 ```bash
 export openIDHost=some.keycloak.com
 export oasPath=examples/oas-oidc.yaml
 ```
 
-> **Note:** the sample OAS has some placeholders for namespaces and domains - we will inject valid values into these placeholders based on our previous env vars
+NOTE: The sample OAS has some placeholders for namespaces and domains. You will inject valid values into these placeholders based on your previous environment variables.
 
-Let's use our OAS and `kuadrantctl` to generate an `AuthPolicy` to replace the default on the Gateway.
+You can use your OAS and `kuadrantctl` to generate an `AuthPolicy` to replace the default on the Gateway as follows:
 
 ```bash
 cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas -
 ```
 
-If we're happy with the generated resource, let's apply it to the cluster:
+If you are happy with the generated resource, you can apply it to the cluster as follows:
 
 ```bash
 cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas - | kubectl apply -f -
 ```
 
-We should see in the status of the `AuthPolicy` that it has been accepted and enforced:
+You should see in the status of the `AuthPolicy` that it has been accepted and enforced:
 
 ```bash
 kubectl get authpolicy -n ${devNS} toystore -o=jsonpath='{.status.conditions}'
 ```
 
-On our `HTTPRoute`, we should also see it now affected by this `AuthPolicy` in the toystore namespace:
+On your `HTTPRoute`, you should also see it now affected by this `AuthPolicy` in the toystore namespace:
 
 ```bash
 kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.status.parents[0].conditions[?(@.type=="kuadrant.io/AuthPolicyAffected")].message}'
 ```
 
-Let's now test our `AuthPolicy`:
+#### Test your OpenID AuthPolicy
+
+You can test your `AuthPolicy` as follows:
 
 ```bash
 export ACCESS_TOKEN=$(curl -k -H "Content-Type: application/x-www-form-urlencoded" \
@@ -569,7 +593,7 @@ export ACCESS_TOKEN=$(curl -k -H "Content-Type: application/x-www-form-urlencode
 curl -k -XPOST --write-out '%{http_code}\n' --silent --output /dev/null "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
 ```
 
-You should see a `401` response code. Make a request with a valid bearer token:
+You should see a `401` response code. Make a request with a valid bearer token as follows:
 
 ```bash
 curl -k -XPOST --write-out '%{http_code}\n' --silent --output /dev/null -H "Authorization: Bearer $ACCESS_TOKEN" "https://$(kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.spec.hostnames[0]}')/v1/toys"
@@ -577,32 +601,36 @@ curl -k -XPOST --write-out '%{http_code}\n' --silent --output /dev/null -H "Auth
 
 You should see a `200` response code.
 
-### Set up rate limiting
+### Step 7 - Set up rate limiting
 
-Lastly, you can generate your `RateLimitPolicy` to add your rate limits, based on your OAS file. Rate limiting is simplified for this walkthrough and is based on either the bearer token or the API key value. There are more advanced examples in the How-to guides on the Kuadrant documentation site, for example:
-[Authenticated rate limiting with JWTs and Kubernetes RBAC](https://docs.kuadrant.io/kuadrant-operator/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz/)
+Lastly, you can generate your `RateLimitPolicy` to add your rate limits, based on your OAS file. Rate limiting is simplified for this walkthrough and is based on either the bearer token or the API key value. There are more advanced examples in the How-to guides on the Kuadrant documentation site, for example: [Authenticated rate limiting with JWTs and Kubernetes RBAC](https://docs.kuadrant.io/kuadrant-operator/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz/).
 
  You can continue to use this sample OAS document, which includes both authentication and a rate limit:
 
 ```bash
 export oasPath=examples/oas-oidc.yaml
+
+```
+
 Again, you should see the rate limit policy accepted and enforced:
 
 ```bash
 kubectl get ratelimitpolicy -n ${devNS} toystore -o=jsonpath='{.status.conditions}'
 ```
-On your `HTTPoute` we should now see it is affected by the RateLimitPolicy in the same namespace:
+
+On your `HTTRoute`, you should now see it is affected by the `RateLimitPolicy` in the same namespace:
 
 ```bash
 kubectl get httproute toystore -n ${devNS} -o=jsonpath='{.status.parents[0].conditions[?(@.type=="kuadrant.io/RateLimitPolicyAffected")].message}'
 ```
 
-Let's now test your rate-limiting.
+#### Test your RateLimitPolicy
 
-Note you may need to wait a minute for the new rate limits to be applied. With the below requests you should see some number of 429 responses.
+You can now test your rate limiting as follows:
 
+NOTE: You might need to wait a minute for the new rate limits to be applied. With the following requests, you should see a number of 429 responses.
 
-API Key Auth:
+##### API Key auth
 
 ```bash
 for i in {1..3}
@@ -612,8 +640,7 @@ curl -XPOST -H 'api_key:secret' -s -k -o /dev/null -w "%{http_code}"  "https://$
 printf "\n -- \n"
 done 
 ```
-
-And with OpenID Connect Auth:
+##### OpenID Connect auth
 
 ```bash
 export ACCESS_TOKEN=$(curl -k -H "Content-Type: application/x-www-form-urlencoded" \
@@ -633,4 +660,4 @@ done
 
 ## Conclusion
 
-You've completed the secure, protect, and connect walkthrough. To learn more about Kuadrant, visit https://docs.kuadrant.io
+You have completed the secure, protect, and connect walkthrough. To learn more about Kuadrant, visit <https://docs.kuadrant.io>.
diff --git a/doc/user-guides/secure-protect-connect.md b/doc/user-guides/secure-protect-connect.md
index 16fba50e6..dc2c4f302 100644
--- a/doc/user-guides/secure-protect-connect.md
+++ b/doc/user-guides/secure-protect-connect.md
@@ -1,8 +1,8 @@
-# Secure, Protect and Connect services with Kuadrant
+# Secure, protect, and connect services with Kuadrant on Kubernetes
 
-## Pre-requisites
+## Prerequisites
 
-- Completed the [Single-cluster Quick Start](https://docs.kuadrant.io/getting-started-single-cluster/) or [Multi-cluster Quick Start](https://docs.kuadrant.io/getting-started-multi-cluster/)
+- You have completed the [Single-cluster Quick Start](https://docs.kuadrant.io/getting-started-single-cluster/) or [Multi-cluster Quick Start](https://docs.kuadrant.io/getting-started-multi-cluster/).
 
 ## Overview