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.
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.
| Objet | Ce que tu peux changer | Effet immédiat ? |
|---|---|---|
| Rrset A/AAAA/CNAME | Valeur, TTL | Non, dépend du TTL |
| NS de zone | Délégation chez le registre parent | Non, 24 à 48 h |
| SOA | Serial, refresh, minimum | Oui, sur le cache négatif |
| DNSSEC | Clés, enregistrements DS | Non, 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ère | REST JSON | RFC 2136 |
|---|---|---|
| Authentification | Token scopé, IAM, OAuth | Clé TSIG partagée (HMAC-SHA256) |
| Granularité | Par enregistrement ou par lot | Par instruction update |
| Atomicité | Souvent par zone | Aucune, chaque update est indépendant |
| Audit | Logs fournisseur, horodatés | Logs serveur si tu les actives |
| Idempotence | PATCH 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
| Fournisseur | Endpoint de base | Auth | Modèle d'écriture | Piège principal |
|---|---|---|---|---|
| Cloudflare | /client/v4/zones/{id}/dns_records | Bearer token | POST + PATCH par record | ttl: 1 = automatique, et proxied masque l'origine |
| AWS Route 53 | ChangeResourceRecordSets | SigV4 (IAM) | UPSERT du rrset complet | XML ChangeBatch, attente INSYNC |
| Google Cloud DNS | changes.create | Compte de service | additions + deletions | Une mise à jour = un delete puis un add |
| deSEC | /api/v1/domains/{nom}/rrsets/ | Token | PUT/PATCH de rrset | DNSSEC géré, TTL minimum imposé |
| PowerDNS | /api/v1/servers/localhost/zones/{zone} | X-API-Key | PATCH rrsets | Rectification 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.frqui 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 ?
| Usage | TTL | Raison |
|---|---|---|
| Bascule planifiée | 60–120 s | Rollback rapide, charge accrue sur les autoritatifs |
| Enregistrement stable | 3600 s | Moins de requêtes, cache efficace |
| Validation ACME / TXT | 60 s | Le temps que le CA interroge, puis supprime |
| MX et SPF | 3600 s | Changement 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.