diff options
Diffstat (limited to 'documentation/testing.rst')
| -rw-r--r-- | documentation/testing.rst | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/documentation/testing.rst b/documentation/testing.rst new file mode 100644 index 000000000..fb0a1a870 --- /dev/null +++ b/documentation/testing.rst @@ -0,0 +1,82 @@ +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 + +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 localhost --noop --onetime + +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 puppet --server localhost --test --tag 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. + +.. _node: structures#nodes +.. _source: fromsvn |