Managing a DNS nameserver 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. 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 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.
DNS getting started overview
To get started managing the DNS nameserver, create a Puppet module and then manage it in the console.
In this guide, you complete 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.
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 create the following files:
-
resolver/
(the module name)-
manifests/
-
init.pp
(contains theresolver
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.)
-
-
That's it! You've written a module that contains a class that, once 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 Puppet master). You can create your own groups or add the classes to individual nodes, depending on your needs.
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.
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.
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.
- 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. - Save and exit the file.
- After Puppet runs, navigate to
- Puppet runs.
- 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.