DNS quick start guide

The Puppet Enterprise DNS quick start guide gets you started managing a simple DNS nameserver file with PE. A nameserver ensures that the “human-readable” names you type in your browser (for example, google.com) 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 8.8.8.8. 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 10.16.22.10), and then use PE to ensure all the servers in your infrastructure have access to it.

In this exercise, 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 quick start 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.

Write the resolver module

In this step, you’ll write a simple module to manage a nameserver file. 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/
    • resolv.conf.erb (contains template for /etc/resolv.conf template, the contents of which will be populated after you add the class and run PE.)

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. Check out Puppet: Module fundamentals, Puppet: The modulepath, the Beginner’s guide to modules, and the Puppet Forge.

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 to create the new module directory and its manifests directory.

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 (
      $nameservers,
    ) {
   
      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 file 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

After writing the resolver module, you’ll create a new node group called DNS, which will contain all of your nodes.

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

1. In the console, click Nodes > 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. Note that this rule is for testing purposes and that decisions about pinning nodes to groups in a production environment will vary from user to user.

Add the resolver class to the DNS group

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

1. In the console, select Nodes > Classification, and find and select the DNS group.
2. On the Classes 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.

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 parameters to your classes using the PE console. To edit the server parameter of the resolver class:

1. In the console, click Nodes > Classification, and find and select the DNS group.
2. On the Classes tab, find resolver in the list of classes.
3. From the parameter drop-down list, choose nameservers.

4. In the Value field, enter the nameserver IP address you’d like to use (for example, 8.8.8.8).

   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.

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

Viewing changes on the Events page

The Events page lets you view and research changes. You can view changes by class, resource, or node. For example, 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.

Enforce the desired state of the resolver class

Finally, let’s take a look at how PE ensures the desired state of the resolver class on your agent nodes. In the previous task, you set the nameserver IP address. Now imagine a scenario where a member of your team changes the contents of /etc/resolv.conf to use a different nameserver and can no longer access any internal resources.

1. On any agent to which you applied the resolv.conf class, 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. Puppet runs.
4. 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.

Other resources

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

Puppet offers many opportunities for learning and training, from formal certification courses to guided online lessons. We’ve noted a few below; head over to the learning Puppet page to discover more.

• Learning Puppet is a series of exercises on various core topics about deploying and using PE.
• The Puppet workshop contains a series of self-paced, online lessons that cover a variety of topics on Puppet basics. You can sign up at the learning page.