Zum Inhalt

Domains & DNS

Übersicht

Die Polycrate API verwaltet Domains (Business-Objekt), DNS-Zonen (technisches Objekt) und DNS-Records. Zonen können in zwei Betriebsmodi geführt werden: internal (Betrieb auf unserer PowerDNS-Infrastruktur) oder external (Management-Interface für Zonen bei Drittanbietern wie Cloudflare, Hetzner, Route 53 etc.).

graph LR
    Domain[Domain<br/>Business-Ebene] -->|optional verknüpft| DNSZone[DNSZone]
    DNSZone -->|kind=internal| PDNS[PowerDNS<br/>Betrieb durch ayedo]
    DNSZone -->|kind=external| Lexicon[python-lexicon<br/>89 Provider-APIs]
    DNSZone --> DNSRecord[DNS Records]
    Domain --> Registrar[Domain Registrar<br/>CentralNic, u.a.]
Konzept Beschreibung
Domain Domain-Name, den eine Organisation besitzt oder verwaltet (z. B. example.com) – inkl. Registrar-Status
DNS Zone Technische DNS-Zone mit kind=internal (PowerDNS) oder kind=external (externer Provider)
DNS Record Einzelner Eintrag (A, AAAA, CNAME, TXT, MX, NS, SOA, …) innerhalb einer Zone

Internal vs. External Zonen

Der kind einer DNS-Zone bestimmt, wo die Zone technisch betrieben und wie die Records verwaltet werden.

kind=internal — Betrieb auf ayedo-PowerDNS

Die Zone läuft auf der von ayedo bereitgestellten PowerDNS-Infrastruktur.

  • Records: Werden in der Polycrate-Datenbank persistiert und synchron zu PowerDNS geschrieben
  • Nameserver: PowerDNS-Nameserver von ayedo (bei Domain-Registrar hinterlegen)
  • Zone-Lifecycle: provision() legt die Zone in PowerDNS an, deprovision() entfernt sie
  • Unique: Zone-Name muss systemweit eindeutig sein
  • Abrechnung: Produkt DNS Zone (Internal) – Flat-Rate pro Zone (inkl. Nameserver-Betrieb, Monitoring, Backup)

Empfohlen für Kunden, die DNS komplett an ayedo delegieren wollen.

kind=external — Management-Interface für externe Provider

Die Zone existiert bei einem Drittanbieter (Cloudflare, Hetzner, Route 53, …). Polycrate stellt Management-UI, Audit-Log, API-Zugriff und Credential-Management bereit – betreibt aber nicht die Nameserver.

  • Records: Werden nicht in der Polycrate-DB gespeichert. Lesen/Schreiben erfolgt live beim Provider über python-lexicon (89 unterstützte Provider)
  • Nameserver: Provider-Nameserver (bleiben beim externen Anbieter)
  • Zone-Lifecycle: Polycrate legt die Zone nicht beim Provider an und löscht sie nicht – sie muss dort bereits existieren
  • Unique: Kombination aus (name, organization, provider) – eine Organisation kann example.com bei Cloudflare und bei Hetzner registriert haben
  • Abrechnung: Produkt DNS Zone (External) – Flat-Rate pro Zone (nur Management-Interface)

Empfohlen für Kunden, die DNS-Zonen bei Drittanbietern behalten möchten, aber Record-Management, Änderungshistorie und Audit durch Polycrate nutzen wollen.

Vergleich

Eigenschaft kind=internal kind=external
Nameserver-Betrieb ayedo (PowerDNS) Drittanbieter
Record-Storage Polycrate-DB + PowerDNS Nur Drittanbieter (live abgerufen)
Zone anlegen Automatisch bei Provision Muss beim Provider existieren
Zone löschen Automatisch bei Deprovision Nie durch Polycrate
Unique Constraint Name systemweit Name pro Organization + Provider
Credentials nötig Nein Ja (kind=dns-provider Credential)
Record-Änderung Sofort in DB + PowerDNS Direkt beim Provider via Lexicon
Abrechnung DNS Zone (Internal) Product DNS Zone (External) Product

Internal Zone einrichten

Voraussetzungen

  1. PowerDNS-Deployment als Polycrate Block (z. B. mit dem powerdns-Block aus PolyHub) im Management-Cluster
  2. System Config → Integration → PowerDNS: Endpoint und API-Key hinterlegt
  3. Rechte: Rolle mit domains.add_dnszone

Schritt für Schritt

  1. Networking → DNS-Zonen → New Zone
  2. Felder ausfüllen:
    • Name: example.com (ohne führenden Punkt)
    • Kind: internal
    • Organization: gewünschte Organisation
  3. Speichern – Polycrate legt die Zone in PowerDNS an (synchron)
  4. Im Tab Records einzelne Einträge anlegen (A, AAAA, CNAME, TXT, MX, NS, …)
  5. Beim Domain-Registrar die Nameserver auf die ayedo-PowerDNS-Nameserver umstellen (siehe System Config → Default Nameservers)

Propagation

Record-Änderungen sind synchron – sobald die UI Erfolg meldet, ist der Record in PowerDNS aktiv. Die externe DNS-Propagation hängt von TTL und Caching der auflösenden Resolver ab.

External Zone einrichten

Voraussetzungen

  1. Zone existiert beim Provider (z. B. example.com ist bei Cloudflare eingerichtet und aktiv)
  2. API-Credentials beim Provider erzeugt (API-Token, ggf. Username)
  3. Rechte: Rolle mit credentials.add_credential und domains.add_dnszone

Schritt 1: dns-provider Credential anlegen

Credentials → New Credential

Feld Beispiel (Cloudflare) Beispiel (Hetzner)
Kind dns-provider dns-provider
Name cloudflare-main hetzner-dns
API Key Cloudflare API-Token Hetzner DNS-API-Token
API User Email-Adresse (falls Global API Key) –
Metadata provider-spezifische Parameter (z. B. zone_id, Custom-Endpoints) –

Die Felder api_key / api_user werden verschlüsselt gespeichert und an Lexicon als auth_token / auth_username durchgereicht. Provider-spezifische Extra-Parameter (z. B. OAuth-Refresh-Tokens, Custom-Endpoints) werden als Key-Value-Paare im Metadata-Feld abgelegt.

Welche Auth-Parameter braucht mein Provider?

Jeder Provider hat ein eigenes Auth-Schema. Die Lexicon-Dokumentation listet pro Provider die benötigten Felder: dns-lexicon Provider Configuration

Schritt 2: Zone anlegen

Networking → DNS-Zonen → New Zone

Feld Wert
Name example.com
Kind external
Provider Name des Lexicon-Providers, z. B. cloudflare, hetzner, route53
Credential das eben angelegte dns-provider Credential
Organization gewünschte Organisation

Nach dem Speichern:

  • Polycrate legt keine Zone beim Provider an – sie muss dort schon existieren
  • Das Records-Tab zeigt live die Records direkt vom Provider (jeder Aufruf ist ein API-Call zum Provider)

Schritt 3: Records verwalten

Create/Update/Delete im Records-Tab werden sofort via Lexicon beim Provider ausgeführt. Unterstützt werden alle Record-Typen, die der Provider unterstützt – bei manchen Providern ist TTL/Priority nicht editierbar (Lexicon-Einschränkung).

Einschränkungen bei externen Zonen

  • Zone selbst kann nicht aus Polycrate angelegt oder gelöscht werden
  • TTL-Support ist provider-abhängig
  • MX/SRV-Priority wird unterschiedlich behandelt
  • Keine Batch-Operationen (jede Änderung ein API-Call)

Domain Registrar

CentralNic (RRPProxy)

CentralNic ist der erste unterstützte Domain-Registrar. Domains können über die Polycrate API registriert und verwaltet werden:

  • Registrierung: Neue Domains direkt anlegen
  • Portfolio-Import: Bestehende Domains aus dem Registrar-Konto importieren
  • Status & Verwaltung: Ablaufdatum, Nameserver, Kontakte einsehen und bearbeiten

Weitere Registrar-Anbindungen

Weitere Domain-Registrare sind in Arbeit und werden schrittweise ergänzt.

Konfiguration unter Administration → Domain Registrar bzw. System Config → Integration.

Wo finden Sie was?

Aufgabe Ort in der Web-UI
Domains verwalten Networking → Domains
DNS-Zonen (internal + external) Networking → DNS-Zonen
Records in einer Zone Zone öffnen → Records-Tab
dns-provider Credentials Credentials → Kind dns-provider
PowerDNS-Integration System Config → Integration
Default Nameservers System Config → Integration → DNS
Default Zone-Produkte System Config → Default Products
Domain-Registrar Administration → Domain Registrar

Siehe auch