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:
resolver
to manage a nameserver file called, /etc/resolv.conf
.resolver
class to your agent nodes 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.
resolver
moduleIn 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.
cd /etc/puppetlabs/code/environments/production/modules
.mkdir -p resolver/manifests
to create the new module directory and its manifests directory.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'),
}
}
mkdir -p resolver/templates
to create the templates directory.resolver/templates/resolv.conf.erb
file.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.
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.
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.
name
..*
.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.
resolver
class to the DNS groupNext, you’ll add the resolver
class to your new DNS node group.
resolver
.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.
From the command line of your Puppet master, run puppet agent -t
.
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 theresolver
class to use. You can do this by adding a parameter right 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:
resolver
in the list of classes.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.
puppet agent -t
.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.
/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.
resolver
classFinally, 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.
resolv.conf
class, edit /etc/resolv.conf
to be any nameserver IP address other than the one you want to use./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.
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.