T-0.1 Flux GitOps layout + dev/prod overlays + platform component skeletons (R-GITOPS-01/03, R-ENV-02, R-PLAT-01)

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-16 00:08:31 -05:00
1 parent bd8de96456
commit af4f6c07ae
@@ -0,0 +1,34 @@
+# platform/cert-manager
+
+**cert-manager** — trusted TLS via **Let's Encrypt**, **ACME DNS-01** (Cloudflare).
+
+- **Governing ADR:** [ADR-0006 — TLS: cert-manager + Let's Encrypt (DNS-01)](../../../home-network-k3s/decisions/adr-0006-tls-cert-manager-letsencrypt.md)
+- **Spec:** [docs/08 — TLS & Certificates](../../../home-network-k3s/docs/08-tls-and-certificates.md),
+  [docs/09 — DNS & Ingress](../../../home-network-k3s/docs/09-dns-and-ingress.md)
+- **Serves:** R-TLS-01/02/03, R-DNS-01
+- **Owner:** WS-SEC
+
+## What this stub is
+
+Flux `HelmRelease` + **two `ClusterIssuer`s** (`letsencrypt-staging`, `letsencrypt-prod` — both
+mandated by ADR-0006). DNS-01 against the `keithjackson.dev` zone validates domain control **without
+exposing the service** (works for internal-only services, R-TLS-03) and enables the **wildcard**
+`*.home.keithjackson.dev` cert defined in [`../gateway`](../gateway).
+
+## Contract (Issuer + Gateway TLS)
+
+Part of the "Issuer + Gateway TLS" interface (`roadmap/workstreams.md`, WS-SEC + WS-NET): the wildcard
+`Certificate` (in `gateway/`) references the issuer named by `${ACME_CLUSTER_ISSUER}` and its secret
+is consumed by the Gateway HTTPS listener.
+
+## Secrets
+
+The Cloudflare API token is referenced **by name** (`cloudflare-api-token`) and committed
+**SOPS-encrypted** (WS-SEC, OQ-4, ADR-0007). **No plaintext token in git.**
+
+## TODO (later phases)
+
+- **OQ-4 (resolved to Cloudflare):** WS-SEC provisions the scoped Cloudflare token, SOPS-encrypted.
+- Set the ACME account email.
+- **Phase 2 (WS-SEC):** issue the wildcard cert; prove a trusted, non-self-signed cert at
+  `*.home.keithjackson.dev` (R-TLS-01/03, Phase-2 exit gate).
@@ -0,0 +1,48 @@
+---
+# ClusterIssuers — Let's Encrypt via ACME DNS-01 against the keithjackson.dev zone (Cloudflare).
+# ADR-0006 mandates BOTH a staging issuer (bring-up) and a prod issuer. DNS-01 enables wildcard
+# certs and does NOT require exposing the service (works for internal-only services, R-TLS-03).
+#
+# Phase 0 STUB: emails/tokens are placeholders. The Cloudflare API token is referenced BY NAME only
+# and will be committed SOPS-encrypted (OQ-4, ADR-0007) — NO plaintext secret here.
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-staging
+spec:
+  acme:
+    server: https://acme-staging-v02.api.letsencrypt.org/directory
+    email: [email protected]        # TODO(WS-SEC): ACME account email
+    privateKeySecretRef:
+      name: letsencrypt-staging-account-key
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token       # SOPS-encrypted (WS-SEC) — name only
+              key: api-token
+        selector:
+          dnsZones:
+            - "keithjackson.dev"
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: [email protected]        # TODO(WS-SEC): ACME account email
+    privateKeySecretRef:
+      name: letsencrypt-prod-account-key
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token       # SOPS-encrypted (WS-SEC) — name only
+              key: api-token
+        selector:
+          dnsZones:
+            - "keithjackson.dev"
+# The active issuer per environment is chosen via ${ACME_CLUSTER_ISSUER} (cluster-vars):
+# dev -> letsencrypt-staging, prod -> letsencrypt-prod (R-ENV-02). See gateway/ wildcard Certificate.
@@ -0,0 +1,28 @@
+---
+# cert-manager — issues trusted Let's Encrypt certs via ACME DNS-01 (ADR-0006). Phase 0 STUB.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: cert-manager
+  namespace: cert-manager
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: cert-manager
+      version: ">=1.16.0 <1.17.0"   # TODO(WS-SEC): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: jetstack
+        namespace: cert-manager
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    crds:
+      enabled: true      # install CRDs with the chart
+    # TODO(WS-SEC, Phase 2): DNS-01 recursive nameserver config if split-horizon DNS interferes
+    #   with propagation checks (docs/09 split-horizon note).
@@ -0,0 +1,9 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: jetstack
+  namespace: cert-manager
+spec:
+  interval: 1h
+  url: https://charts.jetstack.io
@@ -0,0 +1,8 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - helmrepository.yaml
+  - helmrelease.yaml
+  - clusterissuers.yaml
@@ -0,0 +1,5 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: cert-manager
@@ -0,0 +1,6 @@
+# cert-manager Helm values — PLACEHOLDER (Phase 0). Authoritative values inline in helmrelease.yaml.
+#
+# crds.enabled: true                          # install CRDs with the chart
+# dns01RecursiveNameservers / -Only           # TODO(WS-SEC): may be needed with split-horizon DNS
+# ClusterIssuers (letsencrypt-staging/-prod) live in clusterissuers.yaml, not here.
+# Cloudflare API token: SOPS-encrypted secret `cloudflare-api-token` (WS-SEC, OQ-4) — name only.