DNS como código

Comece a partir da sua zona

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

O arquivo

# 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 é @ para a própria zona ou um nome relativo a ela (www, _dmarc); um nome totalmente qualificado com o ponto final também funciona.
• type é A, AAAA, CNAME, MX, TXT, SRV, PTR ou REDIRECT (um redirecionamento HTTP para a URL em value).
• ttl é 5m, 15m, 30m, 1h ou 1d; sem ele, um registro recebe o ttl do arquivo, ou 1h. MX aceita priority (padrão 10), SRV aceita priority, weight e port, REDIRECT aceita save_path (padrão true).
• O mesmo documento funciona como JSON. O JSON Schema oferece preenchimento automático e verificações no VS Code e em outros editores.

Como um plano é criado

O arquivo é a zona inteira: um registro que está na zona, mas não no arquivo, é excluído. Use --keep-unlisted (prune=false na API) para apenas adicionar e alterar.

Os registros A, AAAA, MX e TXT são correspondidos por nome e valor (e prioridade, no caso de MX), já que um mesmo nome pode ter vários deles. Os registros CNAME, SRV, PTR e REDIRECT são correspondidos por nome. Um ttl diferente, ou uma prioridade, peso ou porta SRV diferente, é considerado uma alteração; todo o resto é uma adição ou uma exclusão.

O apply é executado em uma única transação: primeiro as exclusões, depois as alterações e por fim os novos registros, de modo que um CNAME pode substituir um registro A no mesmo arquivo. Se um registro for recusado, nada é alterado. Se alguém alterar a zona entre o plan e o apply, o apply é recusado e você precisa gerar o plano novamente.

Os registros que a NameOcean mantém para si, o endereço por trás de um redirecionamento HTTP e os desafios ACME para SSL, nunca são exportados, planejados ou excluídos.

GitHub Actions

Crie uma chave de API com dns:write (ou apenas dns:read para um job que só gera planos) e salve-a como o 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 sai com código 2 quando há alterações, para jobs que devem apenas reportar divergências.

Com a API REST

$ 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

Envie YAML com Content-Type: application/yaml ou o mesmo documento em JSON. Um arquivo que o servidor não pode aceitar responde 400 invalid_zone_file com uma lista errors indicando cada registro e campo. Tudo isso está na referência da API.

A partir da sua IA

Através do MCP, um assistente pode exportar uma zona, planear uma alteração a vários registos de uma só vez com plan_dns_zone e, depois de lhe mostrar o plano, aplicá-la com apply_dns_zone.