Test-driving Puppet

If you want to just test-drive Puppet, making the least commitment possible, you can run it directly from the checked-out source, against a configuration in a temporary directory.

The default Puppet configuration directory (where it looks for its manifests, and where it stores certificates and logs) is /etc/puppet if you are running the executables as root or ~/.puppet otherwise. All of the executables accept a --confdir <directory> flag to change this directory.

I often use my local Subversion sandbox for testing (i.e., I have my Puppet configuration stored in Subversion and checked out in my home directory, and I just test Puppet directly against this configuration). Normally Puppet would make the configuration directory for you, but the server needs the site.pp to exist, so you need to create the manifests subdirectory:

$ mkdir -p /var/tmp/puppet/manifests
$ vi /var/tmp/puppet/manifests/site.pp
<create file>

Alternatively, you can just specify the manifest itself:

$ sudo puppetmasterd --verbose --manifest ~/svn/puppet/manifests/site.pp

I also always at least run the daemons in verbose mode while testing. First start the central daemon:

$ sudo puppetmasterd --verbose --confdir /var/tmp/puppet

(If you're only going to do dry-run testing of your configuration, sudo won't be necessary for any of these commands.)

By default, puppetmasterd looks for node definitions along these lines:

node mymachine {
    include $operatingsystem
}

You can put any valid Puppet code in the structure, but the important point is that the node definitions need to be there or you need to tell puppetmasterd they are not there by using the --nonodes argument. If you are trying to write a config that works for both puppet (the stand-alone executable) and puppetd (the client to puppetmasterd), then you should create the config without nodes and use the --nonodes argument.

Once you have the manifest, start the client, pointing it at the local server, running in noop mode the first time:

$ sudo puppetd --verbose --confdir /var/tmp/puppet --server <local-hostname> --noop --onetime

Replace <local-hostname> with your server's hostname. If you use localhost, you will also need to add --certname localhost to the arguments given to puppetmasterd.

The first time you run the above command, a request for a node certificate will be created. You can sign it using:

$ sudo puppetca --confdir /var/tmp/puppet --sign --all

When this is done, rerun the puppetd command line above. This will connect to the server, retrieve the current machine's configuration, and run it. In noop mode, this should work for any user, but if you run it as a normal user you might get some errors if you are not in noop mode (e.g., normal users cannot use 'chown').

Note that your site.pp file should have a node definition for the host connecting; otherwise you will get an error complaining of no configuration for that host. It is possible to skip this requirement -- see the --help output of puppetmasterd for details.

Configuration Testing

Once you're successfully running the daemons, there are other useful flags you can use to make your life easier. First is the --test flag for puppetd, which is the equivalent of running with --onetime --verbose --no-usecacheonfailure, which means the puppet client will exit after the first run and will not use the cached configuration if the central one is broken somehow (this is useful for those cases where you accidentally cause a parsing error in the config).

Also, you can narrow down what portion of the configuration you are testing by using --tag. For instance, say you are running this on a machine that is an ldapserver, namedserver, and webserver, and you're adding ntpserver to the list of classes being evaluated. Rather than sitting through the entire config every run, just apply the ntpserver elements:

$ sudo puppetd --server localhost --test --tags ntpserver

Every element in Puppet is tagged with the class or definition enclosing that element, all the way up to the base of the configuration, and it is also tagged with the host name. So if classA includes classB which creates fileC, then fileC will be tagged with both classes.