boma/docs/superpowers/specs/2026-06-11-public-dns-gandi-migration-design.md

# 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 | `<host>.boma.baobab.band` | internal zone (`dns1`/`dns2`, Phase 2) | never |
| Home / cluster services | `<service>.baobab.band` | internal zone (split-horizon) | only deliberate exceptions |
| Off-site / VPS services | `<service>.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: ["<home-ingress-ip>"], ttl: 1800 }
  - { record: askari,  type: A, values: ["<hetzner-ip>"],      ttl: 1800 }
  # mesh/LAN-only services are intentionally ABSENT — they live only in the internal zone.
# PAT referenced as {{ vault.gandi.pat }} (nested vault.<service>.<key>, 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 @<gandi-ns>`.
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 `<service>.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.