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.]

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¶

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)

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

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.

Schritt 2: Zone anlegen¶

Networking → DNS-Zonen → New Zone

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).

DNS-Verwaltung via API (Customer Portal / Self-Service)¶

Neben der Web-UI kann die DNS-Verwaltung vollständig über die REST API gesteuert werden – etwa für ein Customer Self-Service Portal, das im Namen von Kunden DNS-Zonen und Credentials verwaltet.

Provider Catalog¶

Bevor eine externe Zone angelegt werden kann, muss bekannt sein, welche Provider konfiguriert sind und welche Credential-Felder sie benötigen:

GET /api/v1/dns/providers/
Authorization: Bearer <system-api-key>

Response:

{
  "providers": [
    {
      "slug": "cloudflare",
      "label": "Cloudflare",
      "credential_schema": {
        "api_key": {
          "label": "API Token (Bearer)",
          "required": true,
          "sensitive": true,
          "help": "Cloudflare API Token mit Zone:Read und DNS:Edit Rechten."
        },
        "api_user": {
          "label": "Account Email (nur Legacy API Key)",
          "required": false
        }
      }
    }
  ]
}

Die Liste der erlaubten Provider wird unter System Config → Integration → PowerDNS → Supported DNS Providers konfiguriert (komma-getrennte Lexicon-Slugs).

Credential via API anlegen¶

Für externe Zonen wird ein dns-provider Credential benötigt. Dieses kann ohne Web-UI-Zugriff über einen dedizierten Endpoint angelegt werden:

POST /api/v1/external-credentials/
Authorization: Bearer <system-api-key-oder-org-api-key>

{
  "name": "cloudflare-acme",
  "kind": "dns-provider",
  "organization_id": "11111111-2222-3333-4444-555555555555",
  "api_key": "<cloudflare-api-token>",
  "metadata": {
    "dns_provider": "cloudflare"
  }
}

DELETE /api/v1/external-credentials/{credential-id}/
# → 204 No Content (Erfolg)
# → 409 Conflict (Credential wird noch von Zone(n) verwendet)

Externe Zone via API anlegen¶

POST /api/v1/domains/dnszones/
Authorization: Bearer <api-key>

{
  "name": "example.com",
  "kind": "external",
  "provider": "cloudflare",
  "credential_id": "<uuid-des-credentials>",
  "organization_id": "<uuid-der-organisation>"
}

Zone und Credential müssen zur selben Organisation gehören – sonst 400 Bad Request.

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

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

Wo finden Sie was?¶

Siehe auch¶

• Pricing & Business Layer – Zone-Produkte und Abrechnung
• Polycrate API Integrationen – PowerDNS und Registrar konfigurieren
• Release 0.14.0 – Domains & DNS (Grundlage)
• Release 0.15.0 – externe Zonen via Lexicon