Free Trial

How I use the DNSimple Chef Cookbook

Amelia Aronsohn's profile picture Amelia Aronsohn on

Hey everyone! Amelia here. Nice to meet you all. This is my first post at DNSimple and I'm super excited to share what we have been working on.

When I first came on, one of the first things I noticed was that our public cookbook wasn't working well. We sat down, cleaned it up to both internal & community standards, and added it into the Chef cookbook partner program.

I'm not a fan of managing massive BIND/TinyDNS files; being able to automate DNS when I am spinning up machines saves error prone manual work. We hope that our cookbook and the services we offer can simplify and automate your domain name management.

Allow me to show you how I personally use our cookbook to automate domain services.


I'm going to assume here that you've already set up your account and added your domain(s). I'm also going to assume you are an experienced chef using the chef-dk. If you don't know how to chef yet, check out

Store your credentials securely with vault

You could use encrypted (or even plain) data bags here, but I'm going to demo vault quickly for this. There are some gotchas with using chef-vault. You will need to bootstrap a node with a blank runlist, then run knife vault update to add the new node to the vault before you can add the actual runlist. So don't just pull this into a large working setup unless you are sure about what you are doing.

If you are using chef-vault you also have to set up your knife.rb according to the documentation here.

Let's create a new dnsimple item in the secrets vault. We are going to set the search term to *:* (which you probably don't wanna do unless you only have a small amount of machines) so as to figure out who has permission to this. Check out this repo here for more details on how to use chef vault.

The token below is the APIv1 key from DNSimple's users page.

knife vault create secrets dnsimple -S '*:*'
knife vault edit secrets dnsimple
  "user": "",
  "token": "BigLongString"

Set up the hostnames automatically

First and foremost when I bootstrap a box, I set the node-name to the hostname of the machine and let the chef_hostname cookbook set it. Our dnsimple cookbook then sets up the domain name globally.

include_recipe 'chef-vault::default'
credentials = chef_vault_item('secrets', 'dnsimple')

my_fqdn      =
my_apexname  = my_fqdn.split('.')[-2..-1].join('.')
my_subdomain = my_fqdn.split('.')[0..-3].join('.')
my_shortname = my_fqdn.split('.').first

hostname my_fqdn do
  aliases [my_shortname]

include_recipe 'dnsimple::default'

dnsimple_record 'main_hostname_setup' do
  name     my_subdomain
  content  node['ipaddress']
  type     'A'
  domain   my_apexname
  username credentials['user']
  token    credentials['token']
  action   :create

Going past the hostname

Ok, that's great but what about all my convenience domains like mail, www, coolapp, etc?

Well there is a few different ways to approach this; the bigger your setup, the more complex this is going to be since you don't want to set the same domain name to the same box or they will battle for it. I can't offer up a one-size-fits-all solution, but I can offer up what I do for my small setup—which is setting the node attributes in a wrapper.

default['dnsimple']['cnames'] = %w( www coolapp )

Now we can modify our hostname setting with something cool like this

my_aliases = node['dnsimple']['cnames'].map{ |x| x + '.' + my_apexname }

hostname my_fqdn do
  aliases [my_shortname] + my_aliases

node['dnsimple']['cnames'].each do |cname|
  dnsimple_record "#{cname}_cname_setup" do
    name     cname
    content  my_fqdn
    type     'CNAME'
    domain   my_apexname
    username credentials['user']
    token    credentials['token']
    action   :create

Enjoy your hands off DNS with machine converges

I hope this document gives you a lot of ideas on what you can do with our cookbook and Chef. If you have any suggestions or need any help, feel free to open an issue at the github repo or send us a support email.

Also, be careful with test-kitchen. Because our cookbook doesn't yet support our sandbox environment, you could overwrite production entries. I recommend always prefixing your node names in your .kitchen.yml with test- or some other marker to prevent problems. See the kitchen docs for more information.

If you want to read more into this check out our developer documentation as well.

Looking towards version 2.0

We're working on the 2.0 version of this cookbook, moving to the Chef 12 custom resources and our new API v2 so you will be able to use the domain or account access tokens to restrict permissions. The 2.0 may be a breaking release since we are adding so much so make sure to pin the cookbook to the 1.0 series to prevent problems in the future.

Share on Twitter and Facebook

Amelia Aronsohn's profile picture

Amelia Aronsohn

Kaizen junkie, list enthusiast, automation obsessor, unrepentant otaku, constantly impressed by how amazing technology is.

We think domain management should be easy.
That's why we continue building DNSimple.

Try us free for 30 days
4.5 stars

4.3 out of 5 stars.

Based on and reviews.