# 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).

| Method | What 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. |
| `ValidateCredentials` | Checks 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` / `FindZone` | Zone lifecycle; `FindZone` finds a zone by id or by name for adoption. |
| `ListRecordSets` | What the provider serves, as canonical record sets (SOA excluded, apex NS included). |
| `ApplyChanges` | Applies a diff (create, update, delete per name and type). Idempotent: a retry after a partial failure converges. |
| `QueryMetrics` | Query 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`):

| Adapter | Refusal (`BatchRejected`) | Not a refusal (retried) |
|---|---|---|
| `route53` | `InvalidChangeBatch`, `InvalidInput` | `Throttling`, `PriorRequestNotComplete`, `AccessDenied`, `NoSuchHostedZone`, 5xx, network |
| `oci` | HTTP 400 (`InvalidParameter` and the like) on a record write | 401/403/404, 429 and 5xx (retried in the adapter first), network |
| `gcp` | HTTP 400 on a Change (`invalid`, `invalidRecordData`, ...) | 401/403, 404, 412 (stale deletion), 429, 5xx, network |
| `azure` | HTTP 400 on a record set write | 401/403, 404, 409, 429, 5xx, network |
| `cloudflare` | HTTP 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 |
| `selfhost` | HTTP 422 (PowerDNS refuses an RRset) and 400 on the zone PATCH | 401/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).

| Level | What 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 53 | OCI DNS | Google Cloud DNS | Azure DNS (coming soon) | Cloudflare | Self-hosted (PowerDNS) |
|---|---|---|---|---|---|---|
| Record types | A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR | same | same | same | same | same (PowerDNS also serves TLSA, HTTPS, SVCB: not in the canonical model yet) |
| TTL range (seconds) | 0 to 2,147,483,647 | 1 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,647 | 60 to 86,400 (30 on Enterprise; not used) | 1 to 2,147,483,647 |
| Apex NS editable | yes | yes, OCI's own four are protected and always kept | yes | yes, Azure's own four are always kept | yes, with the Multi-provider DNS setting (turned on by the adapter) | yes |
| Wildcards | yes | yes | yes | yes (not for NS and SOA) | yes | yes |
| CNAME at the apex | no | no | no | no | yes (CNAME flattening) | no |
| Max values per record set | 100 (from the code: Route 53's real cap is request-size based) | 100 (from the code) | 10,000 | 20 | no documented limit | no 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 set | 2,048 per record (8,192 per name and type) | no limit (255 per string) |
| Batching | `ChangeResourceRecordSets`: 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 set | one change per batch: up to 1,000 additions, 1,000 deletions and 100 KB of data | one call per record set, deletes first | batch endpoint: delete and repost a set's records in one request, up to 200 operations each | one `PATCH` per diff (`REPLACE`/`DELETE` per record set, one transaction) |
| Zone status reading | no | no | no | no | yes: initializing, pending, active, moved | no |
| Query metrics (managed billing) | yes: CloudWatch `DNSQueries`, daily sums | not yet | not yet | not yet | not 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](https://redundantdns.com/docs/providers/cloudflare.md).
- **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](https://redundantdns.com/docs/providers/cloudflare.md).
- **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](https://redundantdns.com/docs/providers/cloudflare.md#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](https://redundantdns.com/docs/providers/cloudflare.md).
- **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](https://redundantdns.com/docs/providers/azure.md).
- **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](https://redundantdns.com/docs/providers/gcp.md).
- **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](https://redundantdns.com/docs/providers/route53.md).
- **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](https://redundantdns.com/docs/providers/oci.md).
- **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)](https://redundantdns.com/docs/providers/selfhost.md).

## 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](/legal/managed-terms) once (the
RedundantDNS nameservers, `rdns-ns`, have their own
[RedundantDNS Nameservers Terms](/legal/nameservers-terms) instead). The
provider's cost is passed through at list price plus our margin, line by
line on the Billing page.

| Provider | Managed account | Pass-through basis |
|---|---|---|
| Route 53 | an AWS account of ours | hosted zones per month plus queries (CloudWatch `DNSQueries`) |
| OCI DNS | an OCI tenancy of ours | queries (no zone fee); query metrics not read yet |
| Google Cloud DNS | a Google Cloud project of ours | managed zones per month plus queries; query metrics not read yet |
| Azure DNS (coming soon) | an Azure subscription of ours | zones per month plus queries; query metrics not read yet |
| Cloudflare | a Cloudflare account of ours | no 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 node | none: 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](https://redundantdns.com/docs/providers/rdns-ns.md).

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

- [AWS Route 53](https://redundantdns.com/docs/providers/route53.md)
- [OCI DNS](https://redundantdns.com/docs/providers/oci.md)
- [Google Cloud DNS](https://redundantdns.com/docs/providers/gcp.md)
- [Azure DNS](https://redundantdns.com/docs/providers/azure.md) (coming soon: not available for new connections yet)
- [Cloudflare](https://redundantdns.com/docs/providers/cloudflare.md)
- [Self-hosted (PowerDNS)](https://redundantdns.com/docs/providers/selfhost.md)
- [RedundantDNS nameservers](https://redundantdns.com/docs/providers/rdns-ns.md) (managed, no permissions to grant)
