Editing Zero to puppet in one day

This page explains how to get started using puppet to maintain Ubuntu 10.10 (Maverick) and VirtualBox.

=== Pick a server to be puppetmaster ===
Since this machine will have the task of maintaining or rebuilding your important machines, it should not be one of those machines.  Maybe spin up a VM that can be used on any of your machines and make that your puppet server.

==== a note about making virtual machines ====
For our purposes, (making a puppet master or test puppet client) we'll need a VM that appears to be a real machine on the network.  That means turning on bridged networking in Virtualbox.  With the VM running bridged networking, you can watch your normal dhcp server's logs, see the VM ask for a lease, and then add that machine to your dhcpd.conf.

With normal NAT networking, the VM is hidden within the host and uses the Virtualbox internal dhcp server, and so your VM is not a first class citizen on the network.

=== Install puppetmaster ===

Puppet has a lot of dependencies, but in this distro they are well managed and we can just say

 apt-get install puppetmaster

I can't remember if the master starts automatically upon install.  Check:
 service puppetmaster status

If it isn't running, start it:
 service puppetmaster start

=== Install puppet client on a test VM ===

Create a bridged network VM, install Ubuntu on it, and then install puppet client:
 apt-get install puppet

Configure the client to start at boot by editing /etc/default/puppet:
<pre>
# Defaults for puppet - sourced by /etc/init.d/puppet

# Start puppet on boot?
START=yes

# Startup options
DAEMON_OPTS=""
</pre>

Start puppet
 service puppet start

=== Sign the client's cert on the puppet master ===
 puppet cert --list

You should see the client that just started in the output.  Sign the cert to authorize communication between the client and the master:
 puppet cert --sign <hostname>

Now you should have a puppet master that can control a VM client.  Any horrible mistakes will only affect the VM which can easily be rebuilt.

=== Puppet master configs ===
How do you tell the puppet master what to make the clients do?
====/etc/puppet/manifests/site.pp====
<pre>
#import "templates"
import "nodes"
</pre>
The site.pp is entry point for puppetmaster configuration.  This file simply tells puppet to look in the nodes.pp file.
Other site-wide configuration can go here as well.
====/etc/puppet/manifests/nodes.pp====
<pre>
node default {

}

node testingdefault {
	include hosts
}

node 'merkli.finninday.net' inherits testingdefault {
}
node 'ferret.finninday.net' inherits testingdefault {
}
node 'stinkerbelle.finninday.net' inherits testingdefault {
}
node 'potato.finninday.net' inherits testingdefault {
}

node 'weasel.finninday.net' {

}
</pre>

The first node defined here is the default node.  This tells puppet what to do with any machine that talks to the master, but is not specifically mentioned in the nodes.pp.  In this case, do nothing with such machines.

The testingdefault node is defined to get a resource called "hosts".  Notice that order is not important in this file.  We haven't defined what nodes are in the testingdefault node before saying what should happen to such nodes.

The next four nodes insert actual hosts into the testingdefault group.

The last node is a place holder for a machine that does not get the testingdefault treatment.

So, what's a "hosts" resource?

=== Puppet modules ===
<pre>
root@merkli:/etc/puppet/modules/hosts# tree
.
├── files
├── lib
├── manifests
│   └── init.pp
├── templates
│   └── hosts.erb
└── tests
    └── init.pp
</pre>

I've created a puppet module called hosts by creating this file structure.
* files: this is where puppet looks for static files that the module will push out as part of this module
* lib: this isn't important yet
* manifests: this is where puppet gets the configuration files for this module.  init.pp is the default starting point.
* templates: this is where puppet looks for templates (files that are modified before being distributed)
* tests: this is where you can put unit tests

====/etc/puppet/modules/hosts/manifests/init.pp====
<pre>
class hosts {
    file { "/etc/hosts":
        owner => root,
        group => root,
        mode => 644,
        content => template("hosts/hosts.erb"),
    }
}
</pre>
Puppet only does things that you specifically tell it to do.  Here we tell it to make sure there is a file called /etc/hosts and that it has certain permissions and certain content.

====/etc/puppet/modules/hosts/templates/hosts.erb====
<pre>
<%= ipaddress %>	<%= fqdn %> <%= hostname %>
127.0.0.1       localhost.localdomain   localhost
::1     <%= hostname %>    localhost6.localdomain6 localhost6
127.0.1.1       <%= hostname %>

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
ff02::3 ip6-allhosts
</pre>

This is a ruby template that contains variables and static text.  When the template is populated, it looks something like this:
<pre>
10.0.0.14	merkli.finninday.net merkli
127.0.0.1       localhost.localdomain   localhost
::1     merkli    localhost6.localdomain6 localhost6
127.0.1.1       merkli

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
ff02::3 ip6-allhosts
</pre>

