Resolve nodes to your internal nameserver

To manage your nameserver, write your own module and configure it in the console.

DNS overview

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.

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.

Note: You can add the DNS nameserver class to as many agents as needed. For ease of explanation, our instructions might show only one agent.
You will:
  • Write a module
  • Create a node group
  • Classify nodes
  • Set parameters

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 some resources about modules and the creation of modules that you can reference.

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 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 are 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, after applied, ensures your nodes resolve to your internal nameserver. You must 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 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 master). You can create your own groups or add the classes to individual nodes, depending on your needs.

  1. In the console, click Classification, then 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 vary from user to user.

Add the resolver class to the DNS group

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

Next, 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 configures 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 grey 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.

Puppet Enterprise now uses the nameserver IP address you 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 receive. If there had been a problem applying the resolver class, this information tells 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 corrects 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.