# Connect AWS Route 53

RedundantDNS talks to Route 53 with an **IAM access key** that you create in
your AWS account. The 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 hosted zones, 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 hosted zone that you created. It never creates or deletes zones. |
| **Mirror source (read-only)** | Only read the records of one hosted 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. |

## Create and manage zones

1. In the AWS console, open **IAM → Users → Create user**. Name it, for
   example, `redundantdns`. It does not need console access.
2. Attach this inline policy (**Add permissions → Create inline policy →
   JSON**):


```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedundantDnsManageZones",
      "Effect": "Allow",
      "Action": [
        "route53:CreateHostedZone",
        "route53:DeleteHostedZone",
        "route53:ListHostedZones",
        "route53:ListHostedZonesByName",
        "route53:GetHostedZone",
        "route53:GetChange",
        "route53:ListResourceRecordSets",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "RedundantDnsQueryMetricsOptional",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics"
      ],
      "Resource": "*"
    }
  ]
}
```

   The second statement is **optional**: it only lets RedundantDNS read the
   query counts Route 53 publishes to CloudWatch (used for managed-mode
   billing and usage charts). Remove it if you do not need them.

3. Open the user, go to **Security credentials → Create access key**, choose
   **Application running outside AWS**, and copy the **Access key ID** and
   **Secret access key**.
4. In RedundantDNS, **Providers → Add connection**: provider *AWS Route 53*,
   access level *Create and manage zones*, paste both keys and click **Test
   and save**. We check the key by listing your hosted zones.

## Manage an existing zone

Use this when you already created the hosted zone yourself and want to grant
access to that zone only.

1. Copy the **hosted zone ID** from **Route 53 → Hosted zones** (it looks
   like `Z0123456789ABCDEFGHIJ`).
2. Create an IAM user as above and attach this inline policy, replacing
   `<hosted zone id>`:


```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedundantDnsEditOneZone",
      "Effect": "Allow",
      "Action": [
        "route53:GetHostedZone",
        "route53:ListResourceRecordSets",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/<hosted zone id>"
    },
    {
      "Sid": "RedundantDnsChangeStatus",
      "Effect": "Allow",
      "Action": "route53:GetChange",
      "Resource": "arn:aws:route53:::change/*"
    }
  ]
}
```

   `route53:ListHostedZones` is **not** required: RedundantDNS never lists
   your account. (`GetChange` is scoped to change ARNs because that is the
   resource type IAM uses for it; it only reveals the status of a change.)

3. Create the access key as above and 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 hosted zone ID. We verify that the hosted zone holds the same domain
   and that the key can read its records.

   Existing records are never deleted silently: into an empty zone in
   RedundantDNS, the hosted zone's records are imported; if the hosted zone
   holds records the zone in RedundantDNS does not have, the dashboard
   shows the difference and you choose **Import them** or **Overwrite**
   (see "Adopting an existing zone" in the providers overview). Otherwise
   the hosted zone is **verified** first: if its records differ, the
   attachment shows `drift` with the difference; choose **Adopt changes**
   to take Route 53's records as the zone's content, or **Reconcile now**
   to write RedundantDNS's records to Route 53. (`adoptExisting` on the API
   only applies to *Create and manage zones*, where the zone may already
   exist.)

## Mirror source (read-only)

Use this when the zone stays edited in Route 53 (by you, your team or your
own tooling) and RedundantDNS only copies it to your other providers, for
example a standby on another cloud. RedundantDNS reads the hosted zone and
**never writes to it**: no record, not even the apex NS set.

1. Copy the **hosted zone ID** from **Route 53 → Hosted zones**.
2. Create an IAM user as above and attach this inline policy, replacing
   `<hosted zone id>`:


