The Puppet Labs Issue Tracker has Moved:

This issue tracker is now in read-only archive mode and automatic ticket export has been disabled. Redmine users will need to create a new JIRA account to file tickets using See the following page for information on filing tickets with JIRA:

« Previous - Version 16/28 (diff) - Next » - Current version
Nikolay Sturm, 09/07/2010 07:07 am


Cucumber-puppet is a tool for specifying Puppet catalog behavior. It allows the specification of a catalog-wide policy and ensures compliance with it.

Cucumber-puppet uses Cucumber features as specifications and provides the necessary glue to access a node’s catalog from Cucumber’s step definitions.


Initial setup

Before writing your first feature, you have to setup the infrastructure in your Puppet directory. Assuming you develop your Puppet manifests in ~/puppet/.

$ cd ~/puppet
$ cucumber-puppet-gen world

This installs some example step definitions for cucumber to ./features/steps/ and ensures the cucumber-puppet glue code is available. You can adapt cucumber-puppet to your needs in the Before block in ./features/support/hooks.rb with the following variables:

@confdir    Puppet's confdir
            defaults to /etc/puppet
@manifest   full path to the manifest to use
            defaults to @confdir + /manifests/site.pp
@facts      this is a hash of facter facts
            defaults to
                'architecture' => ''
                'domain' => 'no.domain'
                'environment' => 'production'
                'hostname' => 'testnode'
                'lsbdistcodename' => ''
                'network_eth0' => ''
                'operatingsystem' => ''

Facts can be either set globally as described above or from Given steps which makes them specific to that scenario. It is also possible to load a node’s yaml file and compile a catalog for that specific node. See provided step definitions for further details.

Writing a catalog policy

A catalog policy is a list of rules that applies to all catalogs. Here is a simple examples:

$ cat features/catalog/policy.feature
Feature: General catalog policy
  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/<hostname>"
    When I compile its catalog
    Then compilation should succeed
    And all resource dependencies should resolve
    And all file sources should exist in git repository
    And all file templates should exist in git repository

      | host1 |
      | host2 |

There is one Scenario per node which translates to one full catalog compilation per node and all policy rules (Then steps) apply equally to all of them.

For catalog policies it makes sense to specify facts from a node file, so that Puppet compiles exactly the catalog that is later used by that node. Node files can be copied from your Puppet master, on Ubuntu systems they reside in /var/lib/puppet/yaml/node/.

If you have many nodes, it makes sense to generate Scenarios from a script and to limit scenario creation to unique nodes, that is if you have 100 identical desktop PCs, just verify the catalog against one of them.

Applying the policy

To apply the policy, execute it with cucumber-puppet

$ cucumber-puppet features/catalog/policy.feature

When you add further rules to your policy, cucumber-puppet will complain about missing step definitions. Add these to your step files as necessary and make your feature green.

For more information about writing cucumber features, see cucumber tutorials.


Source code is available from github.

Gems are available from rubygems.