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.

Из Вашего ИИ

Через MCP ассистент может экспортировать зону, спланировать изменение сразу многих записей с помощью plan_dns_zone и, показав Вам план, применить его с помощью apply_dns_zone.