Skip to content
RedundantDNS
Menu

View as Markdown

The provider layer

RedundantDNS keeps one canonical copy of each zone and writes it to two or more DNS providers. Everything provider-specific lives behind one small Go interface, so adding a provider never touches the product code. This page explains that layer for engineers and for curious customers: the contract every adapter implements, the two access levels, what each provider can serve, and what managed mode means per provider.

Azure DNS is coming soon. Its adapter is part of the platform and described below, but new Azure connections are not offered yet (the connection form shows it as "Coming soon"; the API answers 422 providerComingSoon). The other providers on this page are available.

The adapter contract

Every provider is an adapter behind providers.Provider (pkg/providers/provider.go in the platform source). Adapters are pure translators between the canonical model (pkg/dnscore) and one provider's API: no UI, no storage, no product logic, and they never read ambient credentials (~/.aws, ~/.oci, ~/.config/gcloud, ~/.azure or CLOUDFLARE_*). Each one is tested with a fake SDK client, never against a cloud (the self-hosted adapter against an in-memory PowerDNS API).

MethodWhat it does
Capabilities()What the provider can serve (the matrix below). A zone's effective capability is the intersection over its providers, checked on the server before any write.
ValidateCredentialsChecks a grant for an access level: list zones (create and manage) or read the one zone given (manage an existing zone, mirror source; read calls only).
CreateZone / DeleteZone / FindZoneZone lifecycle; FindZone finds a zone by id or by name for adoption.
ListRecordSetsWhat the provider serves, as canonical record sets (SOA excluded, apex NS included).
ApplyChangesApplies a diff (create, update, delete per name and type). Idempotent: a retry after a partial failure converges.
QueryMetricsQuery counts of a zone over a period (managed-mode billing); nil when the provider does not expose them.

