# Connect OCI DNS

RedundantDNS talks to Oracle Cloud Infrastructure DNS with an **API signing
key** of an OCI user. The private key is encrypted with your organization's
key as soon as it reaches us, is never shown again, and is only used to read
and write the DNS zones you attach.

Pick the access level that matches how much you want to delegate:

| Access level | What RedundantDNS can do |
|---|---|
| **Create and manage zones** | Create zones in one compartment, write their records and apex NS, and delete a zone when you detach it (only after you type the zone name). |
| **Manage an existing zone** | Read and edit the records of one zone that you created. It never creates or deletes zones. |
| **Mirror source (read-only)** | Only read the records of one zone that you created and keep editing yourself. RedundantDNS mirrors it to your other providers and never writes to it, not even its apex NS set. |

## 1. Create a user, a group and an API key

1. **Identity & Security → Domains → (your domain) → Groups → Create
   group**, for example `redundantdns`.
2. **Users → Create user** (for example `redundantdns`) and add it to the
   group. It does not need a console password.
3. Open the user, **API keys → Add API key → Generate API key pair**,
   download the **private key** (`.pem`) and click **Add**. The console then
   shows a configuration preview with the values you need:
   - `user`: the **user OCID** (`ocid1.user.oc1..…`)
   - `fingerprint`: the key **fingerprint** (`12:34:…`)
   - `tenancy`: the **tenancy OCID** (`ocid1.tenancy.oc1..…`)
   - `region`: the **region identifier** (for example `sa-saopaulo-1`;
     a three-letter region key such as `gru` works too). Anything else, a
     host name or a value with dots, is refused when the connection is
     saved or tested.
4. The **compartment OCID** is under **Identity & Security →
   Compartments** (click the compartment, then **Copy** next to OCID). Use
   the compartment where your DNS zones live; the root compartment's OCID is
   the tenancy OCID.

## 2a. Create and manage zones

Create a policy in the compartment (**Identity & Security → Policies →
Create policy**, in that compartment or a parent), replacing the
compartment OCID:


```
Allow group redundantdns to manage dns in compartment id <compartment OCID>
```

In RedundantDNS, **Providers → Add connection**: provider *OCI DNS*, access
level *Create and manage zones*, fill in tenancy OCID, user OCID,
fingerprint, the private key (paste the whole PEM, including the `BEGIN` and
`END` lines), region and compartment OCID, then click **Test and save**. We
check the key by listing the zones in the compartment.

## 2b. Manage an existing zone

Use this when you already created the zone (a public, primary zone) and want
to grant access to that zone only. Copy its **zone OCID** from **Networking →
DNS management → Zones**, then create this policy, replacing the OCIDs:


```
Allow group redundantdns to use dns in compartment id <compartment OCID> where target.dns-zone.id = '<zone OCID>'
```

`use dns` lets the group read the zone and update its records; it cannot
create or delete zones. Add the connection with access level *Manage an
existing zone*. The key is checked when you attach it to a zone: open the
zone, **Providers → Attach**, pick the connection and paste the zone OCID
(the zone name, such as `example.com`, works too; the attachment keeps the
OCID). We verify that the zone holds the same domain and that the key can
read its records.

## 2c. Mirror source (read-only)

Use this when the zone stays edited in OCI and RedundantDNS only copies it
to your other providers. RedundantDNS reads the zone and **never writes to
it**: no record, not even the apex NS set. Copy the **zone OCID**, then
create this policy:


```
Allow group redundantdns to read dns in compartment id <compartment OCID> where target.dns-zone.id = '<zone OCID>'
```

`read dns` lets the group get the zone (`GetZone`) and its records
(`GetZoneRecords`), nothing else. In RedundantDNS, **Zones → New zone →
Mirror an existing zone**: pick *OCI DNS*, fill in the key fields and the
zone OCID. RedundantDNS checks that it can read the zone, creates the zone
as its mirror and copies every record. The NS plan starts as the zone's own
apex NS set, so nothing needs to change at your registrar.

## What RedundantDNS writes

- Every record set you manage in the dashboard (one update per record set,
  idempotent).
- The **apex NS** record set: RedundantDNS rewrites it to list the
  nameservers of **every** attached provider, so each copy of the zone
  delegates to all of them. It is shown read-only in the dashboard. OCI
  marks the zone's own four nameservers (`nsN.pNNN.dns.oraclecloud.net`) as
  protected: they cannot be removed, and since they are always in the NS
  plan while OCI is an active provider, nothing is lost; the other
  providers' nameservers are added next to them.
- It never touches the SOA record. OCI keeps its own SOA serial, so the
  serial the nameservers answer differs from the one in the dashboard.
