DNS as Code

Mit Ihrer Zone beginnen

$ 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.

Die Datei

# 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 ist @ für die Zone selbst oder ein Name relativ zu ihr (www, _dmarc); ein vollqualifizierter Name mit abschließendem Punkt funktioniert ebenfalls.
• type ist A, AAAA, CNAME, MX, TXT, SRV, PTR oder REDIRECT (eine HTTP-Weiterleitung auf die URL in value).
• ttl ist 5m, 15m, 30m, 1h oder 1d; ohne Angabe erhält ein Eintrag den ttl der Datei oder 1h. MX akzeptiert priority (Standard 10), SRV priority, weight und port, REDIRECT save_path (Standard true).
• Dasselbe Dokument funktioniert auch als JSON. Das JSON Schema bietet Ihnen Autovervollständigung und Prüfungen in VS Code und anderen Editoren.

Wie ein Plan entsteht

Die Datei ist die gesamte Zone: Ein Eintrag, der in der Zone, aber nicht in der Datei steht, wird gelöscht. Übergeben Sie --keep-unlisted (prune=false in der API), um nur hinzuzufügen und zu ändern.

A-, AAAA-, MX- und TXT-Einträge werden anhand von Name und Wert (bei MX zusätzlich anhand der Priorität) abgeglichen, da ein Name mehrere davon haben kann. CNAME-, SRV-, PTR- und REDIRECT-Einträge werden anhand des Namens abgeglichen. Eine abweichende TTL bzw. bei SRV eine abweichende Priorität, Gewichtung oder ein abweichender Port gilt als Änderung; alles andere gilt als Hinzufügen oder Löschen.

Apply läuft in einer einzigen Transaktion: zuerst Löschungen, dann Änderungen, dann neue Einträge – so kann ein CNAME in derselben Datei einen A-Eintrag ersetzen. Wird ein Eintrag abgelehnt, wird nichts geändert. Ändert jemand die Zone zwischen Plan und Apply, wird das Apply abgelehnt und Sie erstellen den Plan erneut.

Einträge, die NameOcean für sich selbst verwaltet – die Adresse hinter einer HTTP-Weiterleitung und die ACME-Challenges für SSL –, werden nie exportiert, geplant oder gelöscht.

GitHub Actions

Erstellen Sie einen API-Schlüssel mit dns:write (oder nur dns:read für einen Job, der nur plant) und speichern Sie ihn als 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 endet mit Exitcode 2, wenn es Änderungen gibt – für Jobs, die nur Abweichungen melden sollen.

Mit der 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

Senden Sie YAML mit Content-Type: application/yaml oder dasselbe Dokument als JSON. Eine Datei, die der Server nicht akzeptieren kann, wird mit 400 invalid_zone_file beantwortet, inklusive einer errors-Liste, die jeden betroffenen Record und jedes Feld benennt. Alle Details finden Sie in der API-Referenz.

Über Ihre KI

Über MCP kann ein Assistent eine Zone exportieren, mit plan_dns_zone eine Änderung an vielen Einträgen gleichzeitig planen und sie, nachdem er Ihnen den Plan gezeigt hat, mit apply_dns_zone anwenden.