DNS als code

Begin met uw zone

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

Het bestand

# 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 is @ voor de zone zelf of een naam relatief daaraan (www, _dmarc); een volledig gekwalificeerde naam met de afsluitende punt werkt ook.
• type is A, AAAA, CNAME, MX, TXT, SRV, PTR of REDIRECT (een HTTP-doorverwijzing naar de URL in value).
• ttl is 5m, 15m, 30m, 1h of 1d; zonder deze waarde krijgt een record de ttl van het bestand, of 1h. MX gebruikt priority (standaard 10), SRV priority, weight en port, REDIRECT save_path (standaard true).
• Hetzelfde document werkt ook als JSON. Het JSON Schema geeft u automatische aanvulling en controles in VS Code en andere editors.

Hoe een plan wordt gemaakt

Het bestand is de hele zone: een record dat wel in de zone staat maar niet in het bestand, wordt verwijderd. Gebruik --keep-unlisted (prune=false in de API) om alleen toe te voegen en te wijzigen.

A-, AAAA-, MX- en TXT-records worden gematcht op naam en waarde (en prioriteit bij MX), omdat één naam er meerdere kan hebben. CNAME-, SRV-, PTR- en REDIRECT-records worden gematcht op naam. Een andere ttl, of een andere SRV-prioriteit, -weight of -poort, geldt als wijziging; al het andere is een toevoeging of een verwijdering.

Apply wordt in één transactie uitgevoerd: eerst verwijderingen, dan wijzigingen, dan nieuwe records, zodat een CNAME een A-record in hetzelfde bestand kan vervangen. Als één record wordt geweigerd, wordt er niets gewijzigd. Als iemand de zone wijzigt tussen het plan en de apply, wordt de apply geweigerd en maakt u opnieuw een plan.

Records die NameOcean voor zichzelf beheert, zoals het adres achter een HTTP-doorverwijzing en de ACME-challenges voor SSL, worden nooit geëxporteerd, gepland of verwijderd.

GitHub Actions

Maak een API-sleutel aan met dns:write (of alleen dns:read voor een job die alleen plant) en sla deze op als het 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 eindigt met code 2 als er wijzigingen zijn, voor jobs die alleen afwijkingen moeten melden.

Met de 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

Verstuur YAML met Content-Type: application/yaml of hetzelfde document als JSON. Een bestand dat de server niet kan accepteren, geeft 400 invalid_zone_file terug met een errors-lijst die elk record en veld benoemt. Alles staat in de API-referentie.

Vanuit uw AI

Via MCP kan een assistent een zone exporteren, met plan_dns_zone een wijziging voor veel records tegelijk plannen en, nadat het plan aan u is getoond, deze toepassen met apply_dns_zone.