DNS-Sollzustand auf Zone anwenden

Dieses Rezept setzt einen definierten DNS-Sollzustand gegen eine bestehende Zone durch. Sie lesen zuerst den Ist-Zustand, vergleichen ihn mit Ihrer Zieldefinition und führen dann gezielt Create-, Update- und Delete-Operationen aus.

Für genau diesen Ablauf gibt es auch ein kleines Bash-Beispielscript zum Download: dns-desired-state-sync-example.sh. Das Script liest den Sollzustand aus einer JSON-Datei und zeigt ohne Parameter direkt ein Beispiel für das erwartete Dateiformat an.

Voraussetzungen

ein API-Key mit Zugriff auf die DNS-Endpunkte
eine bestehende Zone bei regfish DNS
eine interne Sollzustandsdefinition, zum Beispiel aus Git, Terraform oder einer eigenen Service-Konfiguration
eine klare Regel, welche Records automatisiert verwaltet werden dürfen und welche nicht

Schritt 1: Aktuellen Zonenzustand lesen

Am Anfang steht immer ein vollständiger Snapshot der Zone. Entscheidend ist dabei, dass Sie nicht nur name, type und data sehen, sondern auch die id, damit Updates und Löschungen eindeutig werden.

curl --request GET \
  --url 'https://api.regfish.com/dns/example.com/rr' \
  --header 'x-api-key: YOUR_API_KEY'

Typischerweise erhalten Sie eine Liste mit Records und IDs:

{
  "success": true,
  "response": [
    {
      "id": 101,
      "type": "A",
      "name": "api.example.com.",
      "data": "203.0.113.10"
    },
    {
      "id": 102,
      "type": "CNAME",
      "name": "www.example.com.",
      "data": "example.com."
    }
  ]
}

Schritt 2: Sollzustand intern definieren

Legen Sie für die Synchronisation eine Zielmenge fest. In vielen Setups kommt sie aus einer Datei oder einem Deployment-System. Wichtig ist nur, dass Sie sie normiert vergleichen, also zum Beispiel FQDNs konsistent mit abschließendem Punkt speichern.

[
  {
    "type": "A",
    "name": "api.example.com.",
    "data": "203.0.113.20",
    "ttl": 300,
    "annotation": "managed-by=dns-desired-state-sync-example"
  },
  {
    "type": "CNAME",
    "name": "www.example.com.",
    "data": "example.com.",
    "ttl": 300,
    "annotation": "managed-by=dns-desired-state-sync-example"
  },
  {
    "type": "TXT",
    "name": "_service.example.com.",
    "data": "managed-by=regfish-api",
    "ttl": 300,
    "annotation": "managed-by=dns-desired-state-sync-example"
  }
]

Das Script läuft standardmäßig im Dry-Run und führt Änderungen erst mit APPLY=1 aus:

curl -fsSLO 'https://regfish.de/downloads/docs/dns-desired-state-sync-example.sh'
chmod +x dns-desired-state-sync-example.sh
./dns-desired-state-sync-example.sh
API_KEY=YOUR_API_KEY DOMAIN=example.com ./dns-desired-state-sync-example.sh desired-state.json
APPLY=1 API_KEY=YOUR_API_KEY DOMAIN=example.com ./dns-desired-state-sync-example.sh desired-state.json

Schritt 3: Fehlende Records anlegen

Records, die im Sollzustand vorkommen, aber im Ist-Zustand nicht existieren, legen Sie neu an. Das ist der einfachste Teil des Abgleichs.

curl --request POST \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "TXT",
  "name": "_service.example.com.",
  "data": "managed-by=regfish-api",
  "ttl": 300,
  "annotation": "managed-by=dns-desired-state-sync-example"
}
'

Schritt 4: Geänderte Records per RRID aktualisieren

Wenn ein Record bereits existiert, sich aber data, ttl oder ein anderer Wert geändert hat, aktualisieren Sie ihn per rrid. Damit vermeiden Sie Mehrdeutigkeiten bei mehrfach vorhandenen Kombinationen.

curl --request PATCH \
  --url 'https://api.regfish.com/dns/rr/101' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "A",
  "name": "api",
  "data": "203.0.113.20",
  "ttl": 300,
  "annotation": "synced-by-desired-state-job"
}
'

Schritt 5: Veraltete Records entfernen

Alles, was in der Zone noch vorhanden ist, aber nicht mehr im Sollzustand auftaucht, ist Drift und kann entfernt werden. Genau hier sollten Sie aber nur Records löschen, die auch wirklich von Ihrem Workflow verwaltet werden.

curl --request DELETE \
  --url 'https://api.regfish.com/dns/rr/103' \
  --header 'x-api-key: YOUR_API_KEY'

Praxishinweise für produktive Abläufe

Vergleichen Sie Records nicht nur nach name, sondern immer nach name und type
normalisieren Sie FQDNs und abschließende Punkte, bevor Sie vergleichen
trennen Sie manuell gepflegte Records und automatisiert verwaltete Records sauber über Konventionen oder Annotationen
führen Sie zuerst einen Dry-Run aus und loggen Sie geplante Änderungen, bevor Sie sie schreiben
behandeln Sie Deletes strenger als Creates und Updates, zum Beispiel über Allowlists

Ergebnis

Mit diesem Ablauf wird aus einzelnen DNS-Endpunkten ein idempotenter Sync-Workflow. Genau das brauchen Sie, um Drift zu reduzieren und Änderungen reproduzierbar aus Deployments oder Konfigurationsständen abzuleiten.