DNS as code

Parta dalla Sua zona

$ nameocean dns export example.com > dns.yaml
$ $EDITOR dns.yaml
$ nameocean dns plan -f dns.yaml
+  CNAME  blog  example.netlify.app
~  A      @     203.0.113.10  ttl 1h → 5m
-  A      old   203.0.113.9
example.com: 1 to add, 1 to change, 1 to delete, 6 unchanged.
$ nameocean dns apply -f dns.yaml
Apply these changes? [y/N] y
Applied: 1 added, 1 changed, 1 deleted. example.com is at serial 214.

Il file

# yaml-language-server: $schema=https://nameocean.net/schemas/dns-zone.json
zone: example.com
records:
  - name: "@"
    type: A
    value: 203.0.113.10
    ttl: 5m
  - name: www
    type: CNAME
    value: "@"
  - name: "@"
    type: MX
    value: mail.example.com
    priority: 10
  - name: "@"
    type: TXT
    value: "v=spf1 mx -all"
  - name: _sip._tcp
    type: SRV
    value: sip.example.com
    priority: 10
    weight: 5
    port: 5060
  - name: old
    type: REDIRECT
    value: https://example.com/new

• name è @ per la zona stessa oppure un nome relativo a essa (www, _dmarc); funziona anche un nome completo con il punto finale.
• type è A, AAAA, CNAME, MX, TXT, SRV, PTR o REDIRECT (un redirect HTTP all'URL indicato in value).
• ttl è 5m, 15m, 30m, 1h o 1d; se assente, il record riceve il ttl del file, oppure 1h. MX accetta priority (predefinito 10), SRV priority, weight e port, REDIRECT save_path (predefinito true).
• Lo stesso documento funziona anche in JSON. Lo JSON Schema offre completamento automatico e controlli in VS Code e in altri editor.

Come viene creato un plan

Il file rappresenta l'intera zona: un record presente nella zona ma non nel file viene eliminato. Usi --keep-unlisted (prune=false nell'API) per limitarsi ad aggiungere e modificare.

I record A, AAAA, MX e TXT vengono confrontati in base a nome e valore (e priorità per i record MX), poiché uno stesso nome può averne diversi. I record CNAME, SRV, PTR e REDIRECT vengono confrontati in base al nome. Un ttl diverso, oppure una priorità, un peso o una porta SRV diversi, costituiscono una modifica; tutto il resto è un'aggiunta o un'eliminazione.

Apply viene eseguito in un'unica transazione: prima le eliminazioni, poi le modifiche, poi i nuovi record, così un CNAME può sostituire un record A nello stesso file. Se un record viene rifiutato, non viene modificato nulla. Se qualcuno modifica la zona tra il plan e l'apply, l'apply viene rifiutato e occorre rieseguire il plan.

I record che NameOcean riserva per sé, ovvero l'indirizzo dietro un redirect HTTP e le challenge ACME per SSL, non vengono mai esportati, pianificati né eliminati.

GitHub Actions

Crei una chiave API con dns:write (o solo dns:read per un job che esegue il plan) e la salvi come secret NAMEOCEAN_API_KEY.

name: dns
on:
  pull_request: {paths: [dns.yaml]}
  push: {branches: [main], paths: [dns.yaml]}
jobs:
  dns:
    runs-on: ubuntu-latest
    env:
      NAMEOCEAN_API_KEY: ${{ secrets.NAMEOCEAN_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://nameocean.net/install.sh | sh
      - run: nameocean dns plan -f dns.yaml
      - if: github.event_name == 'push'
        run: nameocean dns apply -f dns.yaml --yes

dns plan --detailed-exitcode termina con codice 2 quando ci sono modifiche, per i job che devono solo segnalare le divergenze.

Con la REST API

$ curl -X POST https://nameocean.net/api/v1/dns/example.com/plan \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
    -H "Content-Type: application/yaml" --data-binary @dns.yaml

Invii il file in YAML con Content-Type: application/yaml oppure lo stesso documento in JSON. Se il server non può accettare il file, risponde 400 invalid_zone_file con un elenco errors che indica ogni record e campo. Trova tutti i dettagli nel riferimento API.

Dalla Sua AI

Tramite MCP un assistente può esportare una zona, pianificare una modifica a più record contemporaneamente con plan_dns_zone e, dopo averLe mostrato il piano, applicarla con apply_dns_zone.