From b736a7b202122a01a5b4fd0c6123c8396344b479 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Tue, 28 Nov 2023 09:25:26 +0000
Subject: [PATCH] docs: TLS and DNS Policy user guides (#322)

* docs: TLS and DNS Policy user guides

* 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.

* Add script to generate MetalLB IPAddressPool for docker network.

* Change kind cluster ports 80 -> 9081, 443 -> 9444
---
 Makefile                              |   9 ++
 doc/user-guides/gateway-dns.md        | 202 ++++++++++++++++++++++++++
 doc/user-guides/gateway-tls.md        | 187 ++++++++++++++++++++++++
 utils/docker-network-ipaddresspool.sh |  31 ++++
 utils/kind-cluster.yaml               |   7 +-
 5 files changed, 435 insertions(+), 1 deletion(-)
 create mode 100644 doc/user-guides/gateway-dns.md
 create mode 100644 doc/user-guides/gateway-tls.md
 create mode 100755 utils/docker-network-ipaddresspool.sh

diff --git a/Makefile b/Makefile
index 739321651..865691f59 100644
--- a/Makefile
+++ b/Makefile
@@ -368,9 +368,18 @@ 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 -
+	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
new file mode 100644
index 000000000..4b20e46dd
--- /dev/null
+++ b/doc/user-guides/gateway-dns.md
@@ -0,0 +1,202 @@
+# 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
+```
+
+Deploy policy controller and install DNSPolicy CRD:
+```shell
+make deploy-policy-controller
+```
+
+Install metallb:
+```shell
+make install-metallb
+```
+
+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..9e38d2344
--- /dev/null
+++ b/doc/user-guides/gateway-tls.md
@@ -0,0 +1,187 @@
+# 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
+```
+
+Deploy policy controller and install TLSPolicy CRD:
+```shell
+make deploy-policy-controller
+```
+
+Install metallb:
+```shell
+make install-metallb
+```
+
+Create a namespace:
+```shell
+kubectl create namespace my-gateways
+```
+
+### Create an ingress gateway
+
+Create a gateway:
+```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 -vkI https://api.toystore.local --resolve 'api.toystore.local:443:172.18.200.0'
+```
+
+## Cleanup
+
+```shell
+make local-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
diff --git a/utils/kind-cluster.yaml b/utils/kind-cluster.yaml
index c9430adcb..f1403b909 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: 9081
+      protocol: TCP
+    - containerPort: 443
+      hostPort: 9444
+      protocol: TCP