jakman85andClaude Opus 4.8
e8c555cfeb
Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
3.8 KiB
3.8 KiB
09 — DNS & Ingress
Serves: R-DNS-01/02/03, R-C2-01, works with R-TLS-*. Related: ADR-0002 (Cilium/Gateway API).
Naming model
- All services live at
<service>.home.keithjackson.dev(e.g.plex.home.keithjackson.dev). - The root
home.keithjackson.devserves the Command & Control UI (12). - Public apex
*.keithjackson.devresolves to the network's public IP;*.home.keithjackson.devis the platform's zone.
DNS automation (R-DNS-02)
- ExternalDNS watches Gateway/HTTPRoute (and Service) resources and manages records in the authoritative DNS provider (Cloudflare, per OQ-4) automatically — a new service's DNS appears from its declared intent, no manual record editing.
- Records for
*.home.keithjackson.devare created/updated/removed as services come and go.
Split-horizon resolution (R-DNS-03)
Internal and external answers differ:
- External (
*.home.keithjackson.devfrom the internet): resolves to the public IP; reaches the edge router, which forwardspublic-class services to the in-cluster Gateway. - Internal (LAN clients): resolves
<service>.home.keithjackson.devto the internal Gateway address directly, avoiding hairpinning through the public IP. - PiHole (itself an onboarded service) provides internal LAN DNS and the split-horizon answers
for
.home.keithjackson.dev; the trusted Let's Encrypt cert is served either way (08).
DNS is thus both a platform capability and a hosted service. Bootstrapping order matters: the platform needs working DNS before PiHole is fully managed — handled by the bring-up sequence in
roadmap/phases.md.
Ingress (north-south) via Gateway API
- Gateway API implemented by Cilium is the ingress layer (no separate ingress controller; reuses the CNI, ADR-0002).
- A shared Gateway defines HTTPS listeners on
*.home.keithjackson.devterminating TLS with the cert-manager cert (08). - Each service contributes an HTTPRoute mapping its hostname to its Service — rendered from the ServiceDefinition, not hand-authored.
- Exposure class is declared per service:
internal— reachable only on the LAN (no edge port-forward; internal DNS only).public— additionally reachable from the internet via the edge router forwarding 80/443 to the Gateway.
Edge integration
- The edge router/firewall forwards inbound 80/443 for
publicservices to the Gateway's address and applies multi-WAN inbound rules as needed (OQ-1). internalservices are never port-forwarded; they rely on internal DNS + Gateway on the LAN.- A stable ingress VIP for the Gateway is provided by the cluster's LB strategy (Cilium L2 announcement / BGP / a chosen LB); pin the mechanism in the networking bring-up.
Interaction with default-deny
Ingress opens north-south paths to the specific service; it does not relax east-west default-deny (03). A service being publicly reachable does not let other in-cluster services reach it unless an explicit allow rule exists.
Acceptance gates
- A new service's
<service>.home.keithjackson.devrecord appears automatically and routes to it. internalservices are unreachable from the public internet;publicservices are reachable and TLS-valid.- Internal clients resolve to the internal Gateway (no public hairpin) and get a trusted cert.
- The root
home.keithjackson.devserves the C2 UI.
Open questions
- OQ-1/OQ-4 — edge router product + DNS provider API (affects ExternalDNS provider config and inbound WAN rules).
- Gateway LB/VIP mechanism (Cilium L2 vs BGP) — pin during networking bring-up.