DNS as code

Partir de votre zone

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

Le fichier

# 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 vaut @ pour la zone elle-même ou un nom relatif à celle-ci (www, _dmarc) ; un nom pleinement qualifié avec le point final fonctionne également.
• type vaut A, AAAA, CNAME, MX, TXT, SRV, PTR ou REDIRECT (une redirection HTTP vers l'URL indiquée dans value).
• ttl vaut 5m, 15m, 30m, 1h ou 1d ; sans lui, un enregistrement reçoit le ttl du fichier, ou 1h. MX accepte priority (10 par défaut), SRV priority, weight et port, REDIRECT save_path (true par défaut).
• Le même document fonctionne en JSON. Le JSON Schema vous offre l'autocomplétion et la validation dans VS Code et d'autres éditeurs.

Comment un plan est établi

Le fichier représente la zone entière : un enregistrement présent dans la zone mais absent du fichier est supprimé. Utilisez --keep-unlisted (prune=false dans l'API) pour uniquement ajouter et modifier.

Les enregistrements A, AAAA, MX et TXT sont identifiés par leur nom et leur valeur (ainsi que par leur priorité pour MX), car un même nom peut en comporter plusieurs. Les enregistrements CNAME, SRV, PTR et REDIRECT sont identifiés par leur nom. Un ttl différent, ou une priorité, un poids ou un port SRV différent, constitue une modification ; tout le reste est un ajout ou une suppression.

Apply s'exécute en une seule transaction : d'abord les suppressions, puis les modifications, puis les nouveaux enregistrements, de sorte qu'un CNAME peut remplacer un enregistrement A dans le même fichier. Si un enregistrement est refusé, rien n'est modifié. Si quelqu'un modifie la zone entre le plan et l'apply, l'apply est refusé et vous devez refaire un plan.

Les enregistrements que NameOcean conserve pour lui-même, à savoir l'adresse derrière une redirection HTTP et les challenges ACME pour le SSL, ne sont jamais exportés, planifiés ni supprimés.

GitHub Actions

Créez une clé API avec dns:write (ou seulement dns:read pour un job qui ne fait que planifier) et enregistrez-la comme 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 renvoie le code 2 en cas de modifications, pour les jobs qui doivent seulement signaler les écarts.

Avec l'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

Envoyez du YAML avec Content-Type: application/yaml ou le même document en JSON. Si le serveur ne peut pas accepter un fichier, il répond 400 invalid_zone_file avec une liste errors indiquant chaque enregistrement et chaque champ concernés. Tous les détails figurent dans la référence de l'API.

Depuis votre IA

Via MCP, un assistant peut exporter une zone, planifier une modification de nombreux enregistrements à la fois avec plan_dns_zone et, après vous avoir présenté le plan, l'appliquer avec apply_dns_zone.