Pro Puppet (52 page)

After we restarted the Puppet master and performed a Puppet run, the new report would be generated. In our case, the final report is contained in a file called
summary.txt
and looks something like this:

In this chapter, we've demonstrated the basics of Puppet reporting, including how to configure reporting and some details on each report type and its configuration.

We've also shown you how to create custom reports of your own, making use of the report data in its YAML form or via processing with a custom report processor.

• Report Reference:
  http://docs.puppetlabs.com/references/latest/report.html
  
• Reports and Reporting:
  http://projects.puppetlabs.com/projects/puppet/wiki/Reports_And_Reporting
  
• Existing reports:
  https://github.com/puppetlabs/puppet/tree/master/lib/puppet/reports
  

Among the most powerful features of Puppet are its flexibility and extensibility. In addition to the existing facts, resource types, providers, and functions, you can quickly and easily add custom code specific to your environment or to meet a particular need.

In the first part of this chapter we're going to examine how to add your own custom facts. Adding custom facts is highly useful for gathering and making use of information specific to your environment. Indeed, we've used Facter extensively in this book to provide information about our hosts, applications and services, and you've seen the array of facts available across many platforms. You may have noted, though, that Facter isn't comprehensive; many facts about your hosts and environments are not available as Facter facts.

In the second part of the chapter, we're going to examine how to add your own custom types, providers and functions to Puppet and how to have Puppet distribute these, and we'll discuss how to make use of them. These are among Puppet's most powerful features, and are at the heart of its flexibility and extensibility. Being able to add your own enhancements in addition to the existing resources types, providers and functions, you can quickly and easily add custom code specific to your environment or to meet a particular need.

Creating your own custom facts to Puppet is a very simple process. Indeed, it only requires a basic understanding of Ruby. Luckily for you, Ruby is incredibly easy to pick up and there are lots of resources available to help (refer to the “Resources” section at the end of the chapter for some helpful links).

In the following sections, you'll see how to successfully extend Facter. We first configure Puppet so we can write custom facts, then we test our new facts to confirm they are working properly.

The best way to distribute custom facts is to include them in modules, using a Puppet concept called “plug-ins in modules.” This concept allows you to place your custom code inside an existing or new
Puppet module and then use that module in your Puppet environment. Custom facts, custom types, providers, and functions are then distributed to any host that includes a particular module.

Modules that distribute facts are no different from other modules, and there are two popular approaches to doing so. Some people distribute facts related to a particular function in the module that they use to configure that function. For example, a fact with some Bind data in it might be distributed with the module you use to configure Bind. This clusters facts specific to a function together and allows a greater portability. Other sites include all custom facts (and other items) in a single, central module, such as a module called
facts
or
plugins
. This centralizes facts in one location for ease of management and maintenance.

Each approach has pros and cons and you should select one that suits your organization and its workflow. We personally prefer the former approach because it limits custom facts and other items to only those clients that require them, rather than all hosts. For some environments, this may be a neater approach. We're going to use this approach in this section when demonstrating managing custom facts.

So where in our modules do facts go? Let's create a simple module called
bind
as an example:

Here we've created our standard module directory structure, but we've added another directory, lib. The lib directory contains any “plug-ins” or additional facts, types or functions we want to add to Puppet. We're going to focus on adding facts; these are stored in the
lib/facter
directory.

In addition to adding the
lib/facter
directory to modules that will distribute facts, you need to enable “plug-ins in modules” in your Puppet configuration. To do this, enable options in the
[main]
section of the Puppet master's
puppet.conf
configuration file, as you can see on the next line:

When set to true, the
pluginsync
setting turns on the “plug-ins in modules” capability. Now, when clients connect to the master, each client will check its modules for facts and other custom items. Puppet will take these facts and other custom items and sync them to the relevant clients, so they can then be used on these clients.

After configuring Puppet to deliver our custom facts, you should actually create some new facts! Each fact is a snippet of Ruby code wrapped in a Facter method to add the result of our Ruby code as a fact. Let's look at a simple example in
Listing 10-1
.

In this example, our custom fact returns the value of the
HOME
environmental value as a fact called
home
, which in turn would be available in our manifests as the variable
$home
.

The
Facter.add
method allows us to specify the name of our new fact. We then use the
setcode
block to specify the contents of our new fact, in our case using Ruby's built-in
ENV
variable to access an environmental variable. Facter will set the value of our new fact using the result of the code executed inside this block.

In
Listing 10-2
, you can see a custom fact that reads a file to return the value of the fact.

Here, we're returning the timezone of a Debian host. We've also done two interesting things. First, we've specified a
confine
statement. This statement restricts the execution of the fact if a particular criteria is not met. This restriction is commonly implemented by taking advantage of the values of other facts. In this case, we've specified that the value of the
operatingsystem
fact should be Debian for the fact to be executed. We can also use the values of other facts, for example:

The previous
confine
is commonly used to limit the use of a particular fact to nodes with Linux-based kernels.

Second, we've used the
readlines
File method to read in the contents of the
/etc/timezone
file. The contents are returned as the fact
timezone
, which in turn would be available as the variable
$timezone
.

We've established how to confine the execution of a fact but we can also use other fact values to influence our fact determination, for example:

Here, if the operating system is Debian or Ubuntu, it will return a time zone value by returning the value from the
/etc/timezone
file. Otherwise, the fact will use Ruby's in-built time handling to return a time zone.

You could also use a case statement to select different fact values, for example as used in the
operatingsystemrelease
fact shown in
Listing 10-3
.

You can use other fact values for any purpose you like, not just for determining how to retrieve a fact. Some facts return another fact value if they cannot find a way to determine the correct value. For example, the
operatingsystem
fact returns the current kernel,
Facter.value(:kernel)
, as the value of
operatingsystem
if Facter cannot determine the operating system it is being run on.

You can create more complex facts and even return more than one fact in your Ruby snippets, as you can see in
Listing 10-4
.