DNS jako kód

Začněte od své zóny

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

Soubor

# 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 je @ pro samotnou zónu nebo název relativní k ní (www, _dmarc); funguje i plně kvalifikovaný název s tečkou na konci.
• type je A, AAAA, CNAME, MX, TXT, SRV, PTR nebo REDIRECT (HTTP přesměrování na URL ve value).
• ttl je 5m, 15m, 30m, 1h nebo 1d; bez něj záznam dostane ttl souboru, nebo 1h. MX přijímá priority (výchozí 10), SRV priority, weight a port, REDIRECT save_path (výchozí true).
• Stejný dokument funguje i jako JSON. JSON Schema vám poskytne doplňování a kontroly ve VS Code a dalších editorech.

Jak vzniká plán

Soubor představuje celou zónu: záznam, který je v zóně, ale ne v souboru, se smaže. Použijte --keep-unlisted (v API prune=false), chcete-li pouze přidávat a měnit.

Záznamy A, AAAA, MX a TXT se párují podle názvu a hodnoty (u MX také podle priority), protože jeden název může mít více takových záznamů. Záznamy CNAME, SRV, PTR a REDIRECT se párují podle názvu. Jiná hodnota ttl nebo u SRV jiná priorita, váha či port se považuje za změnu; vše ostatní je přidání nebo smazání.

Apply probíhá v jedné transakci: nejprve mazání, pak změny, pak nové záznamy, takže CNAME může ve stejném souboru nahradit záznam A. Pokud je jeden záznam odmítnut, nic se nezmění. Pokud někdo změní zónu mezi plánem a aplikací, apply je odmítnuto a musíte vytvořit nový plán.

Záznamy, které si NameOcean ponechává pro sebe – adresa za HTTP přesměrováním a ACME výzvy pro SSL – se nikdy neexportují, neplánují ani nemažou.

GitHub Actions

Vytvořte API klíč s oprávněním dns:write (nebo jen dns:read pro úlohu, která pouze plánuje) a uložte ho jako 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 skončí s kódem 2, pokud existují změny – pro úlohy, které mají pouze hlásit odchylky.

Přes 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

Odešlete YAML s hlavičkou Content-Type: application/yaml nebo stejný dokument jako JSON. Pokud server soubor nemůže přijmout, odpoví chybou 400 invalid_zone_file se seznamem errors, který uvádí každý záznam a pole. Vše najdete v referenci API.

Z vaší AI

Přes MCP může asistent exportovat zónu, pomocí plan_dns_zone naplánovat změnu mnoha záznamů najednou a poté, co Vám plán ukáže, jej použít pomocí apply_dns_zone.