From 8889950b60ad2201a44d6b58da67919ee0dce769 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Tue, 21 Nov 2023 09:17:30 +0000
Subject: [PATCH] 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 a91225fb0..566cb02a0 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..ae5aea927
--- /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/v1beta1
+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..ee9292d67
--- /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/v1beta1
+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