This page covers octoDNS configuration using YAML files. octoDNS uses a source → target model where DNS records are defined in sources (YAML files, APIs) and synced to targets (DNS providers).
octoDNS uses two types of configuration files:
config.yaml) - Defines providers and zonesexample.com.yaml) - Defines DNS records per zoneExample: config/production.yaml
---
# Providers define where DNS records come from (sources) and go to (targets)
providers:
# YAML file provider - reads zone files from directory
config:
class: octodns.provider.yaml.YamlProvider
directory: ./config/zones
default_ttl: 3600
enforce_order: true
populate_should_exist: false
# AWS Route53 provider
route53:
class: octodns_route53.Route53Provider
access_key_id: env/AWS_ACCESS_KEY_ID
secret_access_key: env/AWS_SECRET_ACCESS_KEY
max_changes: 32
# Cloudflare provider
cloudflare:
class: octodns_cloudflare.CloudflareProvider
token: env/CLOUDFLARE_TOKEN
# BIND zone file provider (for self-hosted DNS)
bind:
class: octodns_bind.BindProvider
directory: ./config/zones/bind
# Zones define which DNS zones to manage
zones:
example.com.:
sources:
- config
targets:
- route53
example.net.:
sources:
- config
targets:
- cloudflare
# Dynamic zone - sync all zones from source
'*':
sources:
- config
targets:
- route53
- cloudflare
Example: config/zones/example.com.yaml
---
# Root domain A records
'':
ttl: 3600
type: A
values:
- 192.0.2.1
- 192.0.2.2
# WWW subdomain (CNAME)
www:
ttl: 3600
type: CNAME
value: example.com.
# Mail server (MX)
'@':
ttl: 3600
type: MX
values:
- exchange: mail1.example.com.
preference: 10
- exchange: mail2.example.com.
preference: 20
# SPF record (TXT)
'@':
ttl: 3600
type: TXT
values:
- 'v=spf1 mx -all'
# DKIM record (TXT)
mail._domainkey:
ttl: 3600
type: TXT
value: 'v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ...'
# DMARC record (TXT)
_dmarc:
ttl: 3600
type: TXT
value: 'v=DMARC1; p=reject; rua=mailto:dmarc@example.com'
# NS records
'@':
ttl: 3600
type: NS
values:
- ns1.example.com.
- ns2.example.com.
# CAA records (Certificate Authority Authorization)
'@':
ttl: 3600
type: CAA
values:
- flags: 0
tag: issue
value: 'letsencrypt.org'
- flags: 0
tag: issuewild
value: 'letsencrypt.org'
# SRV records
_sip._tcp:
ttl: 3600
type: SRV
values:
- priority: 10
weight: 60
port: 5060
target: sip1.example.com.
- priority: 20
weight: 40
port: 5060
target: sip2.example.com.
# PTR record (reverse DNS)
1:
ttl: 3600
type: PTR
values:
- host1.example.com.
providers:
route53:
class: octodns_route53.Route53Provider
access_key_id: env/AWS_ACCESS_KEY_ID
secret_access_key: env/AWS_SECRET_ACCESS_KEY
max_changes: 32
providers:
cloudflare:
class: octodns_cloudflare.CloudflareProvider
token: env/CLOUDFLARE_TOKEN
# Optional: Account ID for multi-account setups
# account_id: env/CLOUDFLARE_ACCOUNT_ID
providers:
googlecloud:
class: octodns_googlecloud.GoogleCloudProvider
# Service account key file
key_file: /path/to/service-account.json
# Or use application default credentials
# project: my-gcp-project
providers:
bind:
class: octodns_bind.BindProvider
directory: ./zones
providers:
powerdns:
class: octodns_powerdns.PowerDnsProvider
host: pdns.example.com
api_key: env/POWERDNS_API_KEY
# scheme: https
# port: 443
providers:
knotdns:
class: octodns_knotdns.KnotDnsProvider
host: knot.example.com
api_key: env/KNOT_API_KEY
Use env/VARIABLE_NAME syntax to reference environment variables:
providers:
route53:
class: octodns_route53.Route53Provider
access_key_id: env/AWS_ACCESS_KEY_ID
secret_access_key: env/AWS_SECRET_ACCESS_KEY
Set environment variables before running octoDNS:
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
octodns-sync --config-file=config/production.yaml
| Type | Description | Example |
|---|---|---|
A |
IPv4 address | 192.0.2.1 |
AAAA |
IPv6 address | 2001:db8::1 |
CNAME |
Canonical name (alias) | example.com. |
MX |
Mail exchange | mail.example.com. (priority 10) |
NS |
Name server | ns1.example.com. |
TXT |
Text record (SPF, DKIM, DMARC) | 'v=spf1 mx -all' |
PTR |
Pointer (reverse DNS) | host.example.com. |
SRV |
Service record | Priority, weight, port, target |
CAA |
Certificate Authority Authorization | issue: letsencrypt.org |
ALIAS |
Alias record (provider-specific) | example.com. |
Validate configuration before applying:
# Validate configuration syntax
octodns-validate --config-file=config/production.yaml
# Dry-run sync (shows planned changes)
octodns-sync --config-file=config/production.yaml
# Apply changes
octodns-sync --config-file=config/production.yaml --doit
octodns-sync without --doit first'*' pattern for auto-discoveryenforce_order: true - Ensures consistent record orderingoctodns-dump