DNS manager and records

Last verified: 2026-11-05 (repository inspection of tcpsystems/docs and sibling tcpsystems/dns README/spec/credential docs; no live DNS provider calls made). Scope: tcpsystems/dns provides provider-abstracted DNS/CDN desired state, validation, drift and audited apply workflows. This page documents operator checks and ownership boundaries. It does not mutate DNS records.

Ownership boundaries

Surface	Owner	Notes
DNS product code, API, validation, drift/apply logic, tests	tcpsystems/dns	Source of truth for implementation details
Provider credentials and token custody	Lead/operator secret custody path	Credentials are env-name references in config and API output; values are never committed
Zone declarations and approved record changes	DNS/operations owners with change approval	Desired state is reviewed; live provider state is checked for drift
Edge exposure of console/API, Caddy routes, Access/WAF	Lead/edge owners	dns docs state the console is loopback-only in slice 1 and edge exposure is a separate decision
Registrar, NS delegation, manual DNSSEC DS steps	Human-approved registrar/owner actions	Do not automate registrar trust-root changes

Concepts

• Desired state is not live state. The manager validates and plans changes; provider records are not silently rewritten.
• Dry-run is the default posture. Real provider mutation requires explicit intent (dry_run:false) and zone confirmation as defined by the DNS API/spec.
• Prune is explicit. Records present at the provider but absent from desired state are drift candidates until a human-approved prune path is used.
• Credentials are names, not values. Config and responses refer to environment variable names; missing credentials fail closed.
• Audit is part of the product contract. Mutations are recorded in an append-only, hash-chained audit log in the DNS service design.

Prerequisites

• Access to the dnsd API host (loopback-only by default in slice 1) and an operator token supplied out of band.
• The zone name and provider are known and approved for the action.
• Provider credentials are configured in the service environment for the specific provider, when a real plan/apply is approved.
• For production-impacting changes: a change window, BIND/export backup per apply, and explicit approval. For tcp.systems, the DNS spec calls for read-only import and drift checks first.

Local and read-only verification workflow

The commands below use environment variable names and local examples. Replace values outside the repository and never record secret values in docs, logs or commits.

# Service/operator checks (paths and unit names are deployment-specific):
curl -fsS http://127.0.0.1:7310/healthz

curl -fsS -H "Authorization: Bearer $DNS_OPERATOR_TOKEN" \
  http://127.0.0.1:7310/v1/dns/capabilities | jq

# Manage a zone in desired state (no provider mutation by itself):
curl -fsS -H "Authorization: Bearer $DNS_OPERATOR_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"example.com","provider":"cloudflare","comment":"read-only onboarding"}' \
  http://127.0.0.1:7310/v1/dns/zones

# Read-only provider import and drift checks are the safe first step for live zones.
# Use the exact endpoint names and request shape from tcpsystems/dns openapi/dns-v1.yaml.

# External DNS observation (read-only):
dig +short example.com A
dig +short example.com AAAA
dig +short example.com MX
dig +short example.com TXT
dig +dnssec +short example.com DNSKEY
dig +dnssec +short example.com DS @1.1.1.1

If the console is enabled in a deployment, it is loopback-only in slice 1 (http://127.0.0.1:7310/console/dns) and read-only. Do not expose it publicly from this repo.

Failure handling

Symptom	First checks	Safe action
401 from DNS API	Confirm operator token is supplied and valid for that environment	Rotate token through the approved secret path; do not paste token values into tickets or docs
Provider configured:false or missing credential	Check capability output for env NAMEs; verify service environment has those names set	Fix secret injection at the deployment owner; missing credentials are expected to fail closed
Drift reported	Compare desired records, live provider records, and recent approved changes	Resolve by updating desired state or making an approved apply; never hide drift by editing docs claims
Validation errors	Read the validation response and record type/TTL/CAA/SPF/DMARC details	Correct desired state and revalidate; validation should block apply before provider mutation
DNSSEC/DS uncertainty	Use dig for DNSKEY/DS/RRSIG and check registrar state separately	Treat DNSSEC and DS changes as manual, human-approved; stop and escalate
Console/API unavailable	Check local health endpoint and service logs on the host (journalctl -u dnsd where that unit exists)	Do not make blind provider changes; restore observability first

Rollback and safety checks

• Keep a BIND/export backup before any approved real apply. The DNS platform spec requires a backup artifact per apply.
• Prefer scratch-zone rehearsals before touching production zones.
• Real applies use explicit confirmation and avoid prune unless separately approved.
• A bad DNS change is rolled back by applying the previous known-good desired state or provider restore procedure owned by the DNS operators; record the command outputs and timestamps as evidence.
• Never store Cloudflare/Bunny/ClouDNS tokens, global keys, or operator tokens in this repository.

Integrator notes

• docs.tcp.systems and other hostnames depend on DNS, but DNS records are not generated from this docs build.
• When documenting a hostname or record change, cite the change window, approving owner, and verification command output date.
• Do not state that a DNS change is in effect until read-only checks (dig, provider status, or API status) confirm it after propagation.