DNS as Code: Zones in Git, Reviewed Diffs, and Drift You Can Actually See
Your servers are declarative. Your Kubernetes manifests are in git. Your cloud resources have a plan step, a review, and an audit trail. And then there’s DNS: a web console, a text field, a Save button, and an outage that nobody can diff.
This is strange, because DNS has the worst blast radius of anything on that list. A wrong A record takes down the site. A deleted MX record silently discards mail for hours before anyone notices. A dangling CNAME pointing at a deprovisioned cloud bucket is a subdomain takeover waiting for someone to claim the other end. And the change that caused it has no author, no reason, and no previous version to restore.
Managing zones as code fixes the governance problem, which is the real problem. The tooling is the easy part.
What Hand-Edited DNS Actually Costs
Four failure modes, all common, all eliminated by a reviewed diff:
The record nobody knew was load-bearing. Someone cleans up what looks like a stale entry. Three weeks later a quarterly batch job fails because it resolved that name. In a repo, deleting a record is a diff with a blame trail and a reviewer who might remember.
TTL left at the wrong value. Someone drops a TTL to 60 for a migration and never raises it, so you serve ten times the query volume forever. Or a TTL sits at 86400 and your failover takes a day. TTLs are invisible in a console listing and obvious in a diff.
Incident edits that never get reverted. At 3am the console is genuinely faster than a pull request, so people use it. That’s not a process failure — it’s correct behavior. The failure is that the change becomes permanent and undocumented.
Dangling CNAMEs. A CNAME to something.s3.amazonaws.com or app.herokuapp.com outlives the resource it pointed at. Anyone can then claim that resource name and serve content on your subdomain, with a valid certificate they obtained themselves. This class of bug is found by inventory review, and inventory review is only possible when the inventory is a file.
Three Tool Families
OctoDNS
Python, originally from GitHub, built around one idea: zones are data, providers are interchangeable. You write YAML and declare which providers it syncs to.
|
|
|
|
|
|
The dry run being the default is a design decision worth appreciating. The killer feature is that targets list: one source of truth, synced identically to two providers, which is the foundation of multi-provider redundancy below. octodns-dump generates YAML from a live zone, which is how you adopt it without retyping anything.
DNSControl
Go, from Stack Overflow, with zones defined in JavaScript. That sounds eccentric until you manage forty similar zones and realize you have loops, functions, and variables:
|
|
|
|
Shared record sets as variables is the real win — define your mail records once and include them in every zone, and a DMARC policy change is a one-line diff across all of them. The tradeoff is that reviewing a JavaScript DSL requires slightly more care than reviewing YAML, since logic can hide intent.
Terraform / OpenTofu
Every record becomes a resource in your existing IaC.
|
|
The genuine advantage: the A record and the load balancer it points at live in the same module, created and destroyed together, so you cannot leave one orphaned. That eliminates the dangling-pointer class of bug structurally.
The costs are real too. Five hundred records means five hundred state entries, and terraform plan on a large zone is slow. Importing an existing zone is tedious — one import block or command per record. Provider coverage for DNS is uneven. And pin your provider version: the Cloudflare provider’s v5 release renamed DNS resources (cloudflare_record became cloudflare_dns_record), which is a migration, not an upgrade. Check your provider’s current resource names rather than trusting any example, including this one.
Choosing
Already all-in on Terraform, and most records accompany infrastructure you provision anyway? Use Terraform — the coupling is the point.
DNS is its own domain with hundreds of records, or you want provider redundancy? OctoDNS or DNSControl. They’re built for zones rather than resources, and they adopt existing zones in one command.
Many near-identical zones? DNSControl, for the DSL.
The Workflow Is the Product
The tool matters less than the pipeline around it. The target is: a pull request shows the diff against live DNS, a human approves, merge applies it.
|
|
Three details in there carry most of the safety.
The plan job gets a read-only token; only the apply job gets write. This is not fussiness. A workflow that runs on pull requests executes code from the branch being proposed. Give that job a DNS-write credential and anyone who can open a PR can rewrite your zone — and the pull_request_target trigger, which does expose secrets to fork PRs, is a well-known footgun. Read-only for plan, always.
The apply job uses a protected environment, so the write credential is gated behind required reviewers rather than merely behind branch protection.
There’s a scheduled run. That’s the drift detector, and it’s the part almost everyone omits.
Add a CODEOWNERS entry for the zones directory so DNS changes require a specific reviewer, and your audit trail is complete: who, what, when, why, and what it replaced.
Drift Is Not a Process Failure
Someone will edit the console. Assume it, detect it, and decide in advance what happens next.
Detection is a scheduled plan with a non-empty diff treated as an alert. Terraform makes this explicit with an exit code:
|
|
|
|
Then write down the reconciliation policy, because the argument during an incident is worse than the decision beforehand. A reasonable default: drift is reverted, and if the console change was correct, it gets re-submitted as a PR afterward. The alternative — adopting drift into code automatically — sounds friendly and quietly legitimizes bypassing review.
The shared-zone trap
This one bites hard and specifically. Tools that manage a whole zone will delete records they don’t know about. If anything else writes into the zone, your next apply destroys its work.
The most common collision is ACME. A DNS-01 challenge creates a TXT record at _acme-challenge, and if your DNS-as-code apply runs mid-issuance, it removes it and the certificate order fails. The same applies to Kubernetes external-dns, cert-manager, and any dynamic-update process.
Exclude those names explicitly:
|
|
OctoDNS handles the same need with ignore processors and per-record octodns: lenient settings. Whatever the mechanism, the better architecture is to not share: delegate _acme-challenge to a separate zone with a static CNAME, which keeps the challenge records out of your managed zone entirely and shrinks the credential blast radius at the same time — the reasoning is in the DNS-01 post. Similarly, give external-dns its own subdomain to own rather than letting two systems contend for one zone.
Multi-Provider Redundancy
In October 2016 a DDoS against Dyn took down a large slice of the internet’s recognizable names — not because those services failed, but because nobody could resolve them. A single DNS provider is a single point of failure in front of everything you run.
Serving one zone from two providers means listing both providers’ nameservers at your registrar and keeping the zone contents identical in both. OctoDNS’s targets list does exactly this; with DNSControl you declare multiple DnsProvider() entries.
|
|
Verify both actually agree, rather than trusting the apply:
|
|
Be clear-eyed about the constraints, because this is where multi-provider setups go wrong:
You get the intersection of provider features. Proxied/CDN records, weighted and geographic routing, and health-checked failover are provider-specific inventions. A portable zone can’t use them.
Apex ALIAS/ANAME records don’t port. CNAME-at-apex flattening is each provider’s own non-standard extension with different names and semantics. If your apex points at a hostname rather than an IP, portability gets painful fast.
DNSSEC across two providers is genuinely hard. It requires the multi-signer model of RFC 8901, with coordinated key sets, and most provider pairs don’t support it cleanly. This is a real fork in the road: multi-provider redundancy and DNSSEC are both good, and having both is an advanced project. Pick deliberately rather than discovering the conflict halfway. The single-provider DNSSEC story is covered in the DNSSEC post.
The NS record sets must match at the registrar and inside both zones, or resolvers get inconsistent delegation answers.
TTL Discipline Becomes Reviewable
TTLs are the one DNS field that is both operationally critical and completely invisible in a console listing. In a repo they’re a number in a diff, which makes a discipline possible that otherwise never happens.
The pattern for any planned migration is two pull requests, days apart:
|
|
Merge that at least one old-TTL period before the cutover — an hour in this case — so every resolver has had time to pick up the shorter value. Then the actual migration is a one-line change that propagates in a minute instead of an hour, and a third PR raises the TTL back afterward.
Doing this by hand means remembering three steps across several days. As code it’s a reviewable sequence where the second step can’t be merged early by accident, and the final “restore TTL” PR can be opened immediately and left for later.
Two related numbers worth putting under review at the same time. The zone’s SOA minimum governs how long negative answers are cached, so a high value means a newly created record can appear not to exist for far longer than its own TTL suggests — the trap behind most “the record is there but validation fails” reports. And low TTLs are not free: they multiply query volume against your providers, which matters both for cost and for rate limits.
Testing Before It Goes Live
There are three distinct checks, and teams usually have only the middle one.
Validation catches malformed config with no API calls at all, which makes it fast enough to run on every commit:
|
|
This is where transposed SRV fields and missing trailing dots get caught, before a reviewer’s time is spent.
The plan shows the diff against live. That’s the artifact humans review, and it’s the one everyone already has.
Post-apply verification is the missing piece. An apply that returns success means the provider’s API accepted your change — not that resolution is correct. The authoritative servers may lag, one provider in a multi-provider setup may have silently diverged, or you may have created a record that is syntactically valid and semantically wrong. Assert the outcome:
|
|
Running that loop across every nameserver, rather than once through a recursive resolver, is what catches partial propagation and provider divergence. It takes seconds and turns “the apply worked” into “resolution is correct,” which are not the same claim.
For genuinely risky changes — a mail migration, a DNSSEC key rollover, restructuring a delegation — keep a scratch domain with the same provider set and rehearse there. Registering a throwaway domain is a few dollars a year and considerably cheaper than discovering a provider’s apex-record behavior during a production cutover.
Things That Bite
Trailing dots. example.com versus example.com. is the single most common syntax bug in every one of these tools. A relative name gets the zone appended, so a CNAME to example.com can become example.com.example.com. Absolute names end with a dot. Always.
Structured record types. MX preferences, SRV priority/weight/port, CAA flag/tag/value, TLSA selectors — all easy to transpose and all silently broken rather than loudly invalid. Run the validation step (dnscontrol check, octodns-validate) in CI, not just the plan.
SOA and NS at the apex are frequently not manageable by the tool, or manageable with special care. Expect them to be exceptions.
Provider API rate limits. A first apply on a thousand-record zone can hit them. Most tools batch; some need throttling.
Token scope. The credential your pipeline holds can rewrite your zone, which makes it one of the higher-value secrets you own. Scope it to one zone, use separate read and write tokens, and rotate them — and remember that an expired token is an outage with no warning.
Adoption order. Never hand-write the initial config. Dump the live zone (octodns-dump, dnscontrol get-zones, or Terraform import blocks), commit that, and then prove a zero-diff plan before you change a single record. Your first successful run must be a no-op. If it isn’t, your config doesn’t match reality yet, and applying it will delete whatever you missed. This is the single most important step in the whole migration, and skipping it is how DNS-as-code projects become outages.
Verdict
The reason to do this isn’t elegance, it’s that DNS changes are currently your least-reviewed, highest-blast-radius production edits. Putting zones in git converts them into diffs with authors, reviewers, and a revert path.
Pick the tool by shape: Terraform when records accompany infrastructure in the same module, OctoDNS when you want provider portability or redundancy, DNSControl when you have many similar zones and want a real DSL.
Then do the three things that make it work rather than merely exist. Give the plan job read-only credentials and the apply job a protected environment, because a PR-triggered workflow with a DNS write token is worse than the console you replaced. Run a scheduled plan and alert on any diff, because console edits will happen and silent drift makes your repo a comforting fiction. And exclude the names other systems own — _acme-challenge first and foremost — or your next apply will delete a certificate challenge mid-issuance.
Start by dumping your live zones and achieving a zero-diff plan. Everything after that is ordinary code review.
Comments