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]>
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# 09 — DNS & Ingress
|
|
|
|
Serves: **R-DNS-01/02/03**, **R-C2-01**, works with **R-TLS-***. Related:
|
|
[ADR-0002 (Cilium/Gateway API)](../decisions/adr-0002-cni-cilium.md).
|
|
|
|
## Naming model
|
|
|
|
- All services live at `<service>.home.keithjackson.dev` (e.g. `plex.home.keithjackson.dev`).
|
|
- The **root** `home.keithjackson.dev` serves the **Command & Control UI** ([12](12-command-center-ui.md)).
|
|
- Public apex `*.keithjackson.dev` resolves to the network's public IP; `*.home.keithjackson.dev`
|
|
is 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.dev` are created/updated/removed as services come and go.
|
|
|
|
## Split-horizon resolution (R-DNS-03)
|
|
|
|
Internal and external answers differ:
|
|
- **External** (`*.home.keithjackson.dev` from the internet): resolves to the public IP; reaches
|
|
the edge router, which forwards `public`-class services to the in-cluster Gateway.
|
|
- **Internal** (LAN clients): resolves `<service>.home.keithjackson.dev` to 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](08-tls-and-certificates.md)).
|
|
|
|
> 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`](../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](../decisions/adr-0002-cni-cilium.md)).
|
|
- A shared **Gateway** defines HTTPS listeners on `*.home.keithjackson.dev` terminating TLS with the
|
|
cert-manager cert ([08](08-tls-and-certificates.md)).
|
|
- 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 `public` services to the Gateway's address
|
|
and applies multi-WAN inbound rules as needed (OQ-1).
|
|
- `internal` services 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](03-networking-isolation-and-egress.md)). 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.dev` record appears automatically and routes to it.
|
|
- `internal` services are unreachable from the public internet; `public` services are reachable and
|
|
TLS-valid.
|
|
- Internal clients resolve to the internal Gateway (no public hairpin) and get a trusted cert.
|
|
- The root `home.keithjackson.dev` serves 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.
|