Desarrolladores → DNS como código

DNS como código

Mantenga su zona en un único archivo YAML o JSON junto a su código. Revise los cambios de DNS en pull requests, vea exactamente qué va a cambiar antes de que ocurra y aplíquelo en un solo paso.

Empiece desde su zona

nameocean

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

El archivo

dns.yaml

# 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 es @ para la propia zona o un nombre relativo a ella (www, _dmarc); también funciona un nombre completo con el punto final.
type es A, AAAA, CNAME, MX, TXT, SRV, PTR o REDIRECT (una redirección HTTP a la URL indicada en value).
ttl es 5m, 15m, 30m, 1h o 1d; si no se indica, el registro toma el ttl del archivo, o 1h. MX admite priority (por defecto 10), SRV priority, weight y port, y REDIRECT save_path (por defecto true).
El mismo documento funciona como JSON. El JSON Schema le ofrece autocompletado y validación en VS Code y otros editores.

Cómo se genera un plan

El archivo es la zona completa: un registro que está en la zona pero no en el archivo se elimina. Use --keep-unlisted (prune=false en la API) para solo añadir y cambiar.

Los registros A, AAAA, MX y TXT se identifican por nombre y valor (y por prioridad en el caso de MX), ya que un mismo nombre puede tener varios de ellos. Los registros CNAME, SRV, PTR y REDIRECT se identifican por nombre. Un ttl distinto, o una prioridad, peso o puerto de SRV distintos, se considera un cambio; todo lo demás es una adición o una eliminación.

Apply se ejecuta en una sola transacción: primero las eliminaciones, luego los cambios y después los registros nuevos, de modo que un CNAME puede sustituir a un registro A en el mismo archivo. Si se rechaza un registro, no se cambia nada. Si alguien modifica la zona entre el plan y el apply, el apply se rechaza y debe volver a generar el plan.

Los registros que NameOcean reserva para sí mismo, la dirección detrás de una redirección HTTP y los desafíos ACME para SSL, nunca se exportan, planifican ni eliminan.

GitHub Actions

Cree una clave de API con dns:write (o solo dns:read para un job que solo genere planes) y guárdela como el secreto NAMEOCEAN_API_KEY.

.github/workflows/dns.yml

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 termina con código 2 cuando hay cambios, para jobs que solo deben informar de desviaciones.

Con la API REST

GET /dns/{zone}/export?output=yaml	La zona como archivo (JSON sin output=yaml); la cabecera X-Zone-Serial contiene su número de serie
POST /dns/{zone}/plan	Lo que haría apply; no cambia nada y solo requiere dns:read
POST /dns/{zone}/apply?serial=N	Hace que la zona coincida con el archivo; devuelve 409 zone_changed si ya no está en el serial del plan

curl

$ 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

Envíe YAML con Content-Type: application/yaml o el mismo documento en JSON. Si el servidor no puede aceptar un archivo, responde 400 invalid_zone_file con una lista errors que indica cada registro y campo. Encontrará todos los detalles en la referencia de la API.

Desde su IA

A través de MCP, un asistente puede exportar una zona, planificar un cambio en muchos registros a la vez con plan_dns_zone y, después de mostrarle el plan, aplicarlo con apply_dns_zone.