- Zones it creates carry the freeform tag `managedBy: redundantdns`. In a
  RedundantDNS managed account they also carry `redundantdnsOwner` (your
  organization's id): a zone of another organization in that shared
  account is never adopted, and detaching a managed connection deletes its
  zone unless you choose to keep it.

## Timing

- **A new zone** is created by OCI asynchronously. Record writes wait until
  it is active, so the first sync of a zone RedundantDNS creates can take a
  minute or more, and a probe
  that runs before OCI serves the zone reports it `degraded` until the
  next probe.
- **Deleting a zone** (detach with "delete the zone at the provider") is
  asynchronous too: OCI keeps it in the `Deleting` state for about two
  minutes. An attach of the same zone name (or OCID) meanwhile is refused
  with `409 providerZoneDeleting` ("the provider is still deleting
  <zone>; retry in a few minutes"): a zone being deleted is never adopted.
  Detaching with "delete the zone at the provider" a zone that is already
  gone succeeds.
- **A zone OCI is still creating** (read or written by a sync) is waited
  for, up to 40 seconds, until it is active. Past that, the attachment
  stays `pending` with `pendingReason: provider-creating` ("the provider
  is still creating this zone") and the sync is retried on its own after
  30 seconds, then 1, 2, 4 and 5 minutes, without an alert and without
  using the job's retries (zone creation has been seen to take from 80
  seconds to 12 minutes). Only a zone still being created 30 minutes
  after the attach turns into `error` and fires `sync_error`. An attach
  that adopts a zone OCI is still creating waits the same 40 seconds and
  is refused past them (`422 providerRejected`); retry it a minute later.
  A zone in the `Failed` state is reported, never adopted: delete it at
  OCI and attach again.
- **A large first sync** is batched: new record sets are written with
  `PatchZoneRecords`, up to 500 record operations (and 256 KiB of record
  data) per call, deleted sets are removed the same way, and each updated
  set is one `UpdateRRSet` (atomic per set; the apex NS set always goes
  through it). A 2,500-record-set zone is 5 to 10 calls (5 in the adapter
  test with one value per set), so its first sync takes seconds to about a
  minute instead of the 37 minutes measured when every set was one call
  (about one set per second, with `TooManyRequests`). A throttled call
  (`429 TooManyRequests`) or a transient 5xx is retried up to 8 times,
  waiting OCI's `Retry-After` when it sends one, otherwise a jittered
  exponential backoff from 1 to 32 seconds (about two minutes at most),
  before the job fails and follows its own retry schedule. Updating many
  existing sets at once (a TTL change on the whole zone) is still one call
  per set. Long reconciles keep the organization's lease and heartbeat
  (a second data plane never runs the same job), and up to
  `RDNS_JOBS_PER_ORG` jobs of other zones run meanwhile.
- **TTLs**: OCI accepts 1 to 604,800 seconds (7 days). Attaching OCI to a
  zone whose source is the platform while it holds a record set outside
  that range is refused with `422 recordSetUnsupported` (the details list
  each record set; edit it first). In a mirrored zone (a Route 53 source
  allows 0 to 2^31-1) the attach succeeds: those sets, present or arriving
  later, are skipped at the OCI attachment only and listed in
  `status.attachments[id].skipped` (`ttl-above-max`); the other providers
  keep serving them, and an OCI standby reports `failover: partial`.
- **Delegations need glue inside the delegated name**: OCI refuses an NS
  set below the apex whose nameserver sits inside the delegated name
  (`sub.example.com NS ns.sub.example.com`) when the zone has no A or AAAA
  record for that nameserver (`InvalidParameter: NS record at ... has no
  corresponding A or AAAA records in zone`); a nameserver elsewhere in the
  zone or outside it is accepted without glue. Route 53 and PowerDNS accept
  such a delegation. RedundantDNS checks it before writing: in a mirrored
  zone the set is skipped at the OCI attachment only (`glue-required` in
  `status.attachments[id].skipped`, with the nameservers missing glue),
  the rest of the zone syncs, and the `sync_partial` alert (a warning)
  says so until the source adds the glue record or points the delegation
  at another name; on a zone whose source is the platform the attach is
  refused with `422 recordSetUnsupported` (add the glue first). Glue
  records are always written before the delegations in a sync.
- **A record set OCI refuses anyway**: `PatchZoneRecords` is
  all-or-nothing per call, so one refused set (`400`, such as
  `InvalidParameter`) would stop the rest of its call. The data plane
  splits a refused call in halves until it finds the set OCI refuses (a
  few more calls: about 20 for one set among 600), writes everything
  else, and skips that set at the OCI attachment (`provider-rejected`,
  with OCI's message). The attachment is `in_sync`, the `sync_partial`
  alert fires (never `sync_error`) and a standby reports `failover:
  partial`. A verify does not count the refused set as drift; every
  reconcile tries it again, and once OCI accepts it the skip and the alert
  clear. Refusals seen on the real API: an NS set at a name that also
  holds other types except DS (`Cannot add NS records to a non-apex domain
  with record types other than DS`; Route 53 and PowerDNS accept an NS set
  next to an A set at the same name), a DS set with no NS set at its name,
  a CNAME next to other types and the `HTTPS` type. OCI accepts CAA with
  any tag or flags, SRV and MX targets `.` and long TXT values. Writing
  again what already landed is harmless: an `ADD` of a value the set
  already holds adds no duplicate and a `REMOVE` of an absent set
  succeeds, so an isolation that re-sends sets an earlier call of the same
  sync wrote leaves the zone exact.

## Revoking access

Delete the API key (or the user, or the policy) in OCI at any time. Then
remove the connection in **Providers**; zones keep being served by OCI
exactly as they are.
