Managing a DNS nameserver with PE

A nameserver ensures that the human-readable names you type in your browser (for example, can be resolved to IP addresses that computers can read. This guide provides instructions for getting started managing a simple DNS nameserver file with PE.

Sysadmins typically need to manage a nameserver file for internal resources that aren't published in public nameservers. For example, let's say you have several employee-maintained servers in your infrastructure, and the DNS network assigned to those servers use Google's public nameserver located at However, there are several resources behind your company's firewall that your employees need to access on a regular basis. In this case, you'd build a private nameserver (say at, and then use PE to ensure all the servers in your infrastructure have access to it.

DNS getting started overview

To get started managing the DNS nameserver, you'll create a Puppet module and then manage it in the console.

In this guide, you'll do the following tasks:

  • Write a simple module that contains a class called resolver to manage a nameserver file called, /etc/resolv.conf.
  • Create a DNS node group.
  • Add the resolver class to your agent nodes in the PE console.
  • Change the contents of the nameserver file to see how PE enforces the desired state you specified in the PE console.

Before you begin, you must have installed PE. Refer to the installation overview and the agent installation instructions for complete instructions. See the supported operating system documentation for supported platforms. This guide assumes you are not using Code Manager or r10k.

Tip: Follow the instructions in the NTP getting started guide to have PE ensure time is in sync across your deployment.
Note: You can add the DNS nameserver class to as many agents as needed. For ease of explanation, our console images and instructions might show only one agent.

About module directories

By default, Puppet keeps modules in /etc/puppetlabs/code/environments/production/modules. This includes modules that you download from the Forge and those you write yourself.

PE also creates two other module directories: /opt/puppetlabs/puppet/modules and /etc/puppetlabs/staging-code/modules. For this guide, don't modify or add anything to either of these directories.

There are plenty of resources about modules and the creation of modules that you can reference.

Related topics:

  • Puppet: Module fundamentals.
  • Puppet: The modulepath.
  • The Beginner's guide to modules.
  • The Puppet Forge.

Write the resolver module

Write a small module to ensure that your nodes resolve to your internal nameserver.

This module contains just one class and one template. Modules are directory trees. For this task, you'll create the following files:

  • resolver/ (the module name)

    • manifests/

      • init.pp (contains the resolver class)

    • templates/

      • resolve.conf.erb (contains the template for the /etc/resolv.conf template, the contents of which will be populated after you add the class and run PE.)

  1. From the command line on the Puppet master, navigate to the modules directory: cd /etc/puppetlabs/code/environments/production/modules
  2. Run mkdir -p resolver/manifests
  3. From the manifests directory, use your text editor to create the init.pp file, and edit it so it contains the following Puppet code.
    class resolver (
    ) {
      file { '/etc/resolv.conf':
        ensure  => file,
        owner   => 'root',
        group   => 'root',
        mode    => '0644',
        content => template('resolver/resolv.conf.erb'),
  4. Save and exit the file.
  5. Run mkdir -p resolver/templates to create the templates directory.
  6. Use your text editor to create the resolver/templates/resolv.conf.erb file.
  7. Edit the resolv.conf.erb so that it contains the following Ruby code. 
    # Resolv.conf generated by Puppet
    <% [@nameservers].flatten.each do |ns| -%>
    nameserver <%= ns %>
    <% end -%>
    # Other values can be added or hard-coded into the template as needed.
  8. Save and exit the file.

That's it! You've written a module that contains a class that will, once applied, ensure your nodes resolve to your internal nameserver. You'll need to wait a short time for the Puppet server to refresh before the classes are available to add to your agents.

Note the following about your new class:

  • The class resolver ensures the creation of the file /etc/resolv.conf.
  • The content of /etc/resolv.conf is modified and managed by the template, resolv.conf.erb. You will set this content in the next task using the PE console.

Create the DNS node group

To manage DNS on your nodes, create a new node group that contains all of your nodes.

Create the DNS node group to contain all the nodes in your deployment (including the Puppet master). You can create your own groups or add the classes to individual nodes, depending on your needs.

  1. In the console, click Classification, and click Add group
  2. Specify options for the new node group:
    • Parent name – Select default

    • Group name - Enter a name that describes the role of this environment node group, for example, DNS.

    • Environment - Select Production

    • Environment group - Don't select this option

  3. Click Add.
  4. Click the DNS group,and select the Rules tab.
  5. In the Fact field, enter name.
  6. From the Operator drop-down list, select ~ (matches regex).
  7. In the Value field, enter .* .
  8. Click Add rule.

This rule "dynamically" pins all nodes to the DNS group. This rule is for testing purposes; decisions about pinning nodes to groups in a production environment will vary from user to user.

Add the resolver class to the DNS group

After you create a group, add a class to it.

Next, you'll add the resolver class to your new DNS node group.

  1. In the console, select Classification, and then find and select the DNS group.
  2. On the Configuration tab, in the Class name field, select resolver.
  3. Click Add class, and commit changes.
    Note: The resolver class now appears in the list of classes for the DNS group, but it has not yet been configured on your nodes. For that to happen, you need to kick off a Puppet run.
  4. From the command line of your Puppet master, run puppet agent -t.
  5. From the command line of each PE-managed node, run puppet agent -t.

This will configure the nodes using the newly-assigned classes. Wait one or two minutes.

You're not done just yet! The resolver class now appears in the list of classes for your DNS group, but it has not yet been fully configured. You still need to add the nameserver IP address parameter for the resolver class to use. You can do this by adding a parameter right in the console.

Add the nameserver IP address parameter in the console

You can add class parameter values to the code in your module, but it’s easier to add those parameter values to your classes using the PE console.

  1. In the console, select Classification, and then find and select the DNS group.
  2. On the Configuration tab, find resolver in the list of classes.
  3. From the parameter drop-down list, select nameservers.
  4. In the Value field, enter the nameserver IP address you’d like to use (for example,
    Note: The gray text that appears as values for some parameters is the default value, which can be either a literal value or a Puppet variable. You can restore this value by selecting Discard changes after you have added the parameter.
  5. Click Add parameter, and commit changes.
  6. From the command line of your Puppet master, run puppet agent -t.
  7. From the command line of each PE-managed node, run puppet agent -t.

    This triggers a Puppet run to have Puppet Enterprise create the new configuration.

  8. Navigate to /etc/resolv.conf. This file now contains the contents of the resolv.conf.erb template and the nameserver IP address you added in step 5.

Success! Puppet Enterprise will now use the nameserver IP address you've specified for that node.

Viewing DNS changes on the Events page

The Events page lets you view and research changes. You can view changes by class, resource, or node.

After applying the resolver class, you can use the Events page to confirm that changes were indeed made to your infrastructure, most notably that the class created /etc/resolv.conf and set the contents as specified by the module's template.

The further you drill down in this page, the more detail you'll receive. If there had been a problem applying the resolver class, this information would tell you exactly where that problem occurred or which piece of code you need to fix.

You can click Reports, which contains information about the changes made during Puppet runs, including logs and metrics about the run. See Infrastructure reports for more info.

For more information about using the Events page, see Working with the Events page.

Check that PE enforces the desired state of the resolver class

If your infrastructure changes from what you've specified, PE will correct that change. To test this, make a manual infrastructure change and then run Puppet.

When you set up DNS nameserver management, you set the nameserver IP address. If a member of your team changes the contents of /etc/resolv.conf to use a different nameserver, blocking access to internal resources, the next Puppet run corrects this. You can test this by manually changing the resolv.conf file.

  1. On any agent to which you applied the resolv.conf, edit /etc/resolv.conf to be any nameserver IP address other than the one you want to use.
  2. Save and exit the file.
  3. After Puppet runs, navigate to
  4. Puppet runs.
  5. Navigate to /etc/resolv.conf, and notice that PE has enforced the desired state you specified for the nameserver IP address.

That's it! PE has enforced the desired state of your agent node. And remember, review the changes to the class or node using the Events page.

Learning more about Puppet and DNS

This guide provides a basic discussion of Puppet and DNS.

For more information about working with Puppet Enterprise and DNS, check out our Dealing with name resolution issues blog post.