DNS като код

Започнете от зоната си

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

Файлът

# 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 е @ за самата зона или име спрямо нея (www, _dmarc); работи и пълно име с точка накрая.
• type е A, AAAA, CNAME, MX, TXT, SRV, PTR или REDIRECT (HTTP пренасочване към URL адреса във value).
• ttl е 5m, 15m, 30m, 1h или 1d; без него записът получава ttl на файла или 1h. MX приема priority (по подразбиране 10), SRV – priority, weight и port, REDIRECT – save_path (по подразбиране true).
• Същият документ работи и като JSON. JSON Schema Ви дава автоматично довършване и проверки във VS Code и други редактори.

Как се създава план

Файлът е цялата зона: запис, който е в зоната, но не и във файла, се изтрива. Използвайте --keep-unlisted (prune=false в API), за да само добавяте и променяте.

Записите A, AAAA, MX и TXT се съпоставят по име и стойност (а за MX – и по приоритет), тъй като едно име може да има няколко такива записа. Записите CNAME, SRV, PTR и REDIRECT се съпоставят по име. Различен ttl или различни приоритет, тегло или порт при SRV се считат за промяна; всичко останало е добавяне или изтриване.

Apply се изпълнява в една транзакция: първо изтриванията, после промените, след това новите записи, така че CNAME може да замени A запис в същия файл. Ако един запис бъде отказан, нищо не се променя. Ако някой промени зоната между plan и apply, apply се отказва и трябва да направите plan отново.

Записите, които NameOcean поддържа за себе си – адресът зад HTTP пренасочване и ACME проверките за SSL – никога не се експортират, планират или изтриват.

GitHub Actions

Създайте API ключ с dns:write (или само dns:read за задача, която само планира) и го запазете като тайна 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 завършва с код 2, когато има промени – за задачи, които трябва само да докладват разминавания.

Чрез 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

Изпратете YAML с Content-Type: application/yaml или същия документ като JSON. Ако сървърът не може да приеме файла, той отговаря с 400 invalid_zone_file и списък errors, в който е посочен всеки проблемен запис и поле. Всичко това е описано в справочника за API.

От вашия AI

Чрез MCP асистентът може да експортира зона, да планира промяна на много записи наведнъж с plan_dns_zone и след като Ви покаже плана, да го приложи с apply_dns_zone.