diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 3b1f416..ba35b03 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -176,4 +176,6 @@ Canonical dependency order: ## Next step -Brainstorm **M1 (Gandi DNS migration, IaC)** as its own sub-project → spec → plan. +**M1 (Gandi DNS migration, IaC)** design is written — +`docs/superpowers/specs/2026-06-11-public-dns-gandi-migration-design.md`. Next: user +review → implementation plan. diff --git a/docs/superpowers/specs/2026-06-11-public-dns-gandi-migration-design.md b/docs/superpowers/specs/2026-06-11-public-dns-gandi-migration-design.md new file mode 100644 index 0000000..4a91c23 --- /dev/null +++ b/docs/superpowers/specs/2026-06-11-public-dns-gandi-migration-design.md @@ -0,0 +1,196 @@ +# Design — Public DNS migration to Gandi (DNS-as-code) + +- **Date:** 2026-06-11 +- **Status:** Draft for review — design settled in brainstorming; pending user review, + then implementation plan +- **Roadmap milestone:** M1 (`docs/ROADMAP.md`) +- **Resolves:** TODO 4 (split-horizon FQDN — with/without `nyumbani`); review finding + O12 (ADR-007 FQDN convention contradicts its own example) +- **Amends:** ADR-007 — public DNS provider → **Gandi LiveDNS, managed as code**; the + three-tier naming scheme; `nyumbani` removed; mesh/LAN-only default exposure +- **Becomes:** an ADR-007 amendment (no new ADR unless the `public_dns` role grows + concerns of its own) + +--- + +## Problem + +Move `baobab.band` authoritative DNS **and registration** off Cloudflare to **Gandi**. +The driver is values/sovereignty (Gandi over Cloudflare) — it is **not** a NetBird +prerequisite, but it is sequenced first (roadmap M1) so `askari`'s records are born at +Gandi and Cloudflare is never touched again. Do it **as code**, consistent with boma's +grain: internal DNS is already Ansible-rendered and Terraform owns *no* DNS (CLAUDE.md). +While in here, settle the long-open naming question (`nyumbani`, TODO 4 / O12). + +## Decisions (as settled) + +1. **Full registrar transfer.** Registration *and* authoritative DNS move to Gandi — + fully exits Cloudflare. (DNS-only would strand the registration at Cloudflare and is + likely impossible anyway, since Cloudflare Registrar requires Cloudflare nameservers.) +2. **Three-tier naming scheme** (the convention — see table below). `nyumbani` is + **dropped**. +3. **Mesh/LAN-only by default.** Home/cluster services have **no public record**; they + are reached over LAN or the NetBird mesh. Public Gandi records exist only for + deliberate exceptions (today: `forgejo`, the `askari` tier). +4. **DNS-as-code via a control-node `public_dns` role** driven by structured record data + in `group_vars` — the same pattern as the firewall catalog, and exactly what ADR-007 + already calls "service/alias/split-horizon records … explicit zone data in + `group_vars`." Name is provider-agnostic on purpose. +5. **Tooling: `community.general.gandi_livedns` with `personal_access_token`** (PAT). + Re-adds `community.general` to `requirements.yml` under the collections-on-demand + policy (a committed role now uses `gandi_livedns`), pinned `>=9.0.0`, with the naming + comment. +6. **Clean by omission.** Stale records and the (unused) MX are *not* deleted at + Cloudflare — the zone is abandoned. Only wanted records are carried to Gandi. +7. **Cert scope: DNS + PAT only.** M1 ends at the migrated zone + the PAT in vault, which + *enables* ACME DNS-01 later. **No certificate issuance in M1** — that lands with a + reverse proxy (askari in M4, home in Phase 2). +8. **Human/agent division of labour** (see table) — account, payment, registrar + transfer, and the go-live nameserver flip are human; all record-wrangling, the IaC, + and the post-flip cutover are the agent's, executed from `ubongo`. + +## Verified facts (ADR-014) + +> verified: `community.general.gandi_livedns` requires `personal_access_token` (PAT); +> `api_key` is deprecated and **rejected** by Gandi (Bearer auth replaced Apikey) · +> WebFetch docs.ansible.com + WebSearch (Gandi PAT announcement 2023-09; community.general +> issue #7926) · PAT param added in **community.general 9.0.0**, **13.0.1** current · +> 2026-06-11 +> - Module params: `domain`, `record`, `type`, `values` (list), `ttl`, `state` +> (`present`/`absent`). Supports **check mode + diff**. +> - Auth is per-task: pass `personal_access_token: "{{ vault.gandi.pat }}"`. + +> unverified (from memory — confirm during implementation): the current registrar of +> `baobab.band` (WHOIS) — determines whether the transfer is Cloudflare→Gandi or +> elsewhere→Gandi, and the exact unlock/EPP steps. + +## Naming scheme (the convention) + +| Tier | Pattern | Authoritative source | Public? | +|---|---|---|---| +| Infrastructure / hosts | `.boma.baobab.band` | internal zone (`dns1`/`dns2`, Phase 2) | never | +| Home / cluster services | `.baobab.band` | internal zone (split-horizon) | only deliberate exceptions | +| Off-site / VPS services | `.askari.baobab.band` | Gandi LiveDNS | yes (askari has a stable public IP) | + +- **`nyumbani` removed.** It namespaced "home," but home is the default; only the + *exception* needs naming, and `askari.baobab.band` does that, self-documenting. +- **The mesh carries "internal" to road-warriors.** NetBird pushes `dns1`/`dns2` (over + `wt0`) as the resolver for the `baobab.band` match-domain, so on-LAN-or-on-mesh → + internal answer; truly public → Gandi (ties M1 ↔ ADR-016 / M5). +- **Wildcard TLS later.** A `*.baobab.band` (and `*.askari.baobab.band`) ACME **DNS-01** + cert via the Gandi PAT gives even unexposed services real public-CA TLS — without a + public A record. Enabled by M1, issued in M4/Phase 2. + +## Architecture — two deliverables (kept separate on purpose) + +### (A) One-time migration — a runbook (`docs/runbooks/`) + +Registrar transfers and the nameserver flip cannot be IaC'd. This is a human-gated +procedure (sequence below), executed once. + +### (B) `public_dns` — the reusable IaC role + +- Runs **from the control node** (`delegate_to: localhost`, or a `dns.yml` play targeting + `control`) against the Gandi LiveDNS API — there is no managed *host*, only API calls. +- Reconciles records from **`group_vars` data** via `community.general.gandi_livedns`, + PAT from `vault.gandi.pat`. +- **Check-mode/diff first**, always (boma's check-before-deploy; the module supports it). +- Carries only the public-tier records (exceptions + `askari` tier); the mesh/LAN-only + default keeps this set small. + +#### Data model (sketch) + +```yaml +# inventories/production/group_vars/all/public_dns.yml +public_dns__domain: baobab.band +public_dns__records: + - { record: forgejo, type: A, values: [""], ttl: 1800 } + - { record: askari, type: A, values: [""], ttl: 1800 } + # mesh/LAN-only services are intentionally ABSENT — they live only in the internal zone. +# PAT referenced as {{ vault.gandi.pat }} (nested vault.., CLAUDE.md). +``` + +#### Open design nuance — additive vs authoritative + +`gandi_livedns` is **per-record** (`present`/`absent`); it does not whole-zone sync. To +make the repo *authoritative* (prune undeclared records — cf. TODO 8.3's prune question), +the role would need to GET existing records and remove those not declared. **M1 decision:** +start **additive** (declare what we want; remove the old via explicit `absent` entries +during cutover); flag full-zone pruning as a possible later enhancement. Avoids +accidentally deleting a record someone added out-of-band before the repo is the single +source of truth. + +## Cutover sequence (the runbook) + +Legend: **[H]** human · **[A]** agent (from `ubongo`, committed code + check-mode). + +1. **[A]** Inventory: parse the **Cloudflare zone export** (BIND file the user downloads, + tokenless) → full record list; classify keep / rename / drop (incl. unused MX + stale). +2. **[A]** Draft `public_dns__records` (new scheme) + the `public_dns` role; PR/commit; + `make check` shows the intended Gandi state as a diff. +3. **[H]** Create/verify the Gandi account; issue a **LiveDNS-scoped PAT** for + `baobab.band`; store it in vault (`vault.gandi.pat`) via rbw. **[H]** Lower TTLs on the + *old* Cloudflare zone ~24–48h ahead. +4. **[A]** Create the zone in Gandi LiveDNS and load records (`make deploy`, after a clean + `make check`). Validate with `dig @`. +5. **[H]** Initiate the **registrar transfer** to Gandi (unlock at Cloudflare, get + EPP/auth code, start at Gandi, ACK to expedite; ~5 days — DNS keeps resolving). +6. **[H, go-live]** **Flip nameservers** to Gandi LiveDNS. (Irreversible/outward-facing — + explicit human go.) +7. **[A]** Post-flip: validate resolution; **rename the Forgejo remote + CI** + (`forgejo.nyumbani.baobab.band` → `forgejo.baobab.band`); verify a push. +8. **[A/H]** Confirm propagation; **[H]** decommission the Cloudflare zone. + +## Division of labour & access (security posture) + +| Task | Who | How | +|---|---|---| +| Zone inventory | Agent | From the Cloudflare **export** (tokenless). | +| New record set + `public_dns` role + data | Agent | Committed IaC; `make check` diff. | +| Gandi account, transfer, payment | Human | Identity/billing/e-mail/ToS — not automatable. | +| Create zone + load records + reconcile | Agent | `public_dns` role on `ubongo`, PAT from vault, check-mode first. | +| Nameserver flip / go-live | Human-gated | Agent preps + validates; human flips. | +| Forgejo remote + CI cutover | Agent | After flip; verify push. | +| Delete stale Cloudflare records | Nobody | Cleaned by omission. | + +- **Minimal token scope.** Gandi PAT: **LiveDNS-only**, restricted to `baobab.band`. + Cloudflare: prefer the **tokenless export**; if an API token is used, **read-only, + single-zone, throwaway** — revoke once inventory is captured. +- **Tokens live in boma's vault** (`vault.gandi.pat`) via rbw — never pasted in chat. +- **Execution on `ubongo`**, not in any agent sandbox: committed role + `make check` → + `make deploy`. Irreversible/outward steps (NS flip, go-live) require explicit human + confirmation. + +## Testing & verification + +External-API reconciliation does not fit container Molecule cleanly (a nuance against +ADR-008 — not every role gets a converge-in-a-container scenario). Instead: + +- **`make check` (check-mode + diff)** against live Gandi before any apply. +- **Idempotence:** a second `make deploy` reports no changes. +- **`dig` assertions** post-cutover: new names resolve to expected values; a Forgejo + push over `forgejo.baobab.band` succeeds. +- Optionally a small pytest over the `public_dns__records` data shape (types, no + duplicate record/type pairs), mirroring `test_firewall_rules.py`. + +## Scope boundaries — what M1 is NOT + +- **Not** the internal split-horizon `dns` role (renders `.baobab.band` + privately) — that needs the `dns` role + actual home services → **Phase 2**. +- **Not** certificate issuance or the reverse proxy — **M4 (askari) / Phase 2 (home)**. +- **Not** authoritative whole-zone pruning — additive for now (see nuance above). + +## ADR work + +Amend **ADR-007**: public zone provider → **Gandi LiveDNS, managed as code** (replaces +"Cloudflare or equivalent"); record the **three-tier naming scheme**; remove the +`nyumbani` example; state the **mesh/LAN-only default**. Note `public_dns` as the +control-node role that renders the public zone (sibling to the internal `dns` role). + +## Open items (resolve during the plan / implementation) + +- **Cloudflare zone export** → the exact record list (execution input, not a design gap). +- **WHOIS** the current registrar → confirm transfer source + unlock/EPP steps. +- **Pin** the `community.general` version in `requirements.yml` (≥9.0.0). +- **Play wiring:** a dedicated `dns.yml` play (control-targeted) vs folding into an + existing play — decide in the plan.