Domains & DNS

Domains, DNS zones (internal on PowerDNS or external via python-lexicon) and DNS records in the Polycrate API, including setup guides, API usage for self-service portals and the CentralNic domain registrar.

Domains & DNS

Overview

The Polycrate API manages Domains (business object), DNS zones (technical object) and DNS records. Zones can be operated in two modes: internal (hosted on our PowerDNS infrastructure) or external (management interface for zones at third-party providers such as Cloudflare, Hetzner, Route 53 etc.).

graph LR
    Domain[Domain<br/>Business level] -->|optionally linked| DNSZone[DNSZone]
    DNSZone -->|kind=internal| PDNS[PowerDNS<br/>operated by ayedo]
    DNSZone -->|kind=external| Lexicon[python-lexicon<br/>89 provider APIs]
    DNSZone --> DNSRecord[DNS Records]
    Domain --> Registrar[Domain Registrar<br/>CentralNic, among others]

Internal vs. External Zones

The kind of a DNS zone determines where the zone is technically operated and how the records are managed.

kind=internal — Hosted on ayedo PowerDNS

The zone runs on the PowerDNS infrastructure provided by ayedo.

• Records: Persisted in the Polycrate database and written synchronously to PowerDNS
• Nameservers: ayedo's PowerDNS nameservers (to be configured at the domain registrar)
• Zone lifecycle: provision() creates the zone in PowerDNS, deprovision() removes it
• Unique: Zone name must be unique system-wide
• Billing: Product DNS Zone (Internal) – flat rate per zone (including nameserver operation, monitoring, backup)

Recommended for customers who want to delegate DNS completely to ayedo.

kind=external — Management Interface for External Providers

The zone exists at a third-party provider (Cloudflare, Hetzner, Route 53, …). Polycrate provides the management UI, audit log, API access and credential management – but does not operate the nameservers.

• Records: Are not stored in the Polycrate DB. Reads/writes happen live at the provider via python-lexicon (89 supported providers)
• Nameservers: Provider nameservers (remain with the external provider)
• Zone lifecycle: Polycrate does not create the zone at the provider and does not delete it – it must already exist there
• Unique: Combination of (name, organization, provider) – an organization can have example.com registered at Cloudflare and at Hetzner
• Billing: Product DNS Zone (External) – flat rate per zone (management interface only)

Recommended for customers who want to keep DNS zones at third-party providers but use record management, change history and audit through Polycrate.

Comparison

Setting Up an Internal Zone

Prerequisites

1. PowerDNS deployment as a Polycrate block (e.g. with the powerdns block from PolyHub) in the management cluster
2. System Config → Integration → PowerDNS: endpoint and API key configured
3. Permissions: role with domains.add_dnszone

Step by Step

1. Networking → DNS Zones → New Zone
2. Fill in the fields:
   • Name: example.com (without leading dot)
   • Kind: internal
   • Organization: desired organization
3. Save – Polycrate creates the zone in PowerDNS (synchronously)
4. Create individual entries in the Records tab (A, AAAA, CNAME, TXT, MX, NS, …)
5. At the domain registrar, switch the nameservers to the ayedo PowerDNS nameservers (see System Config → Default Nameservers)

DNSSEC (kind=internal only)

Internal zones support full DNSSEC management via UI and API:

• Enable/disable DNSSEC (idempotent, reconciliation enforces the desired state in PowerDNS)
• Cryptokeys and DS records as metadata on the zone (DNSSEC tab)
• Subdomain zones with automatic NS/DS delegation into the parent zone
• Zone export (AXFR) / import as well as dedicated schemas for enable-dnssec and import-records

External zones (kind=external) have no DNSSEC management in Polycrate — that stays with the provider.

Primary Zone & Resolve

• DNSZone.primary_zone (default true) disambiguates multiple external provider zones with the same name per organization
• GET /api/v1/domains/dnszones/resolve/?fqdn= — longest suffix match: prefers kind=internal, otherwise the primary external zone
• Agent/workspace tokens receive permissions for DNS01 present/cleanup (dnszone read, dnsrecord CRUD)

Setting Up an External Zone

Prerequisites

1. Zone exists at the provider (e.g. example.com is set up and active at Cloudflare)
2. API credentials created at the provider (API token, possibly username)
3. Permissions: role with credentials.add_credential and domains.add_dnszone

Step 1: Create a dns-provider Credential

Credentials → New Credential

The fields api_key / api_user are stored encrypted and passed to Lexicon as auth_token / auth_username. Provider-specific extra parameters (e.g. OAuth refresh tokens, custom endpoints) are stored as key-value pairs in the Metadata field.

Step 2: Create the Zone

Networking → DNS Zones → New Zone

After saving:

• Polycrate does not create a zone at the provider – it must already exist there
• The Records tab shows the records live directly from the provider (every call is an API call to the provider)

Step 3: Manage Records

Create/update/delete in the Records tab are executed immediately at the provider via Lexicon. All record types supported by the provider are supported – with some providers TTL/priority is not editable (Lexicon limitation).

DNS Management via API (Customer Portal / Self-Service)

In addition to the web UI, DNS management can be fully controlled via the REST API – for example for a customer self-service portal that manages DNS zones and credentials on behalf of customers.

Provider Catalog

Before an external zone can be created, it must be known which providers are configured and which credential fields they require:

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

The list of permitted providers is configured under System Config → Integration → PowerDNS → Supported DNS Providers (comma-separated Lexicon slugs).

Creating a Credential via API

External zones require a dns-provider credential. It can be created without web UI access via a dedicated endpoint:

POST /api/v1/external-credentials/
Authorization: Bearer <system-api-key-or-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 (success)
# → 409 Conflict (credential is still used by zone(s))

Creating an External Zone via API

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

{
  "name": "example.com",
  "kind": "external",
  "provider": "cloudflare",
  "credential_id": "<uuid-of-the-credential>",
  "organization_id": "<uuid-of-the-organization>"
}

Zone and credential must belong to the same organization – otherwise 400 Bad Request.

Domain Registrar

CentralNic (RRPProxy)

CentralNic is the first supported domain registrar. Domains can be registered and managed via the Polycrate API:

• Registration: Create new domains directly
• Portfolio import: Import existing domains from the registrar account
• Status & management: View and edit expiry date, nameservers, contacts

Configuration under Administration → Domain Registrar or System Config → Integration.

Where to Find What

See Also

• Pricing & Business Layer – Zone products and billing
• Polycrate API Integrations – Configure PowerDNS and registrar
• Release 0.14.0 – Domains & DNS (foundation)
• Release 0.15.0 – external zones via Lexicon