Les APIs essentielles pour les nameservers

Cloudflare, Route 53, Google Cloud DNS, deSEC et PowerDNS : le code, les pieges et les tests qui font la difference quand tu pilotes tes zones par API.

Les APIs essentielles pour les nameservers

Un enregistrement A modifié à la main dans l'interface d'un registrar ne laisse aucune trace exploitable. Trois personnes disposent des mêmes droits, aucun diff n'existe, et personne ne sait qui a mis 10.0.4.12 à la place de 10.0.4.11 un mardi à 9 h 12. Une API de nameservers règle ce problème avant même de parler d'automatisation : chaque changement devient une requête datée, attribuable et rejouable.

J'ai basculé une dizaine de zones vers des APIs ces deux dernières années. Le gain réel n'est pas la vitesse, c'est la réversibilité : un changement raté se corrige en une commande au lieu d'un appel au support à 23 h.

Ce que pilote vraiment une API de nameservers

Une zone DNS, c'est trois objets et pas un. Le SOA et les NS de délégation, les rrsets (un nom, un type, un TTL, une ou plusieurs valeurs), et la chaîne DNSSEC quand elle existe. Une API sérieuse expose les trois ; une API de registrar se contente souvent du deuxième et ignore le reste.

Ce qu'aucune API ne fait : propager. Le TTL de l'enregistrement décide de la durée pendant laquelle les résolveurs gardent l'ancienne valeur. Un enregistrement à 3600 s reste faux pendant une heure, même si ta requête a renvoyé 200 en 80 ms.

ObjetCe que tu peux changerEffet immédiat ?
Rrset A/AAAA/CNAMEValeur, TTLNon, dépend du TTL
NS de zoneDélégation chez le registre parentNon, 24 à 48 h
SOASerial, refresh, minimumOui, sur le cache négatif
DNSSECClés, enregistrements DSNon, et casse la zone si mal ordonné

Deux familles d'API à ne pas confondre

Les APIs REST JSON (Cloudflare, Route 53, Google Cloud DNS, deSEC, PowerDNS) parlent au plan de contrôle du fournisseur. Elles gèrent les zones, les tokens, les quotas, et souvent les transactions.

Le DNS UPDATE de la RFC 2136 parle directement au serveur autoritatif, en UDP ou TCP sur le port 53, authentifié par TSIG. C'est le seul choix quand tu héberges tes propres nameservers BIND ou Knot, et c'est aussi le plus brutal : pas de rollback, pas d'historique, juste des paquets.

CritèreREST JSONRFC 2136
AuthentificationToken scopé, IAM, OAuthClé TSIG partagée (HMAC-SHA256)
GranularitéPar enregistrement ou par lotPar instruction update
AtomicitéSouvent par zoneAucune, chaque update est indépendant
AuditLogs fournisseur, horodatésLogs serveur si tu les actives
IdempotencePATCH ou UPSERTÀ construire toi-même

Le choix se fait donc sur une question simple : la zone est-elle hébergée chez un fournisseur ou sur tes machines ? Le reste, y compris le style d'API, en découle. Si tu compares encore les modèles d'API côté application, mon comparatif APIs REST vs GraphQL couvre le sujet sous l'angle client.

Les cinq APIs qui couvrent la quasi-totalité des cas

FournisseurEndpoint de baseAuthModèle d'écriturePiège principal
Cloudflare/client/v4/zones/{id}/dns_recordsBearer tokenPOST + PATCH par recordttl: 1 = automatique, et proxied masque l'origine
AWS Route 53ChangeResourceRecordSetsSigV4 (IAM)UPSERT du rrset completXML ChangeBatch, attente INSYNC
Google Cloud DNSchanges.createCompte de serviceadditions + deletionsUne mise à jour = un delete puis un add
deSEC/api/v1/domains/{nom}/rrsets/TokenPUT/PATCH de rrsetDNSSEC géré, TTL minimum imposé
PowerDNS/api/v1/servers/localhost/zones/{zone}X-API-KeyPATCH rrsetsRectification et serial à gérer

Hetzner et OVH restent utilisables, mais leurs APIs DNS sentent le SOAP de 2013 : pas de PATCH partiel, pas de transaction, et des identifiants de record qui changent après certaines opérations.

Cloudflare : un token, un scope, une requête

Commence par un token limité à une zone et au droit Zone → DNS → Edit. Un token global dans une variable d'environnement de CI, c'est un incident qui attend son heure — j'ai détaillé cette logique dans comment sécuriser une API.

