API v2: Zone Distribution Check

A year ago I started working on a system to check the distribution status of a particular zone or zone record in all our name servers.

The use case for this project was primarily an internal tool to check the health of a DNS zone. When a zone is modified (because you add a DNS record, for example), this tool will be used to check the zone at our name servers. If it detects a propagation issue, the system will automatically try to recover and force a re-sync.

We've been using this system in production for months. We love it, and we think you may love it too. That's why today we're announcing the ability to check for distribution of DNS zones using our API.

Customers with large amount of domains, such as resellers, can use this new feature to confirm that the DNS zone is fully delegated before linking customers to their new domain.

DNS propagation

Every time you modify a DNS record, it's propagated instantly in our 6 anycast regions across the globe. For each of our regions, we have multiple servers.

Distributing an update across several servers isn't easy. A variety of problems can arise along the path of these DNS records. A network problem or a malfunctioning server can compromise the final result.

Monitoring

If a DNS record isn't completely propagated in our servers, a domain may not respond properly to a user that tries to visit it. Monitoring is essential to diagnose any kind of problem both in hardware and software.

With this in mind, we designed an internal tool to check the health of a DNS zone. We started looking at DNS record changes events first. In case of error, after a DNS modification, we're alerted and we can fix it.

In the second stage, we promoted it to proactively monitor all the DNS zones that we host. This helped to spot a tiny percentage of old DNS zones with low-to-zero levels of changes with records that weren't completely propagated.

More recently, we used it to guarantee proper distribution of Let's Encrypt DNS verification records.

How to use it

Starting today, there will be two new endpoints to our API v2:

• checkZoneDistribution
• checkZoneRecordDistribution

The first one tells you about the overall state of your DNS zone.

Here it is in action:

$ curl -H 'Authorization: Bearer <token>' \
       -H 'Accept: application/json' \
       https://api.dnsimple.com/v2/1010/zones/example.com/distribution

It returns a simple payload:

{
  "data": {
    "distributed": true
  }
}

The second endpoint is similar, but targets a single DNS record:

$ curl -H 'Authorization: Bearer <token>' \
       -H 'Accept: application/json' \
       https://api.dnsimple.com/v2/1010/zones/example.com/records/5/distribution

The output format is identical between the two endpoints.

For a detailed, technical explanation, please read our documentation.

One last thing

We released our official API clients to support this new feature for Ruby, Go, Node.js, and Elixir.

From now on, you'll be able to reliably monitor your DNS automation.

Share on Twitter and Facebook

Luca Guidi

Former astronaut, soccer player, superhero. All at the age of 10. For some reason now I write code.