The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

Getting Started with a Simple Puppet Pattern

Using Puppet is largely about developing the Puppet manifests, which describe the desired configuration of your system.

Once you have Puppet installed (see Installation Guide) on at least one server, you’re ready to set up a minimal configuration and get started using Puppet. Using puppet in agent master mode is also supported for more than one system.

If you want to test your Puppet manifests without installing a client and server you can run:

puppet apply /path/to/puppet/test/file.pp

A Simple Manifest: Managing Ownership of a File

For our first manifest, we’ll manage a single resource (in this case, a file) on all of our hosts.

Step one: Create sudo manifests

First, we’ll create a class in a puppet manifest under a sudo module. The puppet autoloader convention require all modules contain an init.pp file that contains a class or define that matches the module name. We’ll use this appropriately-named manifest for all configuration information related to sudo, so next time we’ll be able to find the sudo stuff quickly. We’ll start simple, and just manage the sudoers file for now:

# /etc/puppet/modules/sudo/manifests/init.pp

class sudo {
    file { "/etc/sudoers":
        owner => 'root',
        group => 'root',
        mode  => '0440',
    }
}

So now we have a class which contains a single file resource that will ensure that the owner, group, and mode of the /etc/sudoers file will be set consistently across all systems that includes that class (but we haven’t chosen which computers belong in that class, yet).

Step two: Create a test manifests.

In order to test the class we just created, add a test manifest to the sudo module:

# /etc/puppet/modules/sudo/tests/init.pp

# This is the same as 0.25.x
# include sudo
class { 'sudo': }

Next, we can simulate the sudo class by applying the test manifests with the noop flag:

puppet apply --noop /etc/puppet/modules/sudo/tests/init.pp

If the system configuration is different than the specification in the sudo class, you should see what puppet would have changed during the —noop run, and you can apply those changes by removing noop, so puppet is no longer simulating the changes, but enforcing the configuration against the system:

puppet apply /etc/puppet/modules/sudo/tests/init.pp

Step three: Create /etc/puppet/manifests/site.pp

Now we’ll create the site.pp manifest which is the master manifest. Puppet will search for a manifest by this name by default. Here’s our file:

# /etc/puppet/manifests/site.pp

node default {
    include sudo
}

After we create a default node definition, the default node definition will be applied to any node that doesn’t fall into any other node definition’s scope. In this case, since we have no other node definitions, all puppet agents will follow this node definition and so any node will include our sudo class.

Step four: Start the Puppetmaster

Now that we have a basic manifest configuration laid out, we can start the Puppet master daemon. The —mkusers option is only necessary the method used to install puppet didn’t create the puppet user and group:

master % sudo puppet master --mkusers

This will background the daemon and send all of its logs to the syslog facility. If you would prefer, you can add —verbose —no-daemonize and the daemon will stay in the foreground and its messages will go to the terminal.

On Ubuntu and other Debian based distributions, starting the Puppetmaster daemon works like this:

master % sudo /etc/init.d/puppetmaster restart

Step five: Run a client

It’s usually best to start with your first client being Puppetmaster server itself. However, since the Puppetmaster will be talking to itself, that client will already have a certificate, so no signing will be necessary to establish trust between the Puppetmaster server and itself. In this example, we’ll configure a client that isn’t the Puppetmaster server so we can demonstrate how to establish cryptographic trust between the Puppetmaster server and its new clients:

First, start puppet agent on the client in verbose mode:

client% sudo puppet agent --verbose

You should see a message about not receiving a certificate, and on the server you should get a message about a request waiting for you. On the server, we’ll list the certificates waiting for signatures:

master% sudo puppet cert --list

You should see our client’s name listed, so we can give the Puppetmaster the command to sign its certificate (thus creating a trust relationship that client):

master% sudo puppet cert --sign <client>

Within two minutes (the default value for —waitforcert), the client should connect again and receive its signed certificate. Once the signed cert is in place, the client should ask for its configuration; the server will compile it (and log that it has done so) and pass the compiled configuration to the client.

Then, if the sudoers file had incorrect permissions, we should see one or more messages indicating the corrections; but if everything about the sudoers file is already correct, you’ll just see messages about starting and ending the configuration run.

If you restart puppetd without the —verbose option, it will background itself and run periodically thereafter, checking with the Puppetmaster server to see if there the manifests have changed.

Caveat

This is half of the infrastructure for a working Puppet installation. The other half of a hygienic and efficient installation revolves around version-controlling the Puppet manifests and the files Puppet will be managing. It also provides a minimalist structure around which to build other Puppet classes.

Where to next

Have a look at the Advanced Puppet Pattern to see how we can build on this basic recipe.

%orangecone — This should redirect to Learning Puppet front page.