UC-002: DNSControl Integration¶

Purpose¶

DNSControl is a declarative DNS configuration management tool that allows you to define DNS zones using code. By integrating DNSControl with your BIND DNS server setup, you can manage DNS records programmatically with version control, validation, and automated deployment capabilities.

Setup¶

Prerequisites¶

DNSControl 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 DNSControl using one of the following methods:

# Using Homebrew (macOS)
brew install dnscontrol

# Using Go
go install github.com/StackExchange/dnscontrol/v4@latest

# Using Docker
docker pull stackexchange/dnscontrol

Configuration¶

DNSControl Configuration File: Create a dnsconfig.js file to define your DNS zones and records.
Credentials Configuration: Set up creds.json to store authentication details for your BIND server.
TSIG Authentication: Use the TSIG keys generated by your env-manager.sh script for secure communication.

Example Configuration¶

dnsconfig.js¶

var REG_NONE = NewRegistrar("none");
var DSP_BIND = NewDnsProvider("bind", {
    "server": "127.0.0.1:53",
    "tsig_key_name": "external-dns-key",
    "tsig_key_algorithm": "hmac-sha256",
    "tsig_key_secret": "your-tsig-key-secret"
});

D("example.local", REG_NONE, DnsProvider(DSP_BIND),
    A("@", "192.168.1.100"),
    A("www", "192.168.1.100"),
    A("api", "192.168.1.101"),
    CNAME("mail", "www"),
    MX("@", 10, "mail.example.local."),
    TXT("@", "v=spf1 include:_spf.google.com ~all")
);

creds.json¶

{
    "bind": {
        "server": "127.0.0.1:53",
        "tsig_key_name": "external-dns-key",
        "tsig_key_algorithm": "hmac-sha256",
        "tsig_key_secret": "ENV:TSIG_KEY_SECRET"
    }
}

Security Considerations¶

TSIG Keys: Use the secure TSIG keys generated by env-manager.sh. Store the key secret as an environment variable.
Credentials File: Keep creds.json secure and never commit it to version control. Add it to .gitignore.
Access Control: Ensure only authorized systems can perform DNS updates.
Key Rotation: Regularly rotate TSIG keys using the env-manager.sh script.

Usage¶

Basic Operations¶

# Validate configuration
dnscontrol check

# Preview changes (dry run)
dnscontrol preview

# Apply changes to DNS server
dnscontrol push

Integration with Environment Management¶

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

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

# Apply DNS configuration
dnscontrol push

Automation and CI/CD¶

DNSControl integrates well with CI/CD pipelines:

Version Control: Store your dnsconfig.js in Git
Validation: Run dnscontrol check in CI
Preview: Use dnscontrol preview for pull request reviews
Deployment: Automate dnscontrol push for approved changes

Advanced Features¶

Multi-Provider Support: Manage multiple DNS providers from a single configuration
Record Validation: Built-in validation for DNS record syntax and conflicts
Diff Visualization: Clear visualization of changes before applying
Backup and Restore: Export existing DNS records for backup purposes

Best Practices¶

Infrastructure as Code: Treat DNS configuration as code with version control
Testing: Use dnscontrol preview before applying changes
Gradual Rollout: Test changes in development environments first
Documentation: Document DNS record purposes and dependencies
Monitoring: Monitor DNS changes and their effects on services

Troubleshooting¶

TSIG Authentication Errors: Verify TSIG key configuration matches between DNSControl and BIND
Connection Issues: Ensure your BIND server is accessible and DNS update port is open
Permission Errors: Check that TSIG key has appropriate permissions for zone updates

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