Skip to content

feat(dns): hand www to the platform's external-dns without a gap - #76

Merged
devantler merged 19 commits into
mainfrom
claude/dns-www-handover
Nov 15, 2026
Merged

devantler merged 19 commits into
mainfrom
claude/dns-www-handover

Conversation

@devantler

@devantler devantler commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Why

www.devantler.tech should be served by the platform, not GitHub Pages, and follow the platform gateway on its own.

What

  • Creates the ownership record that lets the platform's external-dns take over the existing www record. This repository stops managing www, but the record itself stays. Within a minute external-dns swaps www to the gateway addresses in one Cloudflare transaction, so www never goes without an address. The record name and content were confirmed with the platform cutover (platform#6177).
  • Keeps the encrypted state from the adoption apply (feat(dns): adopt the zone's DNS records through a guarded plan and apply #75, run 43674749476) as the retained recovery copy. The DNS workflow requires that copy before it will run this change.

The rollback plan is in the comment below.

Part of #21

🤖 Generated with Claude Code

devantler and others added 11 commits November 15, 2026 02:51
Declare the records this repository owns in dns.tf and add a main-only
"DNS plan and guarded apply" workflow against the authoritative R2 state.
It imports a declared record only when exactly one unowned live record
matches it, refuses deletes, replacements and changing imports, encrypts
state before and after every apply, and proves a clean plan from a fresh
runner. External-dns records, including the SES bounce records, stay with
external-dns. The email-only import proposal is superseded and removed.

Part of #21. Part of #65.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Create external-dns's ownership record for the existing www CNAME and
forget the CNAME here, so external-dns replaces it with the gateway
addresses in one batch.

Part of #21.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Refuse a create that an external-dns ownership record already claims,
  even when the claimed record itself is missing.
- Compare record names in full lower-case form, so a relative or
  differently written `_externaldns` name cannot pass the apex guard.
- Keep OpenTofu's errored.tfstate in the encrypted evidence when an apply
  cannot save its state to R2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jq 1.8 parses `X and Y as $v | body` with the whole and-expression as the
binding, so the external-dns ownership check always found no owner on the
Ubuntu 26.04 runner. Bind the name first; the tests pass on jq 1.7 and 1.8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep the names of live records that nothing owns in the encrypted evidence
and print a count by type, so the public log never lists hostnames.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From a fresh local review:
- Never import a live record that a resource already manages, and leave
  managed siblings out of the content-differs check.
- Let an `_externaldns.` ownership record claim only a record that the same
  plan stops managing, read both typed and typeless, so no marker can hand
  a mail record such as the DKIM CNAME to external-dns.
- Refuse a create or update of a record external-dns owns, or one without
  a known name.
- Print addresses only for the records in dns.tf; anything keyed by the
  private configuration appears as a count.
- Stop the apply with SIGTERM only, so a timeout cannot leave the R2 lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devantler

Copy link
Copy Markdown
Contributor Author

Rollback plan, written before the apply

What this apply does: it creates _externaldns.cname-www.devantler.tech, and this repository forgets the www CNAME. That CNAME still points at devantler.github.io. Within about a minute, external-dns (policy sync, owner platform.devantler.tech) deletes the CNAME and creates www A and AAAA records pointing at the gateway, proxied, in one Cloudflare batch. It also replaces the marker with _externaldns.a-www and _externaldns.aaaa-www.

How to check it worked: www.devantler.tech resolves to Cloudflare, answers with a 301 to https://devantler.tech/<path>, and both new markers exist. The platform cutover session verifies this live.

If it goes wrong:

  1. The apex does not depend on this change. devantler.tech stays on GitHub Pages until feat(dns): point the apex at www and stop managing the www handover #77, so the main site keeps working whatever happens to www.
  2. external-dns never takes over (the CNAME stays): nothing changes for visitors. www keeps serving GitHub Pages. This repository forgot the record, so no apply here will touch it. Investigate on the platform side.
  3. www is broken on the gateway: fix it forward on the platform first. www only redirects to the apex.
  4. Return www to Pages: the platform removes www.devantler.tech from the business-site-public route. external-dns then deletes the www A/AAAA records and their markers. After that, a pull request here declares the www CNAME again: devantler.github.io, proxied, plan then apply. This path has a short gap for www only: about a minute of no answer, which resolvers may cache for up to 30 minutes. It cannot be gap-free, because a CNAME cannot sit next to A records.

🤖 Generated with Claude Code

devantler and others added 6 commits November 15, 2026 04:32
…ide private refusals

- Refuse an update that moves a record external-dns owns, not only one
  that lands on an owned name.
- Require an upper-case record type for every write and compare types
  case-insensitively when resolving imports, so a `txt` marker cannot skip
  the claims check.
- Report a refusal for a record keyed by the private configuration
  without its address.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From a second local review round:
- An `_externaldns.` ownership record must claim at least one live record,
  and every live record it claims must be one the same plan forgets. It can
  no longer hand an unmanaged record, such as another DKIM selector, to
  external-dns.
- Record names on writes use hostname characters only.
- Import resolution stops if the plan's prior state lacks the zone, instead
  of treating the managed set as empty.
- The apply gets a fresh 15-minute state session and a 5-minute SIGTERM
  bound, so its state save and unlock never run on expired credentials.
- The runbook describes what to do after a failed or partial apply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pply

From the third local review round:
- Match write names against the whole string (\A…\z), so a trailing
  newline cannot slip past the hostname pattern or the ownership check.
- Stop a slow apply with SIGINT sent to OpenTofu alone (--foreground), so
  the provider plugin finishes its in-flight call and the result is saved.
- Test that a marker is refused when the forget lacks or mismatches the
  claimed record's id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from claude/dns-adoption to main November 15, 2026 03:58
devantler and others added 2 commits November 15, 2026 04:59
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	dns.tf
The import-only apply in run 43674749476 (source 457727e) moved the
authoritative state from serial 3 to 4 on the same lineage, with the
configuration unchanged. Its `after` package and the fresh runner's
`recovered` package both authenticate with the independent identity and
carry the same state digest. The DNS workflow requires this generation
before its next run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@devantler devantler left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Local review at 994877c. CodeRabbit is out of its hourly allowance until about 04:30 UTC, and Codex and Bugbot are at their usage limits. The diff is small: one ownership record, one removed block, and the retained state copy.

  • Marker name and content: they match what the platform cutover confirmed. The name is _externaldns.cname-www.devantler.tech. The content is quoted exactly like the existing markers in the zone, for example _externaldns.a-portal, with owner platform.devantler.tech and resource httproute/business-site/business-site-public. The name is in-zone and typed. It is not the typeless apex name.
  • Boundary check: the plan creates the marker, which claims the live www CNAME. The same plan forgets that record (removed, destroy = false). OpenTofu's plan JSON for a forget carries the record's before.id. I checked that with OpenTofu 1.12.6, so the claim matches the forgotten id. Nothing else changes.
  • Retained state: the after package of run 43674749476 authenticates with the independent identity (VERIFIED scope=authenticated-files). Its state digest equals the fresh runner's recovered package. The lineage is unchanged, the serial moves 3 → 4, and the configuration plaintext digest is unchanged, so the configuration secret still matches.
  • scripts/test.sh passes (21 suites).

Clean at 994877c. I'll run the plan and check that it shows exactly one create (the marker) and one forget (www) before applying.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant