Pro Puppet (48 page)

In this example, the
gem
command installs executables to
/var/lib/gems/1.8/gems
. The operator adds this file system location to the
PATH
variable, as shown in
Listing 8-36
, to complete the installation of cucumber-puppet.

Once the cucumber-puppet command is available, we may proceed with writing a story describing the desired Puppet catalog behavior.

The behavior of Puppet is described in Cucumber “stories.” Before writing a story describing the catalog behavior and features, the cucumber-puppet testing directory needs to be created. On a testing system, basic example step definitions should be installed using the cucumber-puppet-gen command (see
Listing 8-37
).

Once the basic steps have been installed, the Example.com operator configures cucumber-puppet by modifying the
hooks.rb
file. Before doing so, he adds and commits the new files to the Git repository as shown in
Listing 8-38
.

Once added to Git, the operator modifies the
hooks.rb
file to configure cucumber-puppet, as shown in
Listing 8-39
.

As you can see, the operator added two lines to the
hooks.rb
file. First, the configuration directory for Puppet is set to
/etc/puppet
. This corresponds to the
confdir
configuration setting. Next, the main
site.pp
file is configured using the @manifest variable. This setting should point to the full path of the
site.pp
file,
/etc/puppet/manifests/site.pp
by default.

Once cucumber-puppet is configured, the catalog policy in
Listing 8-40
is used to test and verify the behavior of the catalog. The Example.com operator uses the cucumber-puppet-gen command to generate a template catalog policy file.

With these three commands, the operator generates a new template for the catalog policy, adds the policy to the Git index, and then commits the new file to the repository. The cucumber-puppet policies closely resemble the natural language stories of Cucumber, as shown in
Listing 8-41
.

There are a few key sections of the policy file. First, the Scenario section is tested for every node listed in the Examples section. Cucumber-puppet substitutes the name listed underneath the
hostname
header into the filename listed in the
Given a node specified by
section. This node cache contains a list of top-level parameters set by
site.pp
, the ENC, and Facter. Using the cached node information stored on the Puppet master allows cucumber-puppet to effectively simulate a catalog request from each Puppet agent.

In order to populate these node definition files, the Example.com operator copies the cached node files from the Puppet Master as shown in
Listing 8-42
. These node files are located in
$yamldir /node/,
where
$yamldir
is a configuration setting on the Master system. Let's see how the operator provides this information to cucumber-puppet.

First, the operator changes to the Puppet configuration directory, then creates the /etc/puppet/features/yaml directory. He then determines where the Puppet Master caches nodes compiled by the Puppet Master using the
--configprint yamldir
option. With this information, he copies the cached node information for the mail and web server into the cucumber-puppet directory structure.

With the node information in place, he modifies the catalog policy slightly to test catalog compilation for the mail and web server, replacing the
localhost
entry in the template. This modification is shown in
Listing 8-43
.

We can see that the operator replaces the
localhost
entry with two additional entries for
www
and
mail
. These names will be substituted into the file path when cucumber-puppet loads the node information. They also match the two YAML node files copied from the Puppet master yaml directory.

With this information in place, the operator commits the changes using the commands in
Listing 8-44
and is ready to start testing changes to the Puppet manifests.

With the YAML node caches copied into place and the catalog policy updated, the operator simply executes cucumber-puppet as shown in
Listing 8-45
, testing his current manifests.

While in the
/etc/puppet
directory, the operator executes cucumber-puppet with the path to the catalog policy file. Cucumber-puppet then tests both the mail and web server and validates that the catalog compilation succeeds. The operator expects as much, but a basic
site.pp
file is being used with an empty node declaration of
node default { }
.

To verify that cucumber-puppet will properly report catalog failures, he modifies the site.pp in
Listing 8-46
to contain the following node definitions:

The operator has reconfigured the site.pp to deliberately fail a catalog compilation when compiling the catalog for the mail server. The web server, however, should still produce a valid catalog. He then verifies these expectations in
Listing 8-47
by re-running the cucumber-puppet command.

Listing 8-47.
Verifying that catalog failures are caught by cucumber-puppet

# cucumber-puppet features/catalog/policy.feature
Feature: General policy for all catalogs
  In order to ensure applicability of a host's catalog
  As a manifest developer
  I want all catalogs to obey some general rules
  Scenario Outline: Compile and verify catalog
    Given a node specified by "features/yaml/.example.com.yaml"
    When I compile its catalog
    Then compilation should succeed
    And all resource dependencies should resolve
    Examples:
      | hostname |
      | www      |
      |This is a deliberate catalog compilation failure at /etc/puppet/manifests/site.pp:17
 on node mail.example.com
 mail     |
      exit (SystemExit)
      features/catalog/policy.feature:8:in `When I compile its catalog'
Failing Scenarios:
cucumber features/catalog/policy.feature:6 # Scenario: Compile and verify catalog
2 scenarios (1 failed, 1 passed)
8 steps (1 failed, 2 skipped, 5 passed)
0m0.132s


The operator uses the fail function to deliberately fail the catalog compilation for the mail server. As expected, cucumber-puppet reports one failed and one successful scenario. The specific error message and line number is returned in the output of cucumber-puppet, allowing the operator to quickly correct the problem.

So far, you've learned how the operator configures cucumber-puppet to test and validate catalog compilation. Next, you'll see how to validate that specific critical resources remain part of the configuration catalog when changes are made to the Puppet modules and manifests.

In the previous section, you learned how to validate catalog compilation successfully after making changes to the Puppet manifests. In this section, you'll see how the operator adds additional scenarios to ensure specific resources remain defined in the configuration catalog.

Catalog compilation errors will be obvious when they occur; the affected nodes will no longer receive a valid catalog. A resource omitted from the catalog is much more difficult to identify, however, because the affected node will still receive and apply the rest of the Puppet catalog. Cucumber-puppet allows the operator to make changes to conditional logic and verify that key resources are not excluded by the change. Let's see how this works.