===Watch the logs===
====puppetmaster log====
root@merkli:~# tail /var/log/daemon.log
<pre>
Apr 21 09:41:31 merkli puppet-master[21718]: Compiled catalog for weasel.finninday.net in environment production in 0.04 seconds
Apr 21 09:47:29 merkli puppet-master[21718]: Compiled catalog for merkli.finninday.net in environment production in 0.03 seconds
Apr 21 09:47:29 merkli puppet-agent[17513]: Finished catalog run in 0.03 seconds
Apr 21 09:50:02 merkli puppet-master[21718]: Compiled catalog for potato.finninday.net in environment production in 0.03 seconds
Apr 21 10:00:29 merkli puppet-master[21718]: Compiled catalog for ferret.finninday.net in environment production in 0.03 seconds
Apr 21 10:11:33 merkli puppet-master[21718]: Compiled catalog for weasel.finninday.net in environment production in 0.02 seconds
Apr 21 10:17:30 merkli puppet-master[21718]: Compiled catalog for merkli.finninday.net in environment production in 0.03 seconds
Apr 21 10:17:31 merkli puppet-agent[17513]: Finished catalog run in 0.03 seconds
Apr 21 10:20:03 merkli puppet-master[21718]: Compiled catalog for potato.finninday.net in environment production in 0.03 seconds
Apr 21 10:30:33 merkli puppet-master[21718]: Compiled catalog for ferret.finninday.net in environment production in 0.03 seconds
</pre>
This machine is running a puppet master and a puppet client (agent).

====puppet client log====
A client-only log looks more like this:
<pre>
root@ferret:~# tail /var/log/daemon.log
Apr 21 07:30:16 ferret puppet-agent[21576]: Finished catalog run in 0.05 seconds
Apr 21 08:00:19 ferret puppet-agent[21576]: Finished catalog run in 0.04 seconds
Apr 21 08:27:09 ferret dhclient: DHCPREQUEST of 10.0.0.26 on eth0 to 10.0.0.3 port 67
Apr 21 08:27:09 ferret dhclient: DHCPACK of 10.0.0.26 from 10.0.0.3
Apr 21 08:27:09 ferret dhclient: bound to 10.0.0.26 -- renewal in 19925 seconds.
Apr 21 08:30:22 ferret puppet-agent[21576]: Finished catalog run in 0.06 seconds
Apr 21 09:00:25 ferret puppet-agent[21576]: Finished catalog run in 0.05 seconds
Apr 21 09:30:29 ferret puppet-agent[21576]: Finished catalog run in 0.05 seconds
Apr 21 10:00:32 ferret puppet-agent[21576]: Finished catalog run in 0.05 seconds
Apr 21 10:30:36 ferret puppet-agent[21576]: Finished catalog run in 0.05 seconds
</pre>

When puppet actually applies a change, it tells you about it in the client's log:
<pre>
Apr 19 19:56:17 ferret puppet-agent[21576]: (/Stage[main]/Hosts/File[/etc/hosts]/content) content changed '{md5}59063f6a994e24029b1cbaa76453933b' to '{md5}f1223bdaf871d6a14a66c83f8e535c94'
</pre>

===Experiment safely===
Say you've created a new module and you want to see what it will do before it does it.

* turn off the client puppet agent that will get the resource
 service puppet stop

<pre>
root@ferret:~# puppetd -t --graph --noop
info: Caching catalog for ferret.finninday.net
info: Applying configuration version '1303359415'
notice: Finished catalog run in 0.10 seconds
</pre>

* -t switch means test
* --noop means "no operation"
*--graph switch creates a graphviz dot file in /var/lib/puppet/state/graphs which can be turned into an image like this:
 dot -T png resources.dot > resources.png
Which looks like this:
[[image: resources.png]]

=== What's really going on? ===
To have puppet tell you much more about what it is doing, you can temporarily stop the client and server, start them up as normal console applications instead of daemons and crank up the debugging output:

==== on the puppet master====
 service puppetmaster stop
 puppetmasterd --no-daemonize --debug

==== on the puppet client====
 service puppet stop
 puppetd -t --debug

This will cause the puppet client to compile its local state, send it to the server which then compares that state to the state defined by its configuration files.  The server then sends appropriate changes to the client to bring it into compliance with the described state.  The client receives and applies these changes.

(Puppetlabs has a good diagram of this.)


===How to see client changes in the master log===
My default puppet configuration shows all the interesting changes in the client's /var/log/daemon.log.  I'd rather be able to see those client-side changes in the master's log.  Making this happen involves turning on puppet's client reporting mechanism.

==== client-side reporting====
This is controlled by a setting in puppet.conf or a command line parameter to puppetd.  I added the switch to /etc/default/puppet:
<pre>
# Defaults for puppet - sourced by /etc/init.d/puppet

# Start puppet on boot?
START=yes

# Startup options
DAEMON_OPTS="--report"
</pre>

==== server handling of reports====
On the server side, puppet has several options for processing reports.  The default is to create a yaml file in /var/lib/puppet/report/<nodename>
To tell puppet to send the client report of changes to syslog (which in this case is sent to daemon.log), make this change to /etc/puppet/puppet.conf
<pre>
[master]
reports = log
</pre>

Now, if you fiddle with a puppet controlled resource on the client (like adding a blank line to /etc/hosts), and restart the puppet client, you'll see puppet's corrective actions reported in the master's /var/log/daemon.log.

== Suggested reading ==
* http://projects.puppetlabs.com/projects/puppet/wiki/Puppet_Patterns
The beauty of open source is seeing how other people solve problems and sharing solutions.  Here is a list of recipes for solving problems with puppet.  The beginner will want to pay special attention to the Simplest Puppet Install Recipe, and the Advanced Puppet Pattern.