Dieses Rezept setzt einen definierten DNS-Sollzustand gegen eine bestehende Zone durch. Du liest zuerst den Ist-Zustand, vergleichst ihn mit deiner Zieldefinition und führst 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 du nicht nur name, type und data siehst, 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 erhältst du 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

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

[
  {
    "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://www.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, legst du 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, aktualisierst du ihn per rrid. Damit vermeidest du 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 solltest du aber nur Records löschen, die auch wirklich von deinem 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

• Vergleiche Records nicht nur nach name, sondern immer nach name und type
• normalisiere FQDNs und abschließende Punkte, bevor du vergleichst
• trenne manuell gepflegte Records und automatisiert verwaltete Records sauber über Konventionen oder Annotationen
• führe zuerst einen Dry-Run aus und logge geplante Änderungen, bevor du sie schreibst
• behandle 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 brauchst du, um Drift zu reduzieren und Änderungen reproduzierbar aus Deployments oder Konfigurationsständen abzuleiten.