From 742f483b0d86effc52e496da1f26afd885863457 Mon Sep 17 00:00:00 2001
From: Luke Repko <luke.repko@rackspace.com>
Date: Mon, 22 Apr 2024 14:44:06 -0500
Subject: [PATCH] docs: Add letsencrypt cert deployment info

---
 docs/infrastructure-letsencrypt.md | 86 ++++++++++++++++++++++++++++++
 mkdocs.yml                         |  1 +
 2 files changed, 87 insertions(+)

diff --git a/docs/infrastructure-letsencrypt.md b/docs/infrastructure-letsencrypt.md
index e69de29b..b97a9f82 100644
--- a/docs/infrastructure-letsencrypt.md
+++ b/docs/infrastructure-letsencrypt.md
@@ -0,0 +1,86 @@
+# Deploying Let's Encrypt Certificates
+
+Are you tired of manually renewing and deploying a countless number of
+certificates across your environments? Us too!
+
+## Apply the Let's Encrypt Cluster Issuer
+
+Before we can have Cert Manager start coordinating Let's Encrypt certificate
+requests for us, we need to add an ACME issuer with a valid, monitored
+email (for expiration reminders and other important ACME related information).
+
+``` yaml
+read -p "Enter a valid email address for use with ACME: " ACME_EMAIL; \
+cat <<EOF | kubectl apply -f -
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: ${ACME_EMAIL}
+    privateKeySecretRef:
+      name: letsencrypt-prod
+    solvers:
+      - http01:
+          ingress:
+            ingressClassName: nginx
+EOF
+```
+
+## Use the proper TLS issuerRef
+
+!!! danger "Important for later helm installations!"
+    You must ensure your helm configuration is such that you set the
+    `endpoints.$service.host_fqdn_override.public.tls.issuerRef.name` for any
+    given endpoint to use our `letsencrypt-prod` ClusterIssuer. Similarly,
+    ensure that `endpoints.$service.host_fqdn_override.public.host`
+    is set to the external DNS hostname you plan to expose for a given
+    service endpoint.
+ 
+!!! example
+    You can find several examples of this in the
+    `helm-configs/prod-example-openstack-overrides.yaml`, one such example
+    for glance is below for reference.
+    ```yaml
+    endpoints:
+      image:
+        host_fqdn_override:
+          public:
+            tls:
+              secretName: glance-tls-api
+              issuerRef:
+                name: letsencrpyt-prod
+                kind: ClusterIssuer
+            host: glance.api.your.domain.tld
+        port:
+          api:
+            public: 443
+        scheme:
+          public: https
+    ```
+
+## Helm Kustomize Post Render Args
+
+In order for Cert Manager to set up the ACME challenge, it needs to know which
+ingress to target. We do this via a kustomize overlay that injects the
+needed annotation(s) to the ingress that will be publicly exposed. The
+kustomize overlay to use for that is aptly named, `letsencrypt`.
+
+!!! example "Example keystone installation using the letsencrypt overlay"
+    ```shell
+    helm upgrade --install keystone ./keystone \
+    --namespace=openstack \
+    --wait \
+    --timeout 120m \
+    -f /opt/genestack/helm-configs/keystone/keystone-helm-overrides.yaml \
+    -f /opt/genestack/helm-configs/prod-example-openstack-overrides.yaml \
+    --set endpoints.identity.auth.admin.password="$(kubectl --namespace openstack get secret keystone-admin -o jsonpath='{.data.password}' | base64 -d)" \
+    --set endpoints.oslo_db.auth.admin.password="$(kubectl --namespace openstack get secret mariadb -o jsonpath='{.data.root-password}' | base64 -d)" \
+    --set endpoints.oslo_db.auth.keystone.password="$(kubectl --namespace openstack get secret keystone-db-password -o jsonpath='{.data.password}' | base64 -d)" \
+    --set endpoints.oslo_messaging.auth.admin.password="$(kubectl --namespace openstack get secret rabbitmq-default-user -o jsonpath='{.data.password}' | base64 -d)" \
+    --set endpoints.oslo_messaging.auth.keystone.password="$(kubectl --namespace openstack get secret keystone-rabbitmq-password -o jsonpath='{.data.password}' | base64 -d)" \
+    --post-renderer /opt/genestack/kustomize/kustomize.sh \
+    --post-renderer-args keystone/letsencrypt
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
index ea8141d5..2771debf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -161,6 +161,7 @@ nav:
               - infrastructure-overview.md
               - Namespace: infrastructure-namespace.md
               - Ingress: infrastructure-ingress.md
+              - LetsEncrypt: infrastructure-letsencrypt.md
               - MariaDB:
                   - infrastructure-mariadb.md
               - RabbitMQ: