DNS som kode

Start fra sonen din

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

Filen

# 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 er @ for selve sonen eller et navn relativt til den (www, _dmarc); et fullt kvalifisert navn med punktum til slutt fungerer også.
• type er A, AAAA, CNAME, MX, TXT, SRV, PTR eller REDIRECT (en HTTP-videresending til URL-en i value).
• ttl er 5m, 15m, 30m, 1h eller 1d; uten den får en post filens ttl, eller 1h. MX tar priority (standard 10), SRV priority, weight og port, REDIRECT save_path (standard true).
• Det samme dokumentet fungerer som JSON. JSON Schema gir deg autofullføring og kontroller i VS Code og andre redigeringsprogrammer.

Slik lages en plan

Filen er hele sonen: en post som finnes i sonen, men ikke i filen, slettes. Bruk --keep-unlisted (prune=false i API-et) for bare å legge til og endre.

A-, AAAA-, MX- og TXT-poster matches på navn og verdi (og prioritet for MX), siden ett navn kan ha flere av dem. CNAME-, SRV-, PTR- og REDIRECT-poster matches på navn. En annen ttl, eller en annen SRV-prioritet, -vekt eller -port, regnes som en endring; alt annet er et tillegg eller en sletting.

Apply kjøres i én transaksjon: først slettinger, deretter endringer, så nye poster, slik at en CNAME kan erstatte en A-post i samme fil. Hvis én post avvises, endres ingenting. Hvis noen endrer sonen mellom plan og apply, avvises apply, og du må lage en ny plan.

Poster som NameOcean beholder for seg selv, adressen bak en HTTP-videresending og ACME-utfordringene for SSL, blir aldri eksportert, planlagt eller slettet.

GitHub Actions

Opprett en API-nøkkel med dns:write (eller bare dns:read for en jobb som planlegger) og lagre den som hemmeligheten 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 avslutter med kode 2 når det finnes endringer, for jobber som bare skal rapportere avvik.

Med REST API-et

$ 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

Send YAML med Content-Type: application/yaml eller det samme dokumentet som JSON. En fil serveren ikke kan godta, besvares med 400 invalid_zone_file og en errors-liste som navngir hver post og hvert felt. Alt dette finner du i API-referansen.

Fra din KI

Via MCP kan en assistent eksportere en sone, planlegge en endring av mange poster samtidig med plan_dns_zone og, etter å ha vist deg planen, ta den i bruk med apply_dns_zone.