UC-003: octoDNS Integration¶

Purpose¶

octoDNS is a DNS-as-code tool that provides a unified interface for managing DNS records across multiple providers. By integrating octoDNS with your BIND DNS server setup, you can manage your DNS infrastructure declaratively with support for validation, synchronization, and multi-provider configurations.

Setup¶

Prerequisites¶

Python 3.6+ installed on your system
Your BIND DNS server running via Docker Compose
TSIG keys configured for secure DNS updates
Access to your DNS zone configuration

Installation¶

Install octoDNS using pip:

# Create a virtual environment (recommended)
python3 -m venv octodns-env
source octodns-env/bin/activate

# Install octoDNS with BIND provider support
pip install octodns[bind]

# Or install from source for latest features
pip install git+https://github.com/octodns/octodns.git

Configuration¶

octoDNS Configuration File: Create a config.yaml file to define providers and zones.
Zone Files: Create YAML zone files defining your DNS records.
TSIG Authentication: Configure TSIG keys generated by your env-manager.sh script.

Example Configuration¶

config.yaml¶

---
providers:
  bind:
    class: octodns_bind.BindProvider
    host: 127.0.0.1
    port: 53
    key_name: external-dns-key
    key_algorithm: HMAC-SHA256
    key_secret: env/TSIG_KEY_SECRET

zones:
  example.local.:
    sources:
      - bind
    targets:
      - bind

Zone File (example.local.yaml)¶

---
'':
  - type: A
    value: 192.168.1.100
  - type: MX
    value:
      exchange: mail.example.local.
      preference: 10
  - type: TXT
    value: "v=spf1 include:_spf.google.com ~all"

www:
  - type: A
    value: 192.168.1.100

api:
  - type: A
    value: 192.168.1.101

mail:
  - type: CNAME
    value: www.example.local.

_dmarc:
  - type: TXT
    value: "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.local"

db:
  - type: A
    value: 192.168.1.102
  - type: AAAA
    value: "2001:db8::102"

Security Considerations¶

TSIG Keys: Use the secure TSIG keys generated by env-manager.sh. Store secrets as environment variables.
Configuration Files: Keep sensitive configuration secure and use environment variables for secrets.
Access Control: Ensure only authorized systems can perform DNS updates.
Validation: Use octoDNS validation features to prevent configuration errors.

Usage¶

Basic Operations¶

# Validate configuration and zone files
octodns-validate --config-file config.yaml

# Plan changes (dry run)
octodns-sync --config-file config.yaml --plan

# Apply changes to DNS server
octodns-sync --config-file config.yaml

# Sync specific zone only
octodns-sync --config-file config.yaml example.local.

Integration with Environment Management¶

# Generate new TSIG key using env-manager.sh
./env-manager.sh generate-keys

# Export TSIG key for octoDNS
export TSIG_KEY_SECRET=$(grep EXTERNAL_DNS_TSIG_KEY_SECRET .env | cut -d'=' -f2)

# Validate and sync DNS configuration
octodns-validate --config-file config.yaml
octodns-sync --config-file config.yaml --plan
octodns-sync --config-file config.yaml

Advanced Configuration¶

Multi-Environment Setup¶

---
providers:
  bind-dev:
    class: octodns_bind.BindProvider
    host: 127.0.0.1
    port: 5353
    key_name: dev-dns-key
    key_secret: env/DEV_TSIG_KEY_SECRET

  bind-prod:
    class: octodns_bind.BindProvider
    host: prod-dns.example.local
    port: 53
    key_name: prod-dns-key
    key_secret: env/PROD_TSIG_KEY_SECRET

zones:
  example.local.:
    sources:
      - bind-dev
    targets:
      - bind-prod

Lenient Mode for Existing Zones¶

---
providers:
  bind:
    class: octodns_bind.BindProvider
    host: 127.0.0.1
    port: 53
    key_name: external-dns-key
    key_secret: env/TSIG_KEY_SECRET
    lenient: true  # Don't fail on unknown record types

zones:
  example.local.:
    lenient: true
    sources:
      - bind
    targets:
      - bind

Advanced Features¶

Record Validation: Built-in validation for DNS record syntax and dependencies
Multi-Provider Sync: Synchronize DNS records between different providers
Selective Updates: Apply changes to specific zones or record types
Backup and Restore: Export existing DNS records for backup purposes
Health Checks: Validate DNS resolution after changes

Automation and CI/CD¶

octoDNS integrates well with CI/CD pipelines:

# GitHub Actions example
name: DNS Sync
on:
  push:
    branches: [main]
    paths: ['dns/**']

jobs:
  dns-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install octoDNS
        run: pip install octodns[bind]
      - name: Validate DNS config
        run: octodns-validate --config-file dns/config.yaml
      - name: Plan DNS changes
        run: octodns-sync --config-file dns/config.yaml --plan
      - name: Apply DNS changes
        run: octodns-sync --config-file dns/config.yaml
        env:
          TSIG_KEY_SECRET: ${{ secrets.TSIG_KEY_SECRET }}

Best Practices¶

Version Control: Store configuration and zone files in Git
Environment Separation: Use different configurations for dev/staging/production
Validation First: Always validate and plan before applying changes
Incremental Changes: Make small, incremental changes and test thoroughly
Monitoring: Monitor DNS changes and their effects on services
Documentation: Document DNS record purposes and dependencies

Troubleshooting¶

Common Issues¶

TSIG Authentication Errors:

# Verify TSIG key configuration
dig @127.0.0.1 -y hmac-sha256:external-dns-key:$TSIG_KEY_SECRET example.local SOA

Connection Issues:

# Test DNS server connectivity
nslookup example.local 127.0.0.1

Configuration Validation:

# Debug configuration issues
octodns-validate --config-file config.yaml --debug

Logging and Debugging¶

Enable detailed logging for troubleshooting:

---
logging:
  version: 1
  formatters:
    standard:
      format: '%(asctime)s %(levelname)s %(name)s %(message)s'
  handlers:
    default:
      class: logging.StreamHandler
      level: DEBUG
      formatter: standard
  loggers:
    octodns:
      handlers: [default]
      level: DEBUG
  root:
    level: INFO
    handlers: [default]

Performance Optimization¶

Batch Updates: Group related changes to minimize DNS update operations
Zone Transfers: Use zone transfers for large zone synchronization
Caching: Leverage octoDNS caching for improved performance
Parallel Processing: Configure parallel processing for multiple zones

For detailed configuration options and troubleshooting, refer to the octoDNS documentation and your existing environment management scripts.