```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedundantDnsReadOneZone",
      "Effect": "Allow",
      "Action": [
        "route53:GetHostedZone",
        "route53:ListResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/<hosted zone id>"
    },
    {
      "Sid": "RedundantDnsListZones",
      "Effect": "Allow",
      "Action": "route53:ListHostedZones",
      "Resource": "*"
    }
  ]
}
```

   `route53:ListHostedZones` lets you check the key with
   `aws route53 list-hosted-zones`; RedundantDNS itself only calls
   `GetHostedZone` and `ListResourceRecordSets`. The policy has no write
   action: if the key happens to have more permissions, RedundantDNS still
   never uses them.

3. Create the access key as above. In RedundantDNS, **Zones → New zone →
   Mirror an existing zone**: pick *AWS Route 53*, paste both keys and the
   hosted zone ID. RedundantDNS checks that it can read the zone, creates
   the zone as its mirror and copies every record (a large zone, thousands
   of records, is read in pages). You can also add the connection in
   **Providers** with access level *Mirror source (read-only)* and attach it
   to a zone: it becomes the zone's source of truth in the same step.

The zone's NS plan starts as the hosted zone's own apex NS set, so nothing
needs to change at your registrar. When you attach a standby and later
promote it, add its nameservers at the registrar and, if you want every
copy of the zone to list them, to the Route 53 apex NS set yourself:
RedundantDNS does not write it.

## Region

Route 53 is a global service; the region field can stay `us-east-1` (the
region where Route 53 publishes its CloudWatch metrics).

## What RedundantDNS writes

- Every record set you manage in the dashboard.
- 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.
- It never touches the SOA record, alias records or routing policies
  (weighted, latency, geolocation...), which are Route 53-only features.

The apex NS set is written on the first reconcile after the attach even
when the NS plan names only Route 53's own four nameservers: Route 53
creates it with a TTL of 172,800 seconds and RedundantDNS writes the NS
plan with its own TTL (86,400 seconds). A *Mirror source* attachment is
the exception: its apex NS set is never written.

## Record sets Route 53 refuses

Route 53 validates record content when it is written, beyond the
capabilities RedundantDNS checks first. Measured with the API
(2026-09-27):

- **Refused** (`InvalidChangeBatch`): an NS set at a wildcard name
  (`*.sub NS`: "Changing wildcard NS record sets are not supported"); a
  CAA flag other than 0 or 128 (`5 issue ...`: `CAARRDATAInvalidFlag`); a
  CAA tag other than `issue`, `issuewild` or `iodef` with a non-critical
  flag (`0 foo ...`: `CAARRDATAInvalidTag`); a TXT character-string longer
  than 255 characters (RedundantDNS already splits long TXT values into
  255-character strings, so this never happens from the platform); a CNAME
  next to other types at the same name (the platform refuses it first,
  `409 cnameConflict`).
- **Accepted**: an NS set next to an A set at the same name (OCI refuses
  that one), `MX 0 .`, `SRV 0 0 0 .`, PTR sets in a forward zone.

A write that Route 53 refuses is atomic: nothing of that request is
applied. The adapter reports `InvalidChangeBatch` and `InvalidInput` as a
refusal of content, so the data plane isolates the refused sets: the rest
is written, the refused sets are listed in the attachment's `skipped` with
`reason: provider-rejected` and Route 53's message, the attachment stays
`in_sync` and `sync_partial` fires (never `sync_error`), also when the
reconcile holds only refused sets (a single refused edit, or deleting
refused sets one by one). Fix or remove the refused set to clear it.
Throttling (`Throttling`, `PriorRequestNotComplete`), `AccessDenied`,
`NoSuchHostedZone` and server or network errors are failures, retried as
usual.

A diff above 1,000 changes is sent as several requests. When a later
request is refused, the isolation sends again parts whose deletes already
went through; Route 53 refuses a delete of a set that does not exist
("Tried to delete resource record set ... but it was not found"), so the
adapter drops such a delete (the set is already gone) and sends the rest
of the request again. Only the sets Route 53 really refuses end up
skipped.

## Revoking access

Delete the access key (or the IAM user) in IAM at any time. Then remove the
connection in **Providers**; zones keep being served by Route 53 exactly as
they are.
