Dernière édition : 2026-07-11

Exploitation API PowerDNS

Bannière LoutikCloud

Informations

Date de mise à jour : 2026-07-11
Service ciblé : DNS
Auteur : Louis MEDO
Responsable : Louis MEDO

1. Contexte

Ce runbook détaille les procédures opérationnelles standards pour le cycle de vie complet des zones et des enregistrements DNS sur l'infrastructure PowerDNS (LoutikCLOUD). Ces opérations s'appuient exclusivement sur l'API REST afin de garantir la cohérence avec les principes Infrastructure as Code (IaC) de l'orchestrateur OpsBricks. Cette procédure doit être exécutée lors d'une demande de modification de routage interne, d'ajout d'une nouvelle machine, ou pour des actions de maintenance (MCO).

2. Prérequis

Connectivité réseau établie vers la DMZ Infrastructure (VLAN 13) ciblant l'IP 10.0.13.1 sur le port 8081.
Jeton d'authentification (Clé API) valide et récupéré depuis le gestionnaire de secrets (Ansible Vault).
Outil en ligne de commande curl et processeur JSON jq installés sur le poste opérateur ou le Bastion de rebond.

3. Procédure d'exécution

3.1. Lister les zones DNS actives (GET)

Vérification de l'état actuel et récupération de la liste complète des domaines gérés par le backend.

curl -X GET "http://10.0.13.1:8081/api/v1/servers/localhost/zones" \
-H "X-API-Key: changeme" \
-H "Accept: application/json" | jq .

-X GET : Méthode HTTP pour la consultation de ressources sans altération de l'état.
| jq . : Formatage du retour JSON pour une lecture humaine facilitée.

3.2. Création d'une nouvelle zone DNS (POST)

Initialisation d'une nouvelle zone (ex: infra.loutik.fr.) avec son enregistrement SOA d'origine et ses serveurs de noms (NS). L'attribut soa_edit_api est injecté pour automatiser l'incrémentation du numéro de série.

curl -X POST "http://10.0.13.1:8081/api/v1/servers/localhost/zones" \
-H "X-API-Key: changeme" \
-H "Content-Type: application/json" \
-d '{
  "name": "infra.loutik.fr.",
  "kind": "Native",
  "soa_edit_api": "INCEPTION-INCREMENT",
  "masters": [],
  "rrsets": [
    {
      "name": "infra.loutik.fr.",
      "type": "SOA",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "ns1.infra.loutik.fr. contact.loutik.fr. 2026071001 10800 3600 604800 3600",
          "disabled": false
        }
      ]
    },
    {
      "name": "infra.loutik.fr.",
      "type": "NS",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "ns1.infra.loutik.fr.",
          "disabled": false
        },
        {
          "content": "ns2.infra.loutik.fr.",
          "disabled": false
        }
      ]
    }
  ]
}'

-X POST : Méthode HTTP utilisée pour la création d'une nouvelle entité racine.
"kind": "Native" : Délègue la réplication des données aux mécanismes natifs de PostgreSQL.

3.3. Ajout ou modification d'enregistrements (A, AAAA, CNAME, TXT) (PATCH)

Déclaration de nouveaux enregistrements au sein d'une zone existante. La méthode REPLACE met à jour l'enregistrement s'il existe déjà ou le crée le cas échéant (Idempotence). L'API permet d'insérer plusieurs types d'enregistrements simultanément.

curl -X PATCH "http://10.0.13.1:8081/api/v1/servers/localhost/zones/infra.loutik.fr." \
-H "X-API-Key: changeme" \
-H "Content-Type: application/json" \
-d '{
  "rrsets": [
    {
      "name": "mlt1-opn-fw-prd-01.infra.loutik.fr.",
      "type": "A",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "10.0.20.254",
          "disabled": false
        }
      ]
    },
    {
      "name": "mlt1-opn-fw-prd-01.infra.loutik.fr.",
      "type": "AAAA",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "2001:db8:10:20::254",
          "disabled": false
        }
      ]
    },
    {
      "name": "fw.infra.loutik.fr.",
      "type": "CNAME",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "mlt1-opn-fw-prd-01.infra.loutik.fr.",
          "disabled": false
        }
      ]
    },
    {
      "name": "infra.loutik.fr.",
      "type": "TXT",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {
          "content": "\"v=spf1 -all\"",
          "disabled": false
        }
      ]
    }
  ]
}'

-X PATCH : Méthode HTTP standard pour appliquer des modifications partielles sur une ressource existante.
"changetype": "REPLACE" : Force l'écrasement de l'ancien Resource Record Set (RRSet) pour garantir l'état exact défini dans le body.
TXT content : La valeur doit obligatoirement inclure des guillemets échappés ("\"valeur\"") selon les spécifications RFC gérées par PowerDNS.

3.4. Suppression d'enregistrements (PATCH)

Retrait ciblé d'enregistrements obsolètes sans affecter le reste de la zone. Il est possible de supprimer plusieurs types (ex: IPv4 et IPv6) en une seule requête.

curl -X PATCH "http://10.0.13.1:8081/api/v1/servers/localhost/zones/infra.loutik.fr." \
-H "X-API-Key: changeme" \
-H "Content-Type: application/json" \
-d '{
  "rrsets": [
    {
      "name": "mlt1-opn-fw-prd-01.infra.loutik.fr.",
      "type": "A",
      "changetype": "DELETE"
    },
    {
      "name": "mlt1-opn-fw-prd-01.infra.loutik.fr.",
      "type": "AAAA",
      "changetype": "DELETE"
    },
    {
      "name": "fw.infra.loutik.fr.",
      "type": "CNAME",
      "changetype": "DELETE"
    }
  ]
}'

"changetype": "DELETE" : Instruction API spécifique ordonnant la suppression de l'enregistrement correspondant au type et au nom fournis.

3.5. Suppression complète d'une zone DNS (DELETE)

Démantèlement total d'un nom de domaine et de l'ensemble de ses enregistrements associés dans la base de données.

curl -X DELETE "http://10.0.13.1:8081/api/v1/servers/localhost/zones/infra.loutik.fr." \
-H "X-API-Key: changeme"

-X DELETE : Méthode HTTP destructrice finale purgeant la ressource du backend gpgsql.