Octodns

Manage DNS zones across multiple providers using octoDNS ("DNS as code"). Use when you need to (1) manage DNS records in YAML format, (2) sync DNS zones between providers, (3) deploy DNS changes with version control, (4) bulk-update DNS records, or (5) migrate zones between DNS providers. Supports easyDNS, Route53, Cloudflare, NS1, and 50+ other DNS providers.

octoDNS - DNS as Code

Manage DNS zones declaratively across multiple providers using octoDNS. Think of it as "infrastructure as code" but for DNS records.

⚠️ CRITICAL SAFETY WARNING

octoDNS operates on "desired state" - the YAML file represents the ENTIRE zone.

If the zone file has 1 record but DNS has 50 records, octoDNS will DELETE 49 records.

MANDATORY SAFETY WORKFLOW:

1. For existing zones: ALWAYS dump first (scripts/dump.sh)
2. ALWAYS preview before applying (run without --doit)
3. REVIEW the diff carefully - unexpected "Delete" lines = DANGER
4. Never assume - verify the preview matches your intent

Quick Start

1. Install octoDNS

bash

scripts/install.sh

This installs octoDNS core plus the easyDNS provider.

2. Dump existing zone (REQUIRED for existing zones)

If managing an existing zone with records already in DNS:

bash

scripts/dump.sh example.com.

This creates config/example.com.yaml with ALL current records. Skipping this step will delete existing records!

3. Create a config file

bash

scripts/init_config.sh example.com

Creates config/production.yaml with easyDNS provider configured.

4. Define your zone

Create config/example.com.yaml:

yaml

---
# Root record (@)
'':
  ttl: 300
  type: A
  value: 192.0.2.1

# www subdomain
www:
  ttl: 300
  type: CNAME
  value: example.com.

# Mail records
'':
  ttl: 300
  type: MX
  values:
    - priority: 10
      value: mail.example.com.

5. Preview changes (MANDATORY)

Always preview first - look for unexpected Delete lines:

bash

scripts/sync.sh

(Note: dry-run is the default - no flag needed)

6. Apply changes (only when safe)

bash

scripts/sync.sh --doit

Common Operations

Sync local YAML to DNS provider

bash

scripts/sync.sh --zone example.com --doit

Dump existing zone to YAML

bash

scripts/dump.sh example.com

Creates config/example.com.yaml from live DNS.

Validate zone file syntax

bash

scripts/validate.sh config/example.com.yaml

Sync between two providers

bash

scripts/sync_providers.sh route53 easydns example.com

Configuration

Provider Setup

Edit config/production.yaml:

yaml

providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config
  
  easydns:
    class: octodns_easydns.EasyDnsProvider
    token: env/EASYDNS_TOKEN
    api_key: env/EASYDNS_API_KEY
    portfolio: env/EASYDNS_PORTFOLIO

zones:
  example.com:
    sources:
      - config
    targets:
      - easydns

Environment Variables

Set these for easyDNS:

bash

export EASYDNS_TOKEN="your-api-token"
export EASYDNS_API_KEY="your-api-key"
export EASYDNS_PORTFOLIO="your-portfolio-id"

Supported Record Types

easyDNS provider supports:

• A, AAAA
• CNAME
• MX
• TXT
• NS
• SRV
• CAA
• NAPTR
• DS

Advanced Usage

Multiple Zones

Use dynamic zone config to manage all zones in a directory:

yaml

zones:
  '*':
    sources:
      - config
    targets:
      - easydns

Any .yaml file in config/ becomes a zone.

Provider-to-Provider Migration

See references/migration.md for migrating zones between DNS providers.

Dynamic DNS Updates

See references/dynamic-dns.md for automated DNS updates from scripts.

Workflow

1. Create/edit zone files in config/
2. Run scripts/sync.sh --noop to preview
3. Review changes
4. Run scripts/sync.sh --doit to apply
5. Commit zone files to git

Troubleshooting

"Provider not found": Install provider package:

bash

pip install octodns-easydns

"Authentication failed": Check environment variables are set correctly.

"Zone not found": Ensure zone exists in DNS provider first, or use --force to create.

Documentation

• octoDNS docs: https://octodns.readthedocs.io/
• easyDNS provider: https://github.com/octodns/octodns-easydns
• Record format guide: references/records.md