Post

Adding a Read-Only Preflight for Exit-Node Drift Before the DNS Cutover

Adding a Read-Only Preflight for Exit-Node Drift Before the DNS Cutover

My AdGuard DNS cutover script previously assumed the saved Terraform plan and the live resolver state agreed. Split-DNS resolver drift broke that assumption, so I added a preflight that reads the exact-main policy, the private saved plan, and live DNS, tolerates one in-place exit-node flag repair plus its matching inverse refresh drift, and reports readiness without applying anything or writing a cutover receipt.

Isolating DNS change validation in the cutover script

I extracted the per-resource checks from validate_plan into a dedicated validate_dns_update helper. It pins the resource address, mode, and type to the single managed Tailscale DNS configuration resource, requires a pure update action with no replacement paths and no previous address, rejects unknown values, and compares the before and after policy against the reviewed transition. It also asserts the DNS singleton identity exists and is unchanged, and returns that identity so the caller can reuse it. validate_plan now takes an allow_inverse_dns_drift keyword, which keeps the strict default path intact while letting the new preview mode admit a narrowly bounded drift shape.

What the new split exit-node preview verifies

A new preview_split_exit_node path reads three inputs: the exact-main policy, the private saved plan, and live DNS. It accepts a single in-place repair of the exit-node flag on the resolver entry and only the matching inverse drift recorded during refresh, then reports plan readiness. Crucially, it stops short of applying or recording a cutover receipt, so the read-only check can run as a gate rather than as a mutation. The bounded tolerance is the interesting part: instead of relaxing validation generally, I encoded exactly the drift I expect and nothing wider.

Tests covering both drift and clean states

The new SplitExitNodePreview case builds fixtures from the baseline and desired policies, then flips use_with_exit_node on the first nameserver of the live policy to simulate the split-resolver mismatch. One fixture mirrors the saved plan with a healthy refresh, the other adds a resource_drift entry that swaps the before and after of the change. The test runs both variants through a subtest, stubs the adapter for source policy, baseline policy, live policy, plan read, and plan hash, and asserts that live policy is read twice during the preview. That establishes the code path and the double-read behavior under test; it does not prove the production cutover runs clean, so the next check is running the preview against the real homelab state before any apply. I also recorded the accepted drift shape in validation-gates.md alongside the existing gate descriptions.

Where this preflight pattern transfers

The generalizable piece is treating drift tolerance as an explicit, enumerable set rather than a relaxed comparison. A platform team applying this would extract one validator per singleton resource, pin the reviewed transition, and add a read-only preview entry point that accepts only named drift shapes — here an exit-node flag repair and its inverse refresh counterpart — while still refusing replacements, unknown values, and identity changes. That keeps a pre-apply check honest, gives reviewers a precise statement of what will be tolerated, and leaves the applying path untouched until someone deliberately runs it.

This post is licensed under CC BY 4.0 by the author.