DNS Management

FlatRun supports DNS management through an integrated PowerDNS server or via external DNS provider APIs for Cloudflare, Route53, DigitalOcean, and Hetzner.

DNS Options

Choose the DNS management approach that fits your setup:

PowerDNS Setup

PowerDNS is deployed as a Docker container and managed by FlatRun.

Agent Configuration

PowerDNS is configured under the infrastructure section:

infrastructure:
  powerdns:
    enabled: true
    container: powerdns
    image: powerdns/pdns-auth-48:latest
    api_port: 8081
    dns_port: 53
    api_key: your-api-key  # Auto-generated if empty
    data_path: ""
    default_soa: ""
    nameservers: ""

Enabling PowerDNS

curl -X POST "http://localhost:8090/api/dns/powerdns/enable" \
  -H "Authorization: Bearer $TOKEN"

This deploys the PowerDNS container with:

• Authoritative DNS server (port 53)
• REST API for zone management (port 8081)
• SQLite backend for zone storage

PowerDNS Status

curl "http://localhost:8090/api/dns/powerdns/status" \
  -H "Authorization: Bearer $TOKEN"

Managing DNS Zones

Creating a Zone

curl -X POST "http://localhost:8090/api/dns/powerdns/zones" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com.",
    "kind": "Master",
    "nameservers": [
      "ns1.example.com.",
      "ns2.example.com."
    ]
  }'

Listing Zones

curl "http://localhost:8090/api/dns/powerdns/zones" \
  -H "Authorization: Bearer $TOKEN"

Getting Zone Details

curl "http://localhost:8090/api/dns/powerdns/zones/example.com." \
  -H "Authorization: Bearer $TOKEN"

Deleting a Zone

curl -X DELETE "http://localhost:8090/api/dns/powerdns/zones/example.com." \
  -H "Authorization: Bearer $TOKEN"

Managing DNS Records

Add, modify, or delete DNS records within a zone using the PATCH endpoint with RRSets (Resource Record Sets).

Adding Records

curl -X PATCH "http://localhost:8090/api/dns/powerdns/zones/example.com." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rrsets": [
      {
        "name": "www.example.com.",
        "type": "A",
        "ttl": 3600,
        "changetype": "REPLACE",
        "records": [
          {"content": "192.168.1.100", "disabled": false}
        ]
      }
    ]
  }'

Supported Record Types

Deleting Records

curl -X PATCH "http://localhost:8090/api/dns/powerdns/zones/example.com." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rrsets": [
      {
        "name": "www.example.com.",
        "type": "A",
        "changetype": "DELETE"
      }
    ]
  }'

External DNS Providers

Available Providers

curl "http://localhost:8090/api/dns/providers" \
  -H "Authorization: Bearer $TOKEN"

Returns available providers and their configuration requirements.

Cloudflare Setup

Configure Cloudflare DNS in the agent config:

dns:
  enabled: true
  provider: cloudflare
  cloudflare:
    api_token: your-cloudflare-api-token
    zone_id: your-zone-id

Or store credentials via the credentials API:

curl -X POST "http://localhost:8090/api/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cloudflare-dns",
    "type": "dns-cloudflare",
    "credentials": {
      "api_token": "your-token",
      "zone_id": "your-zone-id"
    }
  }'

AWS Route53 Setup

dns:
  enabled: true
  provider: route53
  route53:
    access_key_id: AKIA...
    secret_access_key: ...
    hosted_zone_id: Z1234567890

DigitalOcean DNS Setup

dns:
  enabled: true
  provider: digitalocean
  digitalocean:
    api_token: your-do-token

Hetzner DNS Setup

dns:
  enabled: true
  provider: hetzner
  hetzner:
    api_token: your-hetzner-token

DNS for SSL Validation

DNS management integrates with SSL certificate provisioning for DNS-01 validation:

certbot:
  enabled: true
  dns_provider: cloudflare

dns:
  enabled: true
  provider: cloudflare
  cloudflare:
    api_token: your-token

When requesting a certificate with DNS-01 validation:

1. FlatRun creates a TXT record for the ACME challenge
2. Let's Encrypt verifies the record
3. Certificate is issued
4. TXT record is cleaned up

Automatic DNS Records

When DNS is configured and a deployment is assigned a domain, FlatRun can automatically create DNS records.

dns:
  enabled: true
  auto_records: true
  default_ip: 192.168.1.100

When you configure a proxy for blog.example.com, FlatRun automatically:

1. Creates an A record pointing to default_ip
2. Updates the record if the server IP changes
3. Removes the record when the proxy is deleted

PowerDNS Administration

Restart Service

curl -X POST "http://localhost:8090/api/dns/powerdns/restart" \
  -H "Authorization: Bearer $TOKEN"

Disable PowerDNS

curl -X POST "http://localhost:8090/api/dns/powerdns/disable" \
  -H "Authorization: Bearer $TOKEN"

Zone File Export

PowerDNS zones can be exported in standard BIND zone file format for backup or migration.

curl "http://localhost:8090/api/dns/powerdns/zones/example.com./export" \
  -H "Authorization: Bearer $TOKEN"

Best Practices

• Use appropriate TTLs — Lower TTLs (300-900) for frequently changing records
• Set up secondary DNS — Use multiple nameservers for redundancy
• Monitor propagation — Changes take time to propagate globally
• Secure API tokens — Store DNS provider credentials securely
• Test before production — Verify DNS changes in staging first