Three optional interfaces cover provider quirks: ZoneStatusReader (a provider-side zone status the customer must see, Cloudflare's "pending" or "moved"), ZonePreparer (a setting to change before the platform manages an adopted zone: Cloudflare's Multi-provider DNS) and ZoneChecker (record sets the provider refuses because of the rest of the zone, skipped before anything is sent: OCI's delegations without glue). ApplyChanges returns providers.BatchRejected when the provider refuses the content of a write (a validation error): the data plane then isolates the refused record sets, writes the rest and skips them at that attachment (provider-rejected), even when the write held only refused sets (a single bad edit). Every adapter types its provider's refusals; anything else (authorization, a missing zone, throttling, a server error, the network) stays a failed call that is retried and, when it persists, turns the attachment error (sync_error):

AdapterRefusal (BatchRejected)Not a refusal (retried)
route53InvalidChangeBatch, InvalidInputThrottling, PriorRequestNotComplete, AccessDenied, NoSuchHostedZone, 5xx, network
ociHTTP 400 (InvalidParameter and the like) on a record write401/403/404, 429 and 5xx (retried in the adapter first), network
gcpHTTP 400 on a Change (invalid, invalidRecordData, ...)401/403, 404, 412 (stale deletion), 429, 5xx, network
azureHTTP 400 on a record set write401/403, 404, 409, 429, 5xx, network
cloudflareHTTP 400 or 422 on a record batch (9005 invalid content, 9007 invalid TXT or NS content, 9009 MX to an address, 9039 CNAME to itself, 81053 record already exists, ...), except an unknown zone (codes 7003, 1001)403 (token), 404, 429, 5xx, network
selfhostHTTP 422 (PowerDNS refuses an RRset) and 400 on the zone PATCH401/403 (API key), 404, 5xx, network

Isolation re-sends the parts of a write that went through, so every write must stay idempotent per record set: Route 53 refuses a whole request that deletes a set that no longer exists, and its adapter drops such a DELETE (it has reached its goal) and sends the rest of the request again. For adapters that do not type an error, the data plane still isolates a refused write when part of it is accepted. A call on a zone the provider is still creating returns an error wrapping providers.ErrZoneCreating: the attachment stays pending and the sync is retried.

The data plane is the only caller: it diffs the canonical zone plus the apex NS plan (the union of every attached provider's nameservers) against what each provider serves, applies the diff on reconcile, and records drift on verify. A change made directly at a provider is never overwritten silently.

Access levels

Each connection grants one of three levels. Each provider's guide lists the exact permissions (and the connection form shows them, ready to paste).

LevelWhat RedundantDNS can do
Create and manage zones (zone_admin)Create the zone at the provider, write its records and apex NS, and delete it when you detach (only after you type the zone name).
Manage an existing zone (zone_editor)Read and edit the records of a zone you created and whose id you give per attachment. It never creates or deletes zones.
Mirror source (read-only) (mirror_source)Only read a zone you keep editing at the provider, whose id you give per attachment. It becomes the zone's source of truth and is copied to the other providers; RedundantDNS never writes to it, not even its apex NS set.

Adopting an existing zone

Attaching a zone that already exists at the provider (Create and manage zones with "adopt it", or Manage an existing zone with its id) adopts it. RedundantDNS never deletes its records silently:

  • Into a new, empty zone in RedundantDNS, the provider's records are imported first ("N record sets will be imported"). Sets of a type RedundantDNS does not model, or that another attached provider cannot serve, stay at the provider and are listed.
  • Into a zone that already has records, record sets that exist only at the provider stop the attach and the dashboard shows the difference: Import them (they join the zone; where both sides have a set, the zone in RedundantDNS wins) or Overwrite (explicit, confirmed: they are deleted at the provider). The API answers 409 adoptWouldDelete with the same diff; repeat with onAdopt: "import" or "overwrite".
  • Until an adopted zone's first sync completes, no reconcile deletes a set that exists only at the provider, whatever triggered it, unless you chose overwrite: the sets are kept and listed on the attachment until you adopt them or overwrite them. After that first sync, the zone in RedundantDNS is the source of truth and drift is handled as usual.

The apex NS and SOA sets are the provider's and the platform's own: they are never imported. See docs/api.md, "Adopting an existing provider zone".

Destructive safety

What RedundantDNS writes to a provider zone you connect (v0.1.18):

  • Verify only until you decide. A zone you already had at the provider (adopted) is only read and compared: the attachment shows the differences and writes nothing until you click Start applying. A zone RedundantDNS creates for you applies at once.
  • Only what RedundantDNS manages is ever deleted. A record set at the provider that was never part of the zone in RedundantDNS (added by hand, by another tool) is listed as not managed and kept, whatever syncs; import it into the zone or delete it explicitly.
  • Large deletions wait for you. A sync that would delete more than 10 record sets, or 20 % of the provider zone if that is more, writes nothing until an admin confirms (or cancels) it on the attachment.
  • A snapshot comes first. Before any sync deletes record sets, the provider zone is saved (kept 90 days) and can be restored from the attachment's history.
  • Every deletion is announced to your alert channels (provider_records_deleted).

Capability matrix

Numbers come from each adapter's Capabilities value and its comments in pkg/providers/<provider>/; where a provider does not document a bound, the adapter uses a conservative one, marked "from the code".

Route 53OCI DNSGoogle Cloud DNSAzure DNS (coming soon)CloudflareSelf-hosted (PowerDNS)
Record typesA, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTRsamesamesamesamesame (PowerDNS also serves TLSA, HTTPS, SVCB: not in the canonical model yet)
TTL range (seconds)0 to 2,147,483,6471 to 604,800 (OCI enforces the maximum; it accepts 0, the adapter keeps 1)1 to 2,147,483,647 (from the code: not documented)1 to 2,147,483,64760 to 86,400 (30 on Enterprise; not used)1 to 2,147,483,647
Apex NS editableyesyes, OCI's own four are protected and always keptyesyes, Azure's own four are always keptyes, with the Multi-provider DNS setting (turned on by the adapter)yes
Wildcardsyesyesyesyes (not for NS and SOA)yesyes
CNAME at the apexnonononoyes (CNAME flattening)no
Max values per record set100 (from the code: Route 53's real cap is request-size based)100 (from the code)10,00020no documented limitno limit (DNS message size)
TXT length (characters per value)4,000 (from the code)4,000 (from the code)4,000 (from the code: 255 per string, 100 KB per change)4,096 per record set2,048 per record (8,192 per name and type)no limit (255 per string)
BatchingChangeResourceRecordSets: up to 1,000 changes and 1,000 values per request (an upsert counts its values twice)PatchZoneRecords for new and deleted sets (up to 500 operations and 256 KiB per call); one UpdateRRSet per updated set and for the apex NS setone change per batch: up to 1,000 additions, 1,000 deletions and 100 KB of dataone call per record set, deletes firstbatch endpoint: delete and repost a set's records in one request, up to 200 operations eachone PATCH per diff (REPLACE/DELETE per record set, one transaction)
Zone status readingnonononoyes: initializing, pending, active, movedno
Query metrics (managed billing)yes: CloudWatch DNSQueries, daily sumsnot yetnot yetnot yetnot yet (DNS analytics API planned)no (server-wide statistics only)

The intersection rule means a zone attached to Cloudflare accepts only TTLs from 60 seconds to one day, a zone attached to Azure at most 20 values per record set, and so on: the dashboard, the API and MCP refuse a record set that one of the zone's providers cannot serve.

Known quirks

  • Cloudflare: Multi-provider DNS. Cloudflare only honours NS records at the zone apex when the zone's Multi-provider DNS setting is on. The adapter turns it on when it creates a zone, when a zone is adopted and before it writes the apex NS set; the API token therefore needs to edit the zone's DNS settings. Records are always written with the proxy off. See Cloudflare.
  • Cloudflare: CAA and apex CNAME. Where a zone holds a CAA record, Cloudflare also serves CAA records for its Universal SSL certificate authorities (not listed by its API), so its answer differs from the other providers' and the probes report a mismatch; an apex CNAME is served flattened (the target's records), never as a CNAME. See Cloudflare.
  • Cloudflare Registrar. A domain registered at Cloudflare Registrar can only use Cloudflare's nameservers, so its delegation can never list other providers. The delegation check detects it (RDAP) and the dashboard explains the options: transfer the registration, use subdomain redundancy, or keep Cloudflare as one provider with a single-provider apex. See Cloudflare Registrar.
  • Cloudflare: subdomain zones are Enterprise only. Cloudflare adds api.example.com as a zone of its own only on its Enterprise plan, so on other plans a subdomain zone is served by the other providers (Cloudflare can still be the parent). See Cloudflare.
  • Azure keeps its own NS. Azure refuses to remove its four nameservers from the apex NS set; the NS plan always contains them, so nothing is lost. See Azure DNS.
  • Google Cloud: project-wide roles. Cloud DNS has no per-zone permissions: "Manage an existing zone" can edit every zone of the project. Keep a zone that must be isolated in a dedicated project. See Google Cloud DNS.
  • Route 53 deletes need the exact set. Deleting a record set requires its current TTL and values; the adapter reads them first, so retries stay idempotent. See Route 53.
  • OCI writes in batches. New and deleted record sets go in PatchZoneRecords calls (up to 500 operations each); an updated set and the apex NS set are replaced with one UpdateRRSet each. OCI's own four apex nameservers are protected records (they cannot be removed; the NS plan always contains them). Zone creation and deletion are asynchronous: the first sync of a new zone waits until it is active, and a deleted zone stays in Deleting for about two minutes (an attach meanwhile answers 409 providerZoneDeleting). See OCI DNS.
  • Self-hosted: the nameservers come from the connection. PowerDNS has no notion of "its own" nameservers, so the connection declares the NS names the server answers as, and those join the NS plan. The API must be reachable over https at a public address (the data plane refuses private addresses unless the operator lists them in RDNS_SELFHOST_PRIVATE_ALLOWLIST). See Self-hosted (PowerDNS).

Subdomain redundancy

A zone created as a subdomain of another zone of the same organization (api.example.com under example.com) can have its NS delegation written into the parent zone by the platform, kept equal to the child's nameserver plan and removed when the child is deleted. The parent may be served by any provider, including Cloudflare with "Manage an existing zone" access: the delegation is an ordinary NS record set in the canonical parent zone, marked as managed so nobody edits it by hand.

Managed mode per provider

On paid plans a connection can use an account that RedundantDNS operates ("managed") instead of yours. The connection carries no credentials: the data plane resolves the platform account from its own configuration. The access level is always "Create and manage zones", there is at most one managed connection per provider per organization, and the organization accepts the Managed Provider Terms once (the RedundantDNS nameservers, rdns-ns, have their own RedundantDNS Nameservers Terms instead). The provider's cost is passed through at list price plus our margin, line by line on the Billing page.

ProviderManaged accountPass-through basis
Route 53an AWS account of ourshosted zones per month plus queries (CloudWatch DNSQueries)
OCI DNSan OCI tenancy of oursqueries (no zone fee); query metrics not read yet
Google Cloud DNSa Google Cloud project of oursmanaged zones per month plus queries; query metrics not read yet
Azure DNS (coming soon)an Azure subscription of ourszones per month plus queries; query metrics not read yet
Cloudflarea Cloudflare account of oursno DNS charge on Cloudflare's plans today
RedundantDNS nameservers (rdns-ns)nameserver nodes we run in several regions (PowerDNS); one attachment fans out to every nodenone: included in every plan, the trial too (managed only, no BYO mode)

Self-hosted (PowerDNS) connections are always your own server. The RedundantDNS nameservers run the same software on our nodes: attaching them creates the zone on every node, writes every record to each, and adds every node's name to the NS plan; a node that fails leaves the attachment partial (the node named) while the others answer. See RedundantDNS nameservers.

Which providers are offered in managed mode depends on the accounts the platform has configured; the connection form only shows the managed option where one exists.

Permission guides