DNS as Configuration / Code with DNSControl

Managing DNS for a domain name traditionally involves visiting the control panel of your DNS authoritative server providers to create, modify or delete the related records there. But I recently discovered a new project, DNS Control by Stack Overflow, which allows one to manage DNS records by modifying JavaScript configuration files, similar to the ways Kubernetes and Ansible work in.

Why did I switch?

In my experience, the main advantages of DNSControl, or rather the workflow it promotes, are the following:

• Support for different authoritative DNS providers: It is no longer needed to visit the control panels of different providers. The configuration is provider-agnostic, and can be applied to different or even multiple DNS providers, which allows administrators to easily migrate between providers or mix and use servers from different providers simultaneously.
• Specify the state instead of actions: This is analogous of managing infrastructure using Ansible vs manually. Only the final state is specified in the configuration file, and the software takes care of adding or modifying records and deleting unnecessary ones.
• Use script to simplify records description: A basic version of JavaScript can be used in describing the DNS records, which can reduce repetition and ease the complexity of modifications. For example, variables (or constants) and functions can be used to generate similar DNS records in batch.

I will briefly introduce my new workflow for migrating and managing DNS below, in order to show you how it can be done.

Migrating existent zones

The first step of switching to the new workflow, is to export and migrate the existent DNS zones from the current providers into the configuration file.

If you are like me who have dozens of records in the old DNS control panel, and you simply don’t want to copy-paste everything by hand, DNSControl has a “get-zones” sub-command that can be used in this situation. You can read the official documentation about migration, and the steps I used are:

1. In order to read from the current provider, credentials must be generated and provided in the creds.json file. The methods vary by provider, which can be found in their respective pages. For example, CloudFlare only requires an API token with sufficient permissions to access and modify zone records.
2. With creds.json filled out and saved to the current directory, the following command can be executed to export current records of a specific zone:
   dnscontrol get-zones --format=js --out=dnsconfig.js <creds-name> <PROVIDER-IDENTIFIER> your-domain.tld
   1. The software is written in Go, so they provide static binaries in GitHub release page.
   2. creds-name is the key used in creds.json, and PROVIDER-IDENTIFIER can be found in the “Identifier” column in the provider table.
3. Now dnsconfig.js should contain all your existent records, and you can optimize the script using JavaScript variables and functions. Note that they use a simple JavaScript interpreter, so please only use the simplest features of the language. (You will know what not to use in the testing steps below.)

Updating DNS records

In order to create or update DNS records for a domain, one should first edit dnsconfig.js by modifying the arguments or variables (if created in the previous part) that belongs to the domain in question. Then, in order to make sure that the JavaScript syntax is correct and all the changes are indeed desired, use the preview sub-command to compare the changes to the existent records online. Finally, when everything checks out, use dnscontrol push to apply the changes.

To further automate the workflow, I personally use a Git repository to version-control my dnsconfig.js configuration, and Jenkins to perform the steps above. My creds.json is kept private in Jenkins’ “Credentials” area, and mounted into the pipeline environment during execution. In this way, I can commit and push my DNS configuration to the Git server, and Jenkins will automatically check and apply the changes.

Supported providers

As of the time of writing this article, the following DNS providers are supported by DNSControl:

• ActiveDirectory_PS
• AXFRDDNS
• Azure DNS
• BIND
• Cloudflare
• ClouDNS
• deSEC
• DigitalOcean
• DNSimple
• Gandi_v5
• Google Cloud DNS
• Hurricane Electric DNS
• Hetzner DNS Console
• HEXONET
• INWX
• Linode
• Microsoft DNS Server (Windows Server)
• Name.com
• Namecheap Provider
• Netcup
• NS1
• Oracle Cloud
• Ovh
• PowerDNS
• Route 53
• SoftLayer DNS
• Vultr

In addition, the following registrars are supported, which allow users to modify the domains’ NS records to point to the providers above:

• CSC Global
• DNSimple
• DNS-over-HTTPS
• Gandi_v5
• HEXONET
• Internet.bs
• INWX
• Name.com
• Namecheap Provider
• OpenSRS
• Ovh
• Route 53

And even if your current provider is not covered, you can easily add your own integration and possibly contribute to the upstream.