Search... ⌘ K
Get Started Contact Sales

How to Use CoreDNS as an Integrated DNS Provider

Table of Contents

This tutorial sets up CoreDNS to serve a DNSimple zone from your own network. You will connect CoreDNS to your DNSimple account, add one zone to it, run CoreDNS with the DNSimple plugin, and confirm that it answers with the records from DNSimple. CoreDNS loads the zone from DNSimple and reloads it on a fixed interval, so you keep editing records in DNSimple.

You can follow along with the video below.

Note

The video uses an Integrations link in the domain menu that is no longer there. Follow the steps below, which use the DNS Zone Providers card on the domain’s DNS page instead.

Before starting

You need:

  • Full Access to the DNSimple account that has the zone
  • An API access token for that account. CoreDNS reads the zone’s records and reports its sync status back to DNSimple, so a scoped token needs set to Read-only and set to Full access
  • A computer or server where you can run CoreDNS, and the dig command to test it

Connect CoreDNS to your DNSimple account

To connect CoreDNS
  1. If you have more than one account, select the relevant one from the account switcher at the top-right corner of the screen.
  2. From the account switcher, click , then click the tab.
  3. Under , click next to CoreDNS.
  4. In the dialog, click .

DNSimple takes you to the list and shows “The integrated provider has been linked to the account.” CoreDNS is now listed under on the Integrated Providers tab. The nickname is always CoreDNS, and an account has one CoreDNS connection.

Add a zone to CoreDNS

To add a zone to CoreDNS
  1. From the list, click the domain you want CoreDNS to serve.
  2. Click the tab on the left side.
  3. In the card, under , click next to CoreDNS.
  4. In the dialog, keep CoreDNS selected and click .
  5. On the page, enter a . This is a name you choose for your CoreDNS server or group of servers, such as office-dns. DNSimple uses it to show which records the cluster has loaded.
  6. Copy the example Corefile on the page. It already contains your zone name and account ID.
  7. Click .

DNSimple shows “Your zone integration has been created.” The DNS Zone Providers card now lists CoreDNS under .

Get CoreDNS with the DNSimple plugin

CoreDNS needs the coredns-dnsimple plugin compiled in. Use one of these:

  • Precompiled binary. Download the archive for your system from the releases page and extract it. The archive contains a coredns binary.
  • Docker image. Pull dnsimple/coredns from Docker Hub.
  • Your own build. Follow the compile instructions on the page or in the plugin’s README.

To confirm a binary includes the plugin, run:

./coredns -plugins | grep dnsimple

The output includes dnsimple.

Write the Corefile

Create a file named Corefile next to the binary, using the example you copied. Replace CLUSTER_IDENTIFIER with the identifier you entered in DNSimple:

.:53 {
  dnsimple example.com {
    account_id   1010
    identifier   office-dns
  }
}
  • account_id is the ID of the DNSimple account that has the zone.
  • identifier must match the you entered. CoreDNS uses it when it reports which records it has loaded. If you leave it out, CoreDNS reports as default, and DNSimple does not show the status for your cluster.
  • refresh is optional. It sets how often CoreDNS reloads the zone from DNSimple, and the default is 1m (1 minute).

To serve more than one zone, list them on the same line: dnsimple example.com example.net. Each zone also has to be added to CoreDNS in DNSimple, as in Add a zone to CoreDNS. The plugin README lists every option.

Provide your API access token in the DNSIMPLE_TOKEN environment variable rather than in the Corefile, so the token is not stored in a configuration file:

export DNSIMPLE_TOKEN=your-access-token

Start CoreDNS

Start CoreDNS with your Corefile:

./coredns -conf Corefile

Listening on port 53 usually requires administrator privileges. To try the setup first, change .:53 to another port, such as .:1053, and use that port in the next step.

With Docker, mount the Corefile into the container and pass the token. This example makes CoreDNS reachable on port 8053 of the host:

docker run -it -p 127.0.0.1:8053:53/udp -e DNSIMPLE_TOKEN -v ./Corefile:/Corefile dnsimple/coredns:latest

Check that CoreDNS answers

Query CoreDNS for a record in your zone. Use the port CoreDNS is listening on:

dig @127.0.0.1 -p 53 www.example.com A

The answer section shows the same value as the record in DNSimple.

In DNSimple, the DNS Zone Providers card for the domain shows CoreDNS as , and the Record Editor labels each record with your cluster identifier as well as DNSimple.

Change a record and watch it reload

To see a change reach CoreDNS
  1. In the DNSimple Record Editor, add or edit a record in the zone.
  2. Wait for the refresh interval to pass. With the default, that is up to 1 minute.
  3. Run the same dig query for that record. CoreDNS now answers with the new value.

Records only travel from DNSimple to CoreDNS. Always make changes in DNSimple, not on the CoreDNS server.

Next steps

Have more questions?

If you have additional questions or need any assistance with CoreDNS, contact support, and we will be happy to help. You can also read more about DNSimple integrations.