From 9dac15e329f08a09474f224e03f2c08d135b31f6 Mon Sep 17 00:00:00 2001
From: Craig Brookes <maleck13@users.noreply.github.com>
Date: Mon, 14 Oct 2024 14:31:02 +0100
Subject: [PATCH] small updates and improvements for install docs (#939)

Signed-off-by: craig <cbrookes@redhat.com>

rh-pre-commit.version: 2.2.0
rh-pre-commit.check-secrets: ENABLED

update RLP version
---
 doc/install/install-kubernetes.md         | 44 ++++++++++-------
 doc/install/install-openshift.md          | 28 +++++++----
 doc/user-guides/secure-protect-connect.md | 60 ++++++++++++++++++++---
 3 files changed, 98 insertions(+), 34 deletions(-)

diff --git a/doc/install/install-kubernetes.md b/doc/install/install-kubernetes.md
index 7a3b6dca9..993524dfa 100644
--- a/doc/install/install-kubernetes.md
+++ b/doc/install/install-kubernetes.md
@@ -10,6 +10,7 @@
     All required labels are formatted as `kuadrant.io/*`.
     Removal of any labels with the prefix may cause unexpected behaviour and degradation of the product.
 
+
 ## Prerequisites
 
 - Access to a Kubernetes cluster, with `kubeadmin` or an account with similar permissions
@@ -48,9 +49,9 @@ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releas
     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.21.4 sh -
-./istio-1.21.4/bin/istioctl install --set profile=minimal
-./istio-1.21.4/bin/istioctl operator init
+curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.5 sh -
+./istio-1.22.5/bin/istioctl install --set profile=minimal
+./istio-1.22.5/bin/istioctl operator init
 kubectl apply -f https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/config/dependencies/istio/istio-operator.yaml
 ```
 
@@ -115,7 +116,9 @@ Kuadrant is now ready to use.
 
 ### (Optional) `DNSPolicy` setup
 
-If you plan to use `DNSPolicy`, you will need an AWS Account with access to Route 53 (more providers coming soon), and a hosted zone.
+If you plan to use `DNSPolicy`, this doc uses an AWS Account with access to Route 53. There are other providers that you can also use for DNS integration: 
+
+[DNS Providers](https://docs.kuadrant.io/latest/dns-operator/docs/provider/)
 
 Export the following environment variables for setup:
 
@@ -146,7 +149,11 @@ Follow these steps to create the necessary secret:
     ```bash
     # Replace this with an accessible Redis cluster URL
     export REDIS_URL=redis://user:xxxxxx@some-redis.com:6379
-
+    
+    ```    
+3. Create the secret:
+    
+    ```bash
     kubectl -n kuadrant-system create secret generic redis-config \
       --from-literal=URL=$REDIS_URL
     ```
@@ -154,24 +161,25 @@ Follow these steps to create the necessary secret:
 This will create a secret named `redis-config` in the `kuadrant-system` namespace containing your Redis cluster URL, which Kuadrant will use for multi-cluster rate limiting.
 
 
-You'll also need to update your earlier created `Kuadrant` instance to reconfigure Kuadrant to use Redis:
+You'll also need to update the `Limitador` instance (the component that handles rate limiting) to reconfigure Kuadrant to use Redis:
 
 ```bash
-kubectl apply -f - <<EOF
-apiVersion: kuadrant.io/v1beta1
-kind: Kuadrant
-metadata:
-  name: kuadrant
-  namespace: kuadrant-system
+kubectl patch limitador limitador --type=merge -n kuadrant-system -p '
 spec:
-  limitador:
-    storage:
-      redis-cached:
-        configSecretRef:
-          name: redis-config
-EOF
+  storage:
+    redis:
+      configSecretRef:
+        name: redis-config
+'
+
+kubectl wait limitador/limitador -n kuadrant-system --for="condition=Ready=true"
+
 ```
 
+### Metal LB (local setup)
+
+If you are using a local kind cluster, we recommend using [metallb](https://metallb.universe.tf/) to allow the service type loadbalancer to be used with your gateways and an IP to be assigned to your gateway address rather than an internal service name.
+
 ## Next Steps
 
 - [Secure, protect, and connect APIs with Kuadrant on Kubernetes](../user-guides/secure-protect-connect.md)
diff --git a/doc/install/install-openshift.md b/doc/install/install-openshift.md
index d45501918..717768aa1 100644
--- a/doc/install/install-openshift.md
+++ b/doc/install/install-openshift.md
@@ -30,6 +30,13 @@ 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
 ```
 
+Set the version of Kuadrant to the latest released version: https://github.com/Kuadrant/kuadrant-operator/releases/
+
+```
+export KUADRANT_VERSION='vX.Y.Z'
+```
+
+
 ### Step 2 - Install Gateway API v1
 
 Before you can use Kuadrant, you must install Gateway API v1 as follows:
@@ -215,7 +222,7 @@ metadata:
   namespace: kuadrant-system
 spec:
   sourceType: grpc
-  image: quay.io/kuadrant/kuadrant-operator-catalog:v0.11.0
+  image: quay.io/kuadrant/kuadrant-operator-catalog:${KUADRANT_VERSION}
   displayName: Kuadrant Operators
   publisher: grpc
   updateStrategy:
@@ -262,15 +269,6 @@ kubectl get installplan -n kuadrant-system -o=jsonpath='{.items[0].status.phase}
 After some time, this command should return `complete`.
 
 
-#### Redis credentials for storage of rate limiting counters
-
-In this installation we will show how to configure ratelimiting counters to be stored in redis. Before we go further we need to setup a redis secret to use later:
-
-```bash
-kubectl -n kuadrant-system create secret generic redis-config \
-  --from-literal=URL=$REDIS_URL
-```
-
 #### Set up a DNSProvider
 
 The example here is for AWS Route 53. It is important the secret for the DNSProvider is setup in the same namespace as the gateway.
@@ -320,6 +318,16 @@ This will setup and configure a number of Kuadrant subcomponents. Some of these
 
 ### Configuring Redis Storage for Limitador
 
+#### Redis credentials for storage of rate limiting counters
+
+In this installation we will show how to configure ratelimiting counters to be stored in redis. Before we go further we need to setup a redis secret to use later:
+
+```bash
+kubectl -n kuadrant-system create secret generic redis-config --from-literal="URL"=$REDIS_URL
+```
+
+#### Update limitador config
+
 To configure redis storage for Limatador, we must update the Limitador custom resource to use the secret we created:
 
 You can run a command like the one below to add this configuration:
diff --git a/doc/user-guides/secure-protect-connect.md b/doc/user-guides/secure-protect-connect.md
index 4e3bdfcc0..6fefae4f1 100644
--- a/doc/user-guides/secure-protect-connect.md
+++ b/doc/user-guides/secure-protect-connect.md
@@ -4,6 +4,15 @@
 
 - You have completed the [Single-cluster Quick Start](https://docs.kuadrant.io/latest/getting-started-single-cluster/) or [Multi-cluster Quick Start](https://docs.kuadrant.io/latest/getting-started-multi-cluster/).
 
+
+### Local Cluster (metallb)
+
+>**Note:** If you are running on a local kind cluster, it is also recommended you use [metallb](https://metallb.universe.tf/) to setup an IP address pool to use with loadbalancer services for your gateways. An example script for configuring metallb based on the docker network once installed can be found [here](https://github.com/Kuadrant/kuadrant-operator/blob/main/utils/docker-network-ipaddresspool.sh).
+
+```
+./utils/docker-network-ipaddresspool.sh kind yq 1 | kubectl apply -n metallb-system -f -
+```
+
 ## Overview
 
 In this guide, we will cover the different policies from Kuadrant and how you can use them to secure, protect and connect an Istio-controlled gateway in a single cluster, and how you can set more refined protection on the HTTPRoutes exposed by that gateway.
@@ -40,7 +49,7 @@ Adjust the name of the cluster accordingly to match the kubernetes cluster you a
 You can get the current context with `kubectl config current-context`
 
 ```sh
-# Typical single cluster context
+# Typical single cluster context
 export KUBECTL_CONTEXT=kind-kuadrant-local
 
 # Example context for additional 'multi cluster' clusters
@@ -115,7 +124,7 @@ spec:
 EOF
 ```
 
-> **Note:** You may have to create a cluster issuer in the Kubernetes cluster, depending on if one was created during your initial cluster setup or not. Here is an example of how to create a self-signed CA as a cluster issuer.
+> **Note:** You may have to create a cluster issuer in the Kubernetes cluster, depending on if one was created during your initial cluster setup or not. Here is an example of how to create a self-signed CA as a cluster issuer. This is a self signed issuer for simplicity, but you can use other issuers such as [letsencrypt](https://letsencrypt.org/). Refer to the [cert-manager docs](https://cert-manager.io/docs/configuration/acme/dns01/route53/#iam-user-with-long-term-access-key)
 
 ```sh
 kubectl --context $KUBECTL_CONTEXT apply -f - <<EOF
@@ -282,7 +291,9 @@ kubectl -n kuadrant-system create secret generic aws-credentials \
   --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
 ```
 
-Next, create the DNSPolicy:
+Next, create the DNSPolicy. There are two options here. 
+
+1. **Single gateway with no shared hostnames:**
 
 ```sh
 kubectl --context $KUBECTL_CONTEXT apply -f - <<EOF
@@ -299,19 +310,56 @@ spec:
   providerRefs:
   - name: aws-credentials
 EOF
+```
+2. **multiple gateways with shared hostnames:**
+
+If you want to use a gateway with a shared listener host (IE the same hostname on more than one gateway instance). Then you should use the following configuration:
+
+> **Note:** This configuration will work fine for a single gateway also, but does create some additional records.
+
+```sh
+kubectl --context $KUBECTL_CONTEXT apply -f - <<EOF
+apiVersion: kuadrant.io/v1alpha1
+kind: DNSPolicy
+metadata:
+  name: simple-dnspolicy
+  namespace: kuadrant-system
+spec:
+  targetRef:
+    name: api-gateway
+    group: gateway.networking.k8s.io
+    kind: Gateway
+  providerRefs:
+    - name: aws-credentials
+  loadBalancing:
+    weight: 120
+    geo: EU
+    defaultGeo: true
+EOF
+```    
+
+The loadbalancing section here has the following attributes:
+
+- **Weight:** This will be the weighting used for records created for hosts defined by this gateway. It will decide how often the records for this gateway are returned. If you have 2 gateways and each DNSPolicy specifies the same weight, then you will get an even distribution. If you define one weight as larger than the other, the gateway with the larger weight will receive more traffic (record weight / sum of all records).
+- **geo:** This will be the geo used to decide whether to return records defined for this gateway based on the requesting client's location. This should be set even if you have one gateway in a single geo. 
+- **defaultGeo:** For Azure and AWS, this will decide, if there should be a default geo. A default geo acts as a "catch-all" (GCP always sets a catch-all) for clients outside of the defined geo locations. There can only be one default value and so it is important you set `defaultGeo` as true for **one** and **only one** geo code for each of the gateways in that geo. 
 
+Wait for the DNSPolicy to marked as enforced:
+
+```
 kubectl --context $KUBECTL_CONTEXT wait dnspolicy simple-dnspolicy -n kuadrant-system --for=condition=enforced
 ```
 
-If you want to see the DNSRecord created by the this policy, execute the following command:
+If you want to see the actual DNSRecord created by the this policy, execute the following command:
+
+> **Note:** This resource is managed by kuadrant and so shouldn't be changed directly.
 
 ```sh
 kubectl --context $KUBECTL_CONTEXT get dnsrecord.kuadrant.io api-gateway-api -n kuadrant-system -o=yaml
 ```
 
-So now we have a wildcard DNS record to bring traffic to our gateway.
 
-Let's test it again. This time we expect a `403` still as the _deny-all_ policy is still in effect. Notice we no longer need to set the Host header directly.
+With DNS in place, let's test it again. This time we expect a `403` still as the _deny-all_ policy is still in effect. Notice we no longer need to set the Host header directly.
 
 > **Note:** If you have followed through this guide on more than 1 cluster, the DNS record for the HTTPRoute hostname will have multiple IP addresses. This means that requests will be made in a round robin pattern across clusters as your DNS provider sends different responses to lookups. You may need to send multiple requests before one hits the cluster you are currently configuring.