DNS jako kod

Zacznij od swojej strefy

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

Plik

# 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 to @ dla samej strefy lub nazwa względna wobec niej (www, _dmarc); działa też pełna nazwa domenowa zakończona kropką.
• type to A, AAAA, CNAME, MX, TXT, SRV, PTR lub REDIRECT (przekierowanie HTTP na adres URL podany w value).
• ttl to 5m, 15m, 30m, 1h lub 1d; bez tego pola rekord otrzymuje ttl z pliku albo 1h. MX przyjmuje priority (domyślnie 10), SRV priority, weight i port, a REDIRECT save_path (domyślnie true).
• Ten sam dokument działa również jako JSON. JSON Schema zapewnia podpowiedzi i walidację w VS Code oraz innych edytorach.

Jak powstaje plan

Plik to cała strefa: rekord, który jest w strefie, ale nie ma go w pliku, zostanie usunięty. Użyj --keep-unlisted (prune=false w API), aby tylko dodawać i zmieniać rekordy.

Rekordy A, AAAA, MX i TXT są dopasowywane według nazwy i wartości (a w przypadku MX także priorytetu), ponieważ jedna nazwa może mieć kilka takich rekordów. Rekordy CNAME, SRV, PTR i REDIRECT są dopasowywane według nazwy. Inna wartość ttl albo inny priorytet, waga lub port rekordu SRV oznacza zmianę; wszystko inne jest dodaniem lub usunięciem.

Apply działa w jednej transakcji: najpierw usunięcia, potem zmiany, a na końcu nowe rekordy, dzięki czemu CNAME może zastąpić rekord A w tym samym pliku. Jeśli jeden rekord zostanie odrzucony, nic nie zostanie zmienione. Jeśli ktoś zmieni strefę między planem a apply, apply zostanie odrzucone i trzeba ponownie utworzyć plan.

Rekordy, które NameOcean utrzymuje na własne potrzeby – adres obsługujący przekierowanie HTTP oraz wyzwania ACME dla SSL – nigdy nie są eksportowane, planowane ani usuwane.

GitHub Actions

Utwórz klucz API z uprawnieniem dns:write (lub tylko dns:read dla zadania, które jedynie tworzy plan) i zapisz go jako sekret 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 zwraca kod 2, gdy są zmiany – przydatne w zadaniach, które mają tylko zgłaszać rozbieżności.

Przez 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

Wyślij YAML z nagłówkiem Content-Type: application/yaml lub ten sam dokument jako JSON. Jeśli serwer nie może przyjąć pliku, odpowiada kodem 400 invalid_zone_file z listą errors, która wskazuje każdy rekord i pole. Wszystkie szczegóły znajdą Państwo w dokumentacji API.

Z poziomu Twojej AI

Za pośrednictwem MCP asystent może wyeksportować strefę, zaplanować zmianę wielu rekordów jednocześnie za pomocą plan_dns_zone, a po przedstawieniu Państwu planu zastosować ją za pomocą apply_dns_zone.