Pro Puppet (50 page)

Puppet is a fast-moving project with a very active community. Tools designed to work with Puppet will continue to be written as time moves on.

The following resources are a great place to keep track of the tools and work being done by members of the Puppet Community.

• https://github.com/search?q=puppet

• Puppet Users Mailing List -
  mailto:[email protected]

• Puppet Developer Mailing List -
  mailto:[email protected]

• http://blog.puppetlabs.com/


For more information about the Ruby DSL, please see the following resources:

• https://github.com/bobsh/puppet-rubydsl-examples

• http://www.puppetlabs.com/blog/ruby-dsl/
  
• http://projects.puppetlabs.com/projects/1/wiki/Ruby_Dsl
  

Further information about cucumber-puppet and Cucumber is available online at:

• http://www.slideshare.net/nistude/cucumberpuppet

• http://projects.puppetlabs.com/projects/cucumber-puppet/wiki/
  
• https://github.com/nistude/cucumber-puppet
  
• https://github.com/aslakhellesoy/cucumber/wiki


One of the most important aspects of any configuration management system is reporting. Reporting is critical for providing information on accuracy, performance, and compliance to policy and standards, and it can provide graphical representations of the overall state of your configuration. Indeed, we've already seen some examples of how to display Puppet reports (i.e., via a management console) in
Chapter 7
, when we looked at Puppet Dashboard and Foreman.

Puppet's reporting engine has undergone a lot of development in recent releases, especially with the new and more detailed reporting format first introduced in version 2.6.0. In this chapter, we explain what command-line and data-based reports are available, how to configure reporting and reports, and how to work with them, then we look at graphing our reporting data and discuss how to build custom reports.

Puppet agents can be configured to return data at the end of each configuration run. Puppet calls this data a “transaction report.” The transaction reports are sent to the master server where a number of report processors exist that can utilize this data and present it in a variety of forms. You can also develop your own report processors to customize the reporting output.

The default transaction report comes in the form of a YAML file. As mentioned in earlier chapters, YAML is a recursive acronym for “YAML Ain't Markup Language.” YAML is a human-readable data serialization format that draws heavily from concepts in XML and the Python and C programming languages.

The transaction reports contain all events and log messages generated by the transaction and some additional metrics. The metrics fall into three general types: time, resource and change metrics. Within each of these metrics there are one or more values. They include the time taken for the transaction, the number of resources and changes in the transaction and the success or failure of those resources.

In
Listing 9-1
you can see an example of a portion of a YAML Puppet transaction report.

Here you can see that the YAML file is divided into sections. The first section contains any log messages. The log messages are any events generated during the Puppet run, for example, the messages that would typically go to standard out or syslog. The second section contains events related to resources, and it tracks each resource managed by Puppet and the changes made to that resource during the Puppet run. The remaining sections detail the value of each metric that Puppet collects. Each metric has a label, a name and values that make it easy to parse the data, if you wish to use it for reporting or manipulation. Metrics include the number of changes Puppet made, the number of resources managed, and the number and type of events during the run.

The YAML format of the reporting output is very well supported by Ruby, and can be easily consumed in Ruby and other languages to make use of Puppet reporting data.

In order to get Puppet to output the reports we want,  we need to configure it correctly. As of version 2.6.0, each agent is configured by default to not report back to the master; reporting needs to be enabled. The first step to doing this is to ensure that the Puppet agent on the host is started with the
--report
option, like so:

This will cause the Puppet agent to start creating and sending reports to the master. You could also set the
report
option in the
puppet.conf
configuration file:

By default, the reports generated by the agent will be sent to the master and stored as YAML-formatted files in the
report
directory. These files are the output of the default report processor,
store
. Reports are written into sub-directories under the report directory and a directory created for each agent that is reporting. Report file names are the date stamp when the report was generated and are suffixed with
.yaml
, for example:
201010130604.yaml
.

The report directory is
$vardir/reports
(usually
/var/lib/puppet/reports
on most distributions), but you can override this by configuring the
reportdir
option on the Puppet master
puppet.conf
configuration file, like so:

Here, we've set the new report directory to
/etc/puppet/reports
. You can specify whichever directory suits your environment.

There are a number of different report processors available. Report processors are stored on the Puppet master. We've already seen one in
Chapter 7
when we used the
http
report processor to send reports from the master to the Puppet Dashboard.

The default report,
store
, simply stores the report file on the disk. There is also the
log
processor that sends logs to the local log destination, to syslog for example. Also available is the
tagmail
report processor that sends email messages based on particular tags in transaction reports. Next, the
rrdgraph
report processor that converts transaction reports into RRD-based graphs. Lastly, we've already seen the
http
report processor in
Chapter 8
.

Selecting which report processors will run is done using the
reports
configuration option in the
puppet.conf
configuration file.

Each report processor you want to enable should be listed in the
reports
option with multiple processors separated by commas. By default, only
store
is enabled. You can also enable report processors on the command line.

Now let's look at each individual report processor, starting with the
log
processor.

The
log
report processor sends the log entries from transaction reports to syslog. It is the simplest of the report processors. The syslog destination facility is controlled by the
syslogfacility
configuration option, which defaults to the
daemon
facility.

On the previous line, we've directed all syslog output to the
user
facility.

The
tagmail
report sends log messages via email based on the tags that are present in each log message. Tags allow you to set context for your resources, for example you can tag all resources that belong to a particular operating system, location or any other characteristic. Tags can also be specified in your
puppet.conf
configuration file to tell your agents to only apply configuration tagged with the specified tags.