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/gateway
+
+**Gateway API** (north-south ingress) implemented by **Cilium** + the shared HTTPS Gateway and the
+wildcard TLS certificate.
+
+- **Governing ADRs:** [ADR-0002 — Cilium + Gateway API](../../../home-network-k3s/decisions/adr-0002-cni-cilium.md),
+  [ADR-0006 — cert-manager/Let's Encrypt](../../../home-network-k3s/decisions/adr-0006-tls-cert-manager-letsencrypt.md)
+- **Spec:** [docs/09 — DNS & Ingress](../../../home-network-k3s/docs/09-dns-and-ingress.md)
+- **Serves:** R-DNS-01, R-TLS-01
+- **Owner:** WS-NET (+ WS-SEC for the cert)
+
+## What this stub is
+
+- **`GatewayClass` `cilium`** — Gateway API implemented by Cilium; no separate ingress controller
+  (ADR-0002).
+- **`Gateway` `shared`** — HTTPS listener on `*.home.keithjackson.dev`, TLS terminated with the
+  wildcard cert. App HTTPRoutes attach cross-namespace via a namespace label + ReferenceGrant
+  (rendered by WS-APPS from each ServiceDefinition's `exposure`).
+- **`Certificate` `wildcard-home`** — `*.home.keithjackson.dev` issued by `${ACME_CLUSTER_ISSUER}`
+  (staging in dev, prod in prod — R-ENV-02). Makes onboarding certificate-free (ADR-0006 default).
+
+## Contract (Issuer + Gateway TLS)
+
+The "Issuer + Gateway TLS" interface (`roadmap/workstreams.md`): this Gateway + wildcard cert are what
+every service's HTTPRoute attaches to. ExternalDNS ([`../externaldns`](../externaldns)) publishes the
+`public` records for hostnames routed here. Ingress opens **north-south** only — it does **not** relax
+east-west default-deny (docs/09).
+
+## TODO (later phases)
+
+- **Phase 2 (WS-NET):** pin the L2-announced ingress VIP / IP pool (Cilium L2 announcement, docs/09);
+  add the HTTP→HTTPS redirect route; confirm the cross-namespace ReferenceGrant pattern with WS-APPS.
+- **Public exposure** is a **manual edge port-forward** of 80/443 to the Gateway VIP (single SOHO
+  router, docs/09) — a documented manual step, the analogue of the old pfSense exception.
@@ -0,0 +1,42 @@
+---
+# Shared Gateway — HTTPS listeners on *.home.keithjackson.dev, TLS terminated with the wildcard cert
+# (docs/09). Implemented by Cilium (GatewayClass `cilium`). The ingress VIP is announced via Cilium
+# L2 announcement on the flat LAN (docs/09, OQ-1 resolved). Phase 0 STUB.
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: shared
+  namespace: gateway
+spec:
+  gatewayClassName: cilium
+  listeners:
+    - name: https
+      protocol: HTTPS
+      port: 443
+      hostname: "*.home.keithjackson.dev"
+      tls:
+        mode: Terminate
+        certificateRefs:
+          - kind: Secret
+            name: wildcard-home-tls      # produced by wildcard-certificate.yaml
+      allowedRoutes:
+        namespaces:
+          from: Selector
+          selector:
+            matchLabels:
+              # App namespaces opt in to attach HTTPRoutes here (WS-APPS renders the label +
+              # ReferenceGrant from ServiceDefinition `exposure`). docs/09.
+              gateway-access: "shared"
+    - name: http-redirect
+      protocol: HTTP
+      port: 80
+      hostname: "*.home.keithjackson.dev"
+      allowedRoutes:
+        namespaces:
+          from: Selector
+          selector:
+            matchLabels:
+              gateway-access: "shared"
+# TODO(WS-NET, Phase 2): pin the L2-announced VIP / IP pool; add HTTP->HTTPS redirect HTTPRoute;
+#   confirm cross-namespace ReferenceGrant pattern with WS-APPS. Ingress opens NORTH-SOUTH only —
+#   it does not relax east-west default-deny (docs/09).
@@ -0,0 +1,9 @@
+---
+# GatewayClass implemented by Cilium (ADR-0002: Gateway API via Cilium, no separate ingress
+# controller). Phase 0 STUB. The controllerName is provided by the Cilium Gateway API integration.
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: cilium
+spec:
+  controllerName: io.cilium/gateway-controller
@@ -0,0 +1,8 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - gatewayclass.yaml
+  - wildcard-certificate.yaml
+  - gateway.yaml
@@ -0,0 +1,7 @@
+---
+# Shared Gateway lives in its own namespace; HTTPRoutes from app namespaces attach cross-namespace
+# via ReferenceGrant (rendered by WS-APPS from ServiceDefinitions).
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: gateway
@@ -0,0 +1,18 @@
+---
+# Wildcard certificate `*.home.keithjackson.dev`, terminated at the shared Gateway (ADR-0006 default).
+# Makes onboarding certificate-free. Issued by the env-selected ClusterIssuer (R-ENV-02).
+# Phase 0 STUB — cannot issue without a cluster + Cloudflare token.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: wildcard-home
+  namespace: gateway
+spec:
+  secretName: wildcard-home-tls        # consumed by the Gateway HTTPS listener below
+  dnsNames:
+    - "*.home.keithjackson.dev"
+    - "home.keithjackson.dev"          # apex for the C2 UI (docs/09)
+  issuerRef:
+    kind: ClusterIssuer
+    # ${ACME_CLUSTER_ISSUER}: dev -> letsencrypt-staging, prod -> letsencrypt-prod (cluster-vars).
+    name: ${ACME_CLUSTER_ISSUER}