# Connect Google Cloud DNS

RedundantDNS talks to Google Cloud DNS with the **JSON key of a service
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 public zones in one project, 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 zones that already exist in the project. It never creates or deletes zones. |
| **Mirror source (read-only)** | Only read the records of a zone you keep editing yourself. RedundantDNS mirrors it to your other providers and never writes to it, not even its apex NS set. |

> Cloud DNS has **no per-zone permissions**: IAM roles apply to the whole
> project. "Manage an existing zone" therefore can edit the records of
> **every** zone in the project, not only the one you attach. If you need
> one zone isolated, keep it in a **dedicated project** used only by
> RedundantDNS.

## 1. Create a service account and a key

1. In the Google Cloud console pick the project that holds (or will hold)
   your zones. Note its **project ID** (for example `acme-dns`).
2. Make sure the **Cloud DNS API** is enabled: **APIs & Services → Enable
   APIs and services → Cloud DNS API → Enable**.
3. **IAM & Admin → Service accounts → Create service account**, for example
   `redundantdns`. Skip the optional role step for now.
4. Open the service account, **Keys → Add key → Create new key → JSON**.
   The browser downloads the key file. Keep it until you paste it into
   RedundantDNS, then delete it from your computer.

Paste the key file exactly as Google issued it. RedundantDNS accepts only
Google's token endpoint (`token_uri` `https://oauth2.googleapis.com/token`,
or none) and the Google Cloud universe (`universe_domain` `googleapis.com`,
or none); a key that names anything else is refused when the connection is
saved or tested.

With the gcloud CLI instead:

```
gcloud iam service-accounts create redundantdns --project acme-dns
gcloud iam service-accounts keys create redundantdns-key.json \
  --iam-account redundantdns@acme-dns.iam.gserviceaccount.com
```

## 2a. Create and manage zones

Grant the predefined **DNS Administrator** role (`roles/dns.admin`) on the
project: **IAM & Admin → IAM → Grant access**, principal
`redundantdns@<project-id>.iam.gserviceaccount.com`, role *DNS
Administrator*. Or, replacing `<project-id>`:


```
gcloud projects add-iam-policy-binding <project-id> \
  --member serviceAccount:redundantdns@<project-id>.iam.gserviceaccount.com \
  --role roles/dns.admin
```

It covers `dns.managedZones.*`, `dns.changes.*` and
`dns.resourceRecordSets.*`.

In RedundantDNS, **Providers → Add connection**: provider *Google Cloud
DNS*, access level *Create and manage zones*, paste the **whole JSON key**
and the **project ID**, then click **Test and save**. We check the key by
listing the project's managed zones.

## 2b. Manage an existing zone

Create a custom role with only what record editing needs, replacing
`<project-id>`:


```
gcloud iam roles create redundantdnsZoneEditor --project <project-id> \
  --title "RedundantDNS zone editor" \
  --permissions dns.managedZones.get,dns.managedZones.list,dns.changes.create,dns.changes.get,dns.changes.list,dns.resourceRecordSets.create,dns.resourceRecordSets.delete,dns.resourceRecordSets.get,dns.resourceRecordSets.list,dns.resourceRecordSets.update

gcloud projects add-iam-policy-binding <project-id> \
  --member serviceAccount:redundantdns@<project-id>.iam.gserviceaccount.com \
  --role projects/<project-id>/roles/redundantdnsZoneEditor
```

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 name** shown in **Network services → Cloud DNS** (the managed zone
name, for example `example-com`, not the domain). 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 Cloud DNS 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. Grant the predefined
**DNS Reader** role (`roles/dns.reader`), replacing `<project-id>`:


```
gcloud projects add-iam-policy-binding <project-id> \
  --member serviceAccount:redundantdns@<project-id>.iam.gserviceaccount.com \
  --role roles/dns.reader
```

DNS Reader lets the key get a managed zone and list its record sets,
nothing else (like every Cloud DNS role, it applies to the whole project).
In RedundantDNS, **Zones → New zone → Mirror an existing zone**: pick
*Google Cloud DNS*, paste the JSON key, the project ID and the managed zone
name. 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, through Cloud DNS changes
  (each change replaces whole record sets atomically; large updates are
  split in changes of at most 1,000 additions and 1,000 deletions).
- 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. Record sets with a routing policy (geo,
  weighted) are left alone.

## Record sets Cloud DNS refuses

Measured on a real project (2026-09-28). Cloud DNS refuses a **wildcard NS
set** (`*.sub NS`: `wildcardNotAllowed`) and a TXT character-string longer
than 255 bytes (RedundantDNS splits long TXT values into 255-byte strings
before writing, so this only matters for values you write yourself). A set
Cloud DNS refuses never stops the zone: it is listed as skipped with Cloud
DNS's message, the rest syncs and the `sync_partial` alert fires (see
`docs/api.md`, "Record sets a provider refuses"). Cloud DNS accepts an A
set next to an NS set on the same name, `MX 0 .`, `SRV 0 0 0 .` and any
CAA flag or tag.

Changes are applied within 1 to 3 seconds: an edit in the dashboard is
served by the four Google nameservers about 3 to 7 seconds after you save
it. The SOA serial of a Cloud DNS zone stays at 1; RedundantDNS never
writes the SOA.

## Revoking access

Delete the service account key (or the service account, or the role
binding) at any time. Then remove the connection in **Providers**; zones
keep being served by Cloud DNS exactly as they are.
