digitalocean-dns-zones

What this skill does

# DigitalOcean DNS Zones

Operational skill for managing DigitalOcean DNS through doctl, the REST API, and the Terraform provider. Covers the traps that appear most often when migrating zones in or out of Cloudflare — especially apex CNAME handling, trailing-dot semantics, and the account-wide token model that differs from Cloudflare's scoped tokens.

## When to invoke

**Symptoms:**

- Apex hostname (`example.com`) refuses to take a CNAME — the provider errors or the record silently misbehaves.
- A Terraform CNAME resolves to a doubled FQDN like `api.example.com.example.com`.
- Need a wildcard cert (`*.example.com`) with a DNS-01 ACME challenge on a DO-hosted zone.
- Migrating a zone to or from Cloudflare and unsure which records need manual attention.
- Deciding whether to use doctl, the raw API, or the Terraform provider for a given task.
- Token handling for DO DNS in CI — needs guidance on secret management.

## Cross-cutting rules

These rules apply to every section below. Read them before acting.

1. **`DIGITALOCEAN_ACCESS_TOKEN` is account-wide.** Unlike Cloudflare, DigitalOcean has no zone-scoped token model. A token that can edit DNS can touch every domain in the account. Treat it as a high-value secret: store it in a secrets manager or CI secret, never echo it into shared shell history or CI logs. This is an explicit difference from the `cloudflare-dns-zones` skill's "scope tokens to the minimum" rule — on DigitalOcean you cannot scope below the account level.

2. **Domain before records.** A domain entry (`digitalocean_domain` resource or `doctl compute domain create`) must exist before any record can be added. There is no "lazy create." The apex record uses `name = "@"` in both doctl and Terraform.

3. **No apex CNAME, no flattening.** DigitalOcean has no ALIAS, ANAME, or CNAME flattening. A bare apex (`example.com`) must resolve to A or AAAA records. This is the most common trap when migrating from Cloudflare, which transparently flattens apex CNAMEs — that transparency disappears the moment you cut over nameservers to DO.

4. **CNAME and MX values are FQDNs ending in a trailing dot.** Set `value = "mail.example.com."` — with the trailing dot. A value without the trailing dot is treated as relative to the zone and the domain is appended automatically, producing a doubled FQDN such as `mail.example.com.example.com`. This is the second most common migration trap.

5. **List-then-act for idempotency.** There is no upsert-by-name endpoint. Look up a record by name and type, then create it (no ID) or update it by its record ID. Script idempotent tools this way.

6. **`ttl` accepts any non-negative integer; the default is 1800.** Do not assert a 30-second minimum — that was control-panel lore from an older version and does not reflect what the provider or API accept today.

## doctl record CRUD

doctl reads the token from `DIGITALOCEAN_ACCESS_TOKEN` or from `doctl auth init` (stored in `~/.config/doctl/config.yaml`). The raw API at `https://api.digitalocean.com/v2/domains` is the same surface if scripting without doctl.

Record names are relative to the zone — `www` for `www.example.com`. Use `@` to target the apex.

```bash
# Create the domain entry first
doctl compute domain create example.com

# List all records
doctl compute domain records list example.com

# Add an A record (apex)
doctl compute domain records create example.com \
  --record-type A --record-name @ --record-data 192.168.0.11

# Add an A record (subdomain)
doctl compute domain records create example.com \
  --record-type A --record-name www --record-data 192.168.0.11

# Update a record by ID
doctl compute domain records update example.com --record-id <id> --record-data <new-ip>

# Delete a record by ID
doctl compute domain records delete example.com <record-id>
```

To implement idempotent upsert, list and filter by name and type, then branch on whether an ID was found:

```bash
EXISTING_ID=$(doctl compute domain records list example.com \
  --format ID,Name,Type --no-header \
  | awk '$2 == "www" && $3 == "A" { print $1 }')

if [ -n "$EXISTING_ID" ]; then
  doctl compute domain records update example.com \
    --record-id "$EXISTING_ID" --record-data 192.168.0.11
else
  doctl compute domain records create example.com \
    --record-type A --record-name www --record-data 192.168.0.11
fi
```

The raw API endpoint for the same surface is `GET/POST/PUT/DELETE https://api.digitalocean.com/v2/domains/{domain_name}/records` with `Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN`. Prefer doctl for interactive use; use the raw API when scripting inside environments where doctl is unavailable.

## Terraform

The provider is `digitalocean/digitalocean`. Always create the `digitalocean_domain` resource before any `digitalocean_record` resource that references it.

```hcl
resource "digitalocean_domain" "main" {
  name = "example.com"
}

# Apex MUST be A or AAAA — never CNAME (no flattening on DO)
resource "digitalocean_record" "apex" {
  domain = digitalocean_domain.main.id
  type   = "A"
  name   = "@"
  value  = "192.168.0.11"
}

# CNAME value requires a trailing dot
resource "digitalocean_record" "api" {
  domain = digitalocean_domain.main.id
  type   = "CNAME"
  name   = "api"
  value  = "www.example.com."
}

resource "digitalocean_record" "mx" {
  domain   = digitalocean_domain.main.id
  type     = "MX"
  name     = "@"
  priority = 10
  value    = "mail.example.com."
}
```

**Bundled validator** — `scripts/do_dns_tf_lint.py` is a stdlib-only Python 3 linter. Run it against any `.tf` file that defines DigitalOcean DNS records:

```bash
python3 scripts/do_dns_tf_lint.py path/to/dns.tf
python3 scripts/do_dns_tf_lint.py path/to/dns.tf --format json
```

It enforces two rules and deliberately omits a TTL check (the provider accepts `ttl >= 0`):

- `apex-cname` **(error)** — a `digitalocean_record` with `type = "CNAME"` and `name = "@"`. This would be rejected by the API at apply time and is always wrong.
- `relative-fqdn-value` **(warning)** — a CNAME or MX `value` that contains no trailing dot. The record will double the domain at query time.

The validator is a heuristic line/brace scanner, not a full HCL parser (stdlib has none). Interpolated values such as `value = local.endpoint` and `dynamic` blocks are skipped rather than guessed — the linter silently passes on them rather than emitting a false positive.

## DNS-01 ACME / wildcard certs

A wildcard cert (`*.example.com`) requires a DNS-01 challenge. With the zone on DigitalOcean DNS, the two common approaches are:

**cert-manager (Kubernetes).** Use cert-manager's DigitalOcean DNS solver. Create a Kubernetes `Secret` holding the DO token, then reference it in the `Issuer` or `ClusterIssuer`:

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - dns01:
          digitalocean:
            tokenSecretRef:
              name: digitalocean-dns
              key: access-token
        selector:
          dnsZones:
            - example.com
```

**lego / acme.sh.** Set `DO_AUTH_TOKEN` (lego) or `DO_API_KEY` (acme.sh) in the environment. Both read the account-wide token.

Reiterate cross-cutting rule 1: the token is account-wide — store it as a Kubernetes Secret or CI secret vault entry, never inline it in manifests or scripts.

For the general mechanics of DNS-01 challenges (how the `_acme-challenge` TXT record works, propagation timing, CNAME delegation patterns), see the `cloudflare-dns-zones` skill's "DNS-01 with cert-manager" section — the protocol is identical; only the solver config changes.

## Nameserver delegation and migration

DigitalOcean's authoritative nameservers are:

```
ns1.digitalocean.com
ns2.digitalocean.com
ns3.digitalocean.com
```

These are set at the registrar — not inside the DigitalOcean co