Fejlesztők → DNS kódként

DNS kódként

Tárolja zónáját egyetlen YAML- vagy JSON-fájlban a kódja mellett. Nézze át a DNS-változásokat pull requestekben, lássa pontosan, mi fog változni, mielőtt megtörténne, és alkalmazza egyetlen lépésben.

Induljon ki a zónájából

nameocean

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

A fájl

dns.yaml

# 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

A name értéke @ magára a zónára, vagy egy hozzá viszonyított név (www, _dmarc); a záró ponttal ellátott teljes név is működik.
A type lehet A, AAAA, CNAME, MX, TXT, SRV, PTR vagy REDIRECT (HTTP-átirányítás a value mezőben megadott URL-re).
A ttl lehet 5m, 15m, 30m, 1h vagy 1d; ha hiányzik, a rekord a fájl ttl értékét kapja, vagy 1h-t. Az MX priority értéket fogad (alapértelmezés: 10), az SRV priority, weight és port értéket, a REDIRECT save_path értéket (alapértelmezés: true).
Ugyanez a dokumentum JSON formátumban is működik. A JSON Schema automatikus kiegészítést és ellenőrzést biztosít a VS Code-ban és más szerkesztőkben.

Hogyan készül a terv

A fájl a teljes zóna: az a rekord, amely szerepel a zónában, de a fájlban nem, törlődik. Adja meg a --keep-unlisted kapcsolót (az API-ban prune=false), ha csak hozzáadni és módosítani szeretne.

Az A, AAAA, MX és TXT rekordokat név és érték (MX esetén prioritás) alapján egyeztetjük, mivel egy névhez több ilyen rekord is tartozhat. A CNAME, SRV, PTR és REDIRECT rekordokat név alapján egyeztetjük. Az eltérő ttl, illetve SRV esetén az eltérő prioritás, súly vagy port módosításnak számít; minden más hozzáadás vagy törlés.

Az apply egyetlen tranzakcióban fut: először a törlések, majd a módosítások, végül az új rekordok, így egy CNAME ugyanabban a fájlban leválthat egy A rekordot. Ha egy rekordot elutasít a rendszer, semmi sem változik. Ha valaki a plan és az apply között módosítja a zónát, az apply elutasításra kerül, és újra kell tervezni.

A NameOcean által saját célra fenntartott rekordokat – a HTTP-átirányítás mögötti címet és az SSL-hez tartozó ACME-ellenőrzéseket – soha nem exportáljuk, tervezzük vagy töröljük.

GitHub Actions

Hozzon létre egy API-kulcsot dns:write jogosultsággal (vagy csak dns:read jogosultsággal, ha a feladat csak tervez), és mentse el NAMEOCEAN_API_KEY secretként.

.github/workflows/dns.yml

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

A dns plan --detailed-exitcode 2-es kóddal lép ki, ha vannak változások – olyan feladatokhoz, amelyeknek csak az eltérést kell jelezniük.

A REST API-val

GET /dns/{zone}/export?output=yaml	A zóna fájlként (JSON, ha nincs output=yaml); az X-Zone-Serial fejléc tartalmazza a sorozatszámát
POST /dns/{zone}/plan	Mit tenne az apply; semmit sem módosít, és csak dns:read jogosultság kell hozzá
POST /dns/{zone}/apply?serial=N	A zóna igazítása a fájlhoz; 409 zone_changed, ha már nem a terv szerinti serial értéken áll

curl

$ 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

YAML-t küldjön Content-Type: application/yaml fejléccel, vagy ugyanezt a dokumentumot JSON formátumban. Ha a szerver nem tudja elfogadni a fájlt, 400 invalid_zone_file választ ad egy errors listával, amely megnevezi az érintett rekordokat és mezőket. Minden részlet megtalálható az API-referenciában.

Az AI-jából

Az MCP segítségével egy asszisztens exportálhat egy zónát, a plan_dns_zone eszközzel egyszerre több rekord módosítását is megtervezheti, majd miután megmutatta Önnek a tervet, az apply_dns_zone eszközzel alkalmazhatja azt.