Le code ci-dessous fait un upsert idempotent : il cherche l'enregistrement, le patche s'il existe, le crée sinon. Relancé dix fois, il produit le même état.

import os, requests

ZONE = "exemple.fr"
H = {"Authorization": f"Bearer {os.environ['CF_DNS_TOKEN']}",
     "Content-Type": "application/json"}
API = "https://api.cloudflare.com/client/v4"

zid = requests.get(f"{API}/zones", params={"name": ZONE}, headers=H).json()["result"][0]["id"]
record = {"type": "A", "name": f"api.{ZONE}", "content": "203.0.113.42", "ttl": 120}

found = requests.get(f"{API}/zones/{zid}/dns_records",
                     params={"type": "A", "name": record["name"]},
                     headers=H).json()["result"]

if found:
    rid = found[0]["id"]
    r = requests.patch(f"{API}/zones/{zid}/dns_records/{rid}",
                       json={"content": record["content"], "ttl": 120}, headers=H)
else:
    r = requests.post(f"{API}/zones/{zid}/dns_records", json=record, headers=H)
r.raise_for_status()

Deux détails qui font perdre une soirée. Avec proxied: true, Cloudflare impose son TTL et ignore le tien : ton ttl: 120 devient un cache de 300 s côté edge. Et un PATCH sur un champ absent ne l'efface pas ; pour retirer une valeur, il faut envoyer explicitement la nouvelle liste.

Route 53 : le ChangeBatch qui piège tout le monde

Route 53 ne connaît pas la notion de « modifier un enregistrement ». Tu envoies un rrset complet avec une action CREATE, DELETE ou UPSERT, et le service remplace l'ensemble.

Conséquence directe : un UPSERT avec une seule valeur sur un round-robin à trois adresses supprime les deux autres. Sans erreur, sans avertissement.

import boto3

r53 = boto3.client("route53")
change = r53.change_resource_record_sets(
    HostedZoneId="Z0123456789ABCDEFGHIJ",
    ChangeBatch={"Changes": [{
        "Action": "UPSERT",
        "ResourceRecordSet": {
            "Name": "api.exemple.fr.", "Type": "A", "TTL": 120,
            "ResourceRecords": [{"Value": "203.0.113.42"}],
        },
    }]},
)
r53.get_waiter("resource_record_sets_changed").wait(Id=change["ChangeInfo"]["Id"])

Le 200 de ChangeResourceRecordSets signifie « changement accepté », pas « changement propagé ». Le statut reste PENDING jusqu'à ce que les quatre nameservers de la zone aient la nouvelle version. Le waiter ci-dessus attend INSYNC, et c'est la seule réponse qui compte.

Google Cloud DNS : update = delete + add

Cloud DNS impose la transaction explicite. Pour changer une valeur, tu supprimes l'ancien rrset et tu ajoutes le nouveau dans le même changes.create. Les deux opérations réussissent ou échouent ensemble, ce qui évite l'état intermédiaire d'un delete suivi d'un add séparés.

gcloud dns record-sets transaction start --zone=exemple-fr
gcloud dns record-sets transaction remove --zone=exemple-fr \
  --name=api.exemple.fr. --type=A --ttl=300 --rrdatas=203.0.113.10
gcloud dns record-sets transaction add --zone=exemple-fr \
  --name=api.exemple.fr. --type=A --ttl=120 --rrdatas=203.0.113.42
gcloud dns record-sets transaction execute --zone=exemple-fr

La commande remove doit décrire l'enregistrement exact, TTL compris. Un TTL qui ne correspond pas fait échouer la transaction avec un 412 peu bavard. C'est pénible, mais c'est aussi ce qui garantit que tu ne supprimes pas autre chose que ce que tu visais.

PowerDNS et RFC 2136 : quand tu héberges tes nameservers

Sur une instance PowerDNS autoritative, l'API HTTP modifie la base directement. Le corps est une liste de rrsets avec un changetype valant REPLACE ou DELETE, et le serveur s'occupe du NOTIFY vers les secondaires.

curl -sS -X PATCH "http://ns1.exemple.fr:8081/api/v1/servers/localhost/zones/exemple.fr." \
  -H "X-API-Key: $PDNS_API_KEY" -H "Content-Type: application/json" \
  -d '{"rrsets":[{"name":"api.exemple.fr.","type":"A","ttl":120,
        "changetype":"REPLACE",
        "records":[{"content":"203.0.113.42","disabled":false}]}]}'

Si ton serveur est BIND ou Knot, tu passes par nsupdate avec une clé TSIG. Le même changement tient en cinq lignes, mais rien ne te protège d'une faute de frappe.

nsupdate -k /etc/bind/Kexemple.fr.+165+20345.private <<'EOF'
server ns1.exemple.fr
zone exemple.fr
update delete api.exemple.fr. A
update add api.exemple.fr. 120 A 203.0.113.42
send
EOF

Deux réflexes dans ce mode : vérifier le serial SOA après l'envoi, et rectifier la zone si ton backend est SQL avec DNSSEC. Sur PowerDNS, une rrset modifiée sans pdnsutil rectify-zone exemple.fr peut servir des signatures DNSSEC invalides, donc un SERVFAIL chez tous les résolveurs validants.

Tester un changement avant de le considérer comme fait

Interroger 1.1.1.1 ne prouve rien : tu lis le cache d'un résolveur, pas ta zone. La seule vérification utile interroge chaque serveur autoritatif en +norecurse.

for ns in $(dig +short NS exemple.fr); do
  printf "%-28s " "$ns"
  dig +norecurse +short @"$ns" api.exemple.fr A | tr '\n' ' '
  echo
done

Trois réponses identiques et à jour : la zone est cohérente. Une réponse différente sur un seul serveur signale un secondaire qui n'a pas reçu le NOTIFY, ou un transfert AXFR bloqué par un pare-feu.

Pense aussi au cache négatif. Un NXDOMAIN est mémorisé pendant la durée du champ minimum du SOA, souvent 3600 s. Si tu crées un enregistrement après avoir testé son absence, ton propre poste peut continuer à répondre « inexistant » longtemps après la création.

Les erreurs qui coûtent vraiment cher

  • TTL à 3600 pendant une migration. Baisse à 120 s au moins 24 h avant la bascule, remonte après. Sinon le rollback prend une heure.
  • CNAME à l'apex. Interdit par la RFC 1034, toléré par certains fournisseurs via un aplatissement interne. Cloudflare l'accepte, Route 53 seulement en type Alias.
  • Token global dans la CI. Une fuite de log donne le contrôle de toutes les zones du compte. Un token par zone, révoquable, coûte deux minutes à créer.
  • Suppression d'un joker sans le voir. Un *.exemple.fr qui répond reste invisible dans une recherche par nom exact. Liste toujours les rrsets avant un delete.
  • DNSSEC et changement de NS. Retire le DS chez le registre avant de changer les nameservers, sinon la zone devient injoignable pour tous les résolveurs validants.

FAQ : les trois questions qui reviennent

Faut-il une API ou un provider Terraform ?

Les deux, à des étages différents. Terraform gère l'état désiré et détecte les dérives, mais un apply prend 20 à 40 s et ne convient pas à une bascule d'urgence. L'API brute reste l'outil du runbook, celui qu'on exécute sous pression.

Une règle qui marche : tout ce qui est stable dans le temps passe par Terraform, tout ce qui est opérationnel (bascule, enregistrement de validation, ACME) passe par un script qui appelle l'API directement.

Quelle TTL choisir concrètement ?

UsageTTLRaison
Bascule planifiée60–120 sRollback rapide, charge accrue sur les autoritatifs
Enregistrement stable3600 sMoins de requêtes, cache efficace
Validation ACME / TXT60 sLe temps que le CA interroge, puis supprime
MX et SPF3600 sChangement rare, cache long assumé

Peut-on tester une zone sans la publier ?

Oui, avec un serveur autoritatif jetable. Charge ta zone dans un conteneur BIND ou Knot, interroge-le en local sur un port non standard, et compare les réponses avec la zone de production.

docker run --rm -v "$PWD/zone:/zones" -p 5353:53/udp \
  internetsystemsconsortium/bind9:9.18
dig +short @127.0.0.1 -p 5353 api.exemple.fr A

C'est le seul moyen de valider une syntaxe de zone ou une chaîne DNSSEC complète sans risquer la production. Trente secondes de test contre une heure de SERVFAIL, le calcul est vite fait.

Le vrai livrable, c'est le diff

Une API DNS ne rend pas ton infrastructure plus moderne. Elle rend tes changements explicites : une requête, un horodatage, une valeur avant et une valeur après. C'est ça qui se rejoue, se documente et s'audite.

Commence petit : un token scopé, un script d'upsert, une boucle de vérification sur les autoritatifs. Les trois ensemble remplacent déjà la moitié des interventions manuelles sur tes zones.