From 473456625a0e5e0604c23700430ac082e0bc0c38 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Tue, 21 Nov 2023 09:17:30 +0000
Subject: [PATCH 1/4] docs: TLS and DNS Policy user guides

---
 Makefile                       |   1 +
 doc/user-guides/gateway-dns.md | 224 +++++++++++++++++++++++++++++++++
 doc/user-guides/gateway-tls.md | 209 ++++++++++++++++++++++++++++++
 utils/kind-cluster.yaml        |   7 +-
 4 files changed, 440 insertions(+), 1 deletion(-)
 create mode 100644 doc/user-guides/gateway-dns.md
 create mode 100644 doc/user-guides/gateway-tls.md

diff --git a/Makefile b/Makefile
index 739321651..850bd0283 100644
--- a/Makefile
+++ b/Makefile
@@ -371,6 +371,7 @@ deploy-dependencies: kustomize dependencies-manifests ## Deploy dependencies to
 .PHONY: install-metallb
 install-metallb: $(KUSTOMIZE) ## Installs the metallb load balancer allowing use of an LoadBalancer type with a gateway
 	$(KUSTOMIZE) build config/metallb | kubectl apply -f -
+	kubectl -n metallb-system wait --for=condition=ready pod --selector=app=metallb --timeout=60s
 
 .PHONY: uninstall-metallb
 uninstall-metallb: $(KUSTOMIZE) 
diff --git a/doc/user-guides/gateway-dns.md b/doc/user-guides/gateway-dns.md
new file mode 100644
index 000000000..18aba46df
--- /dev/null
+++ b/doc/user-guides/gateway-dns.md
@@ -0,0 +1,224 @@
+# Gateway DNS for Cluster Operators
+
+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:
+
+```shell
+make local-setup
+```
+
+Install metallb:
+```shell
+make install-metallb
+```
+
+Fetch the current kind networks subnet:
+```shell
+docker network inspect kind -f '{{ (index .IPAM.Config 0).Subnet }}'
+```
+Response:
+```shell
+"172.18.0.0/16"
+```
+
+Create IPAddressPool within kind network(Fetched by the command above) e.g. 172.18.200
+```shell
+kubectl -n metallb-system apply -f -<<EOF
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: kuadrant-local
+spec:
+  addresses:
+  - 172.18.200.0/24
+---
+apiVersion: metallb.io/v1beta1
+kind: L2Advertisement
+metadata:
+  name: empty
+EOF
+```
+
+Create a namespace:
+```shell
+kubectl create namespace my-gateways
+```
+
+Export a root domain and hosted zone id:
+```shell
+export ROOT_DOMAIN=<ROOT_DOMAIN>
+export AWS_HOSTED_ZONE_ID=<AWS_HOSTED_ZONE_ID>
+```
+
+> **Note:** ROOT_DOMAIN and AWS_HOSTED_ZONE_ID should be set to your AWS hosted zone *name* and *id* respectively.
+
+### Create a ManagedZone
+
+Create AWS credentials secret
+```shell
+export AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
+
+kubectl -n my-gateways 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
+```
+
+Create a ManagedZone
+```sh
+kubectl -n my-gateways apply -f - <<EOF
+apiVersion: kuadrant.io/v1alpha1
+kind: ManagedZone
+metadata:
+  name: $ROOT_DOMAIN
+spec:
+  id: $AWS_HOSTED_ZONE_ID
+  domainName: $ROOT_DOMAIN
+  description: "my managed zone"
+  dnsProviderSecretRef:
+    name: aws-credentials
+    namespace: my-gateways
+EOF
+```
+
+Check it's ready
+```shell
+kubectl get managedzones -n my-gateways
+```
+
+### 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
+kind: Gateway
+metadata:
+  name: prod-web
+spec:
+  gatewayClassName: istio
+  listeners:
+    - allowedRoutes:
+        namespaces:
+          from: All
+      name: api
+      hostname: "*.$ROOT_DOMAIN"
+      port: 80
+      protocol: HTTP
+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.0   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/v1alpha1
+kind: DNSPolicy
+metadata:
+  name: prod-web
+spec:
+  targetRef:
+    name: prod-web
+    group: gateway.networking.k8s.io
+    kind: Gateway
+  routingStrategy: simple
+EOF
+```
+
+Check policy status:
+```shell
+kubectl get dnspolicy -n my-gateways
+```
+Response:
+```shell
+NAME       READY
+prod-web   True
+```
+
+### 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
+kind: HTTPRoute
+metadata:
+  name: toystore
+spec:
+  parentRefs:
+  - name: prod-web
+    namespace: my-gateways
+  hostnames:
+  - "*.$ROOT_DOMAIN"
+  rules:
+  - backendRefs:
+    - name: toystore
+      port: 80
+EOF
+```
+
+Verify a DNSRecord resource is created:
+```shell
+kubectl get dnsrecords -n my-gateways
+NAME           READY
+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.0
+```
+
+Verify DNS using curl:
+
+```shell
+curl http://api.$ROOT_DOMAIN
+```
+
+## Cleanup
+
+```shell
+make local-cleanup
+```
diff --git a/doc/user-guides/gateway-tls.md b/doc/user-guides/gateway-tls.md
new file mode 100644
index 000000000..0a186f55e
--- /dev/null
+++ b/doc/user-guides/gateway-tls.md
@@ -0,0 +1,209 @@
+# Gateway TLS for Cluster Operators
+
+This user guide walks you through an example of how to configure TLS for all routes attached to an ingress gateway.
+
+<br/>
+
+## Requisites
+
+- [Docker](https://docker.io)
+
+### 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, CertManager and Kuadrant itself.
+
+Clone the project:
+
+```shell
+git clone https://github.com/Kuadrant/kuadrant-operator && cd kuadrant-operator
+```
+
+Setup the environment:
+
+```shell
+make local-setup
+```
+
+Install metallb:
+```shell
+make install-metallb
+```
+
+Fetch the current kind networks subnet:
+```shell
+docker network inspect kind -f '{{ (index .IPAM.Config 0).Subnet }}'
+```
+Response:
+```shell
+"172.18.0.0/16"
+```
+
+Create IPAddressPool within kind network(Fetched by the command above) e.g. 172.18.200
+```shell
+kubectl -n metallb-system apply -f -<<EOF
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: kuadrant-local
+spec:
+  addresses:
+  - 172.18.200.0/24
+---
+apiVersion: metallb.io/v1beta1
+kind: L2Advertisement
+metadata:
+  name: empty
+EOF
+```
+
+Create a namespace:
+```shell
+kubectl create namespace my-gateways
+```
+
+### 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
+kind: Gateway
+metadata:
+  name: prod-web
+spec:
+  gatewayClassName: istio
+  listeners:
+    - allowedRoutes:
+        namespaces:
+          from: All
+      name: api
+      hostname: "*.toystore.local"
+      port: 443
+      protocol: HTTPS
+      tls:
+        mode: Terminate
+        certificateRefs:
+          - name: toystore-local-tls
+            kind: Secret
+EOF
+```
+
+### Enable TLS on the gateway
+
+The TLSPolicy requires a reference to an existing [CertManager Issuer](https://cert-manager.io/docs/configuration/).
+
+Create a CertManager Issuer:
+```shell
+kubectl apply -n my-gateways -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned-issuer
+spec:
+  selfSigned: {}
+EOF
+```
+
+> **Note:** We are using a [self-signed](https://cert-manager.io/docs/configuration/selfsigned/) issuer here but any supported CerManager issuer or cluster issuer can be used.
+
+```shell
+kubectl get issuer selfsigned-issuer -n my-gateways
+```
+Response:
+```shell
+NAME                        READY   AGE
+selfsigned-issuer   True    18s
+```
+
+Create a Kuadrant `TLSPolicy` to configure TLS:
+```sh
+kubectl apply -n my-gateways -f - <<EOF
+apiVersion: kuadrant.io/v1alpha1
+kind: TLSPolicy
+metadata:
+  name: prod-web
+spec:
+  targetRef:
+    name: prod-web
+    group: gateway.networking.k8s.io
+    kind: Gateway
+  issuerRef:
+    group: cert-manager.io
+    kind: Issuer
+    name: selfsigned-issuer
+EOF
+```
+
+Check policy status:
+```shell
+kubectl get tlspolicy -n my-gateways
+```
+Response:
+```shell
+
+NAME       READY
+prod-web   True
+```
+
+Check a Certificate resource was created:
+```shell
+kubectl get certificates -n my-gateways
+```
+Response
+```shell
+NAME                 READY   SECRET               AGE
+toystore-local-tls   True    toystore-local-tls   7m30s
+
+```
+
+Check a TLS Secret resource was created:
+```shell
+kubectl get secrets -n my-gateways --field-selector="type=kubernetes.io/tls"
+```
+Response:
+```shell
+NAME                 TYPE                DATA   AGE
+toystore-local-tls   kubernetes.io/tls   3      7m42s
+```
+
+### Deploy a sample API to test TLS
+
+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
+kind: HTTPRoute
+metadata:
+  name: toystore
+spec:
+  parentRefs:
+  - name: prod-web
+    namespace: my-gateways
+  hostnames:
+  - "*.toystore.local"
+  rules:
+  - backendRefs:
+    - name: toystore
+      port: 80
+EOF
+```
+
+### Verify TLS works by sending requests
+
+Verify we can access the service via TLS:
+```shell
+curl -k https://api.toystore.local --resolve 'api.toystore.local:443:172.18.200.0'
+```
+
+## Cleanup
+
+```shell
+make local-cleanup
+```
diff --git a/utils/kind-cluster.yaml b/utils/kind-cluster.yaml
index c9430adcb..42f93e3e9 100644
--- a/utils/kind-cluster.yaml
+++ b/utils/kind-cluster.yaml
@@ -4,9 +4,14 @@ apiVersion: kind.x-k8s.io/v1alpha4
 nodes:
 - role: control-plane
   image: kindest/node:v1.27.3
-  # port forward 80 on the host to 80 on this node
   extraPortMappings:
     - containerPort: 30950
       hostPort: 9080
     - containerPort: 30951
       hostPort: 9443
+    - containerPort: 80
+      hostPort: 8080
+      protocol: TCP
+    - containerPort: 443
+      hostPort: 8443
+      protocol: TCP

From 925672d6a1fb14e3326e71bc451af8109b3e0120 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Fri, 24 Nov 2023 12:20:46 +0000
Subject: [PATCH 2/4] docs: Update after removal of policy-controller from
 bundle

* Add deploy-policy-controller and undeploy-policy-controller,
  deploys/undeploys the policy-controller into/from the kuadrant-system
namespace.
* Update dns and tls guides with extra step to install
  policy-controller.
---
 Makefile                       | 7 +++++++
 doc/user-guides/gateway-dns.md | 5 +++++
 doc/user-guides/gateway-tls.md | 7 ++++++-
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 850bd0283..32b2ab5f0 100644
--- a/Makefile
+++ b/Makefile
@@ -368,6 +368,13 @@ deploy-dependencies: kustomize dependencies-manifests ## Deploy dependencies to
 	$(KUSTOMIZE) build config/dependencies | kubectl apply -f -
 	kubectl -n "$(KUADRANT_NAMESPACE)" wait --timeout=300s --for=condition=Available deployments --all
 
+deploy-policy-controller: kustomize ## Deploy policy-controller to the K8s cluster specified in ~/.kube/config.
+	$(KUSTOMIZE) build config/policy-controller | kubectl apply -f -
+	kubectl -n "$(KUADRANT_NAMESPACE)" wait --timeout=300s --for=condition=Available deployments policy-controller
+
+undeploy-policy-controller: ## Undeploy policy-controller from the K8s cluster specified in ~/.kube/config.
+	$(KUSTOMIZE) build config/policy-controller | kubectl delete -f -
+
 .PHONY: install-metallb
 install-metallb: $(KUSTOMIZE) ## Installs the metallb load balancer allowing use of an LoadBalancer type with a gateway
 	$(KUSTOMIZE) build config/metallb | kubectl apply -f -
diff --git a/doc/user-guides/gateway-dns.md b/doc/user-guides/gateway-dns.md
index 18aba46df..8748aec98 100644
--- a/doc/user-guides/gateway-dns.md
+++ b/doc/user-guides/gateway-dns.md
@@ -26,6 +26,11 @@ Setup the environment:
 make local-setup
 ```
 
+Deploy policy controller and install DNSPolicy CRD:
+```shell
+make deploy-policy-controller
+```
+
 Install metallb:
 ```shell
 make install-metallb
diff --git a/doc/user-guides/gateway-tls.md b/doc/user-guides/gateway-tls.md
index 0a186f55e..aa577b671 100644
--- a/doc/user-guides/gateway-tls.md
+++ b/doc/user-guides/gateway-tls.md
@@ -25,6 +25,11 @@ Setup the environment:
 make local-setup
 ```
 
+Deploy policy controller and install TLSPolicy CRD:
+```shell
+make deploy-policy-controller
+```
+
 Install metallb:
 ```shell
 make install-metallb
@@ -64,7 +69,7 @@ kubectl create namespace my-gateways
 
 ### Create an ingress gateway
 
-Create a gateway using your ROOT_DOMAIN as part of a listener hostname:
+Create a gateway:
 ```sh
 kubectl -n my-gateways apply -f - <<EOF
 apiVersion: gateway.networking.k8s.io/v1

From e9504dbd137e3d637b40d2d54ae2fbe7916bd709 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Wed, 22 Nov 2023 17:35:56 +0000
Subject: [PATCH 3/4] Add script to generate MetalLB IPAddressPool for docker
 network.

---
 Makefile                              |  1 +
 doc/user-guides/gateway-dns.md        | 27 -----------------------
 doc/user-guides/gateway-tls.md        | 29 +------------------------
 utils/docker-network-ipaddresspool.sh | 31 +++++++++++++++++++++++++++
 4 files changed, 33 insertions(+), 55 deletions(-)
 create mode 100755 utils/docker-network-ipaddresspool.sh

diff --git a/Makefile b/Makefile
index 32b2ab5f0..865691f59 100644
--- a/Makefile
+++ b/Makefile
@@ -379,6 +379,7 @@ undeploy-policy-controller: ## Undeploy policy-controller from the K8s cluster s
 install-metallb: $(KUSTOMIZE) ## Installs the metallb load balancer allowing use of an LoadBalancer type with a gateway
 	$(KUSTOMIZE) build config/metallb | kubectl apply -f -
 	kubectl -n metallb-system wait --for=condition=ready pod --selector=app=metallb --timeout=60s
+	./utils/docker-network-ipaddresspool.sh kind | kubectl apply -n metallb-system -f -
 
 .PHONY: uninstall-metallb
 uninstall-metallb: $(KUSTOMIZE) 
diff --git a/doc/user-guides/gateway-dns.md b/doc/user-guides/gateway-dns.md
index 8748aec98..4b20e46dd 100644
--- a/doc/user-guides/gateway-dns.md
+++ b/doc/user-guides/gateway-dns.md
@@ -36,33 +36,6 @@ Install metallb:
 make install-metallb
 ```
 
-Fetch the current kind networks subnet:
-```shell
-docker network inspect kind -f '{{ (index .IPAM.Config 0).Subnet }}'
-```
-Response:
-```shell
-"172.18.0.0/16"
-```
-
-Create IPAddressPool within kind network(Fetched by the command above) e.g. 172.18.200
-```shell
-kubectl -n metallb-system apply -f -<<EOF
-apiVersion: metallb.io/v1beta1
-kind: IPAddressPool
-metadata:
-  name: kuadrant-local
-spec:
-  addresses:
-  - 172.18.200.0/24
----
-apiVersion: metallb.io/v1beta1
-kind: L2Advertisement
-metadata:
-  name: empty
-EOF
-```
-
 Create a namespace:
 ```shell
 kubectl create namespace my-gateways
diff --git a/doc/user-guides/gateway-tls.md b/doc/user-guides/gateway-tls.md
index aa577b671..9e38d2344 100644
--- a/doc/user-guides/gateway-tls.md
+++ b/doc/user-guides/gateway-tls.md
@@ -35,33 +35,6 @@ Install metallb:
 make install-metallb
 ```
 
-Fetch the current kind networks subnet:
-```shell
-docker network inspect kind -f '{{ (index .IPAM.Config 0).Subnet }}'
-```
-Response:
-```shell
-"172.18.0.0/16"
-```
-
-Create IPAddressPool within kind network(Fetched by the command above) e.g. 172.18.200
-```shell
-kubectl -n metallb-system apply -f -<<EOF
-apiVersion: metallb.io/v1beta1
-kind: IPAddressPool
-metadata:
-  name: kuadrant-local
-spec:
-  addresses:
-  - 172.18.200.0/24
----
-apiVersion: metallb.io/v1beta1
-kind: L2Advertisement
-metadata:
-  name: empty
-EOF
-```
-
 Create a namespace:
 ```shell
 kubectl create namespace my-gateways
@@ -204,7 +177,7 @@ EOF
 
 Verify we can access the service via TLS:
 ```shell
-curl -k https://api.toystore.local --resolve 'api.toystore.local:443:172.18.200.0'
+curl -vkI https://api.toystore.local --resolve 'api.toystore.local:443:172.18.200.0'
 ```
 
 ## Cleanup
diff --git a/utils/docker-network-ipaddresspool.sh b/utils/docker-network-ipaddresspool.sh
new file mode 100755
index 000000000..e7297de57
--- /dev/null
+++ b/utils/docker-network-ipaddresspool.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Generates a MetalLB IpAddressPool for the given docker network.
+# https://metallb.org/configuration/#defining-the-ips-to-assign-to-the-load-balancer-services
+#
+# Example:
+# ./utils/docker-network-ipaddresspool.sh kind | kubectl apply -n metallb-system -f -
+
+set -euo pipefail
+
+networkName=$1
+
+subnet=`docker network inspect $networkName -f '{{ (index .IPAM.Config 0).Subnet }}'`
+# shellcheck disable=SC2206
+subnetParts=(${subnet//./ })
+cidr="${subnetParts[0]}.${subnetParts[1]}.200.0/24"
+
+cat <<EOF
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: kuadrant-local
+spec:
+  addresses:
+  - $cidr
+---
+apiVersion: metallb.io/v1beta1
+kind: L2Advertisement
+metadata:
+  name: empty
+EOF

From ec4e25a3bff8daee957c8cbf755c191b42cbb4be Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Fri, 24 Nov 2023 15:18:36 +0000
Subject: [PATCH 4/4] Change kind cluster ports 80 -> 9081, 443 -> 9444

---
 utils/kind-cluster.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/utils/kind-cluster.yaml b/utils/kind-cluster.yaml
index 42f93e3e9..f1403b909 100644
--- a/utils/kind-cluster.yaml
+++ b/utils/kind-cluster.yaml
@@ -10,8 +10,8 @@ nodes:
     - containerPort: 30951
       hostPort: 9443
     - containerPort: 80
-      hostPort: 8080
+      hostPort: 9081
       protocol: TCP
     - containerPort: 443
-      hostPort: 8443
+      hostPort: 9444
       protocol: TCP