The problem: You have a puppet function you find useful. At this point custom functions are really easy to create and distribute via modules so there’s really no reason not to be using them. However, you want to use the result of a function in your templates.

A real-world example of this is sharing authentication information. (For example, crypted password hashes. Plain text, as always, would be evil no matter where it was living.)
You really have 3 choices:

• Coding it right into your puppet code and checking that into your version control system
• Not distributing that information with puppet
• Using puppet to distribute the information, but store it outside of your puppet modules somehow.

We chose the third way, and store this kind of information in YAML files outside the puppet modules tree.
Anyway. So we want to access this info inside a template.

Assume you have a function called ‘get_extdata’.
You normally call from your ‘.pp’ manifests with something like

$data = get_extdata('mymodule', 'path:to:data')

You can make a call like that from your template by doing this wonderful fragment of magic-wand-waving to get this function accessible:

In mytemplate.erb:

<% Puppet::Parser::Functions.autoloader.loadall %>
Now you can use the 'scope' variable to get at your function.
This is the equivalent of the call get_extdata('mymodule',  'path:to:data'):
<%= scope.function_get_extdata('mymodule',  'path:to:data') %>

This works like a charm, and means you don’t have to create a bunch of variables that you don’t really need before you load the template.

So if you were creating an .htpasswd style file with puppet, you could do

In your init.pp

$users = ['steve', 'paul', 'stu']

htpasswd.erb:

<% Puppet::Parser::Functions.autoloader.loadall %>
<% users.each do |user| -%>
<%= user %>:<%= scope.function_get_extdata('authmodule',  user) %>
<% end -%>

/base and /site

Our puppet modules are stored in 2 directories: /base and /site. Here are the purposes:

/base

The best way to think of what goes in /base is:

I should be able to (and should!) post my /base tree to github or my blog, and it would be useful to other people.

Examples of things that might go into base are:

• virtuozzo
• nginx
• lighttpd
• perlbal
• debrepo
• rpmrepo
• openvpn
• mysql
• memcached

Essentially, the environments that make daemons or applications useable.

/site

Site should be

This should not be in any way useful (or safe to share) outside my company

Good examples might be:

• mywebapp
• mystatshud
• mymonitoringsystem

Module Design

Any functionality we want to do on a server can more or less be defined as:

I want to set up some applications and an environment in a certain way, so that it does what I want

Sample application: mywebapp

So, for example, if we wanted to build an mywebapp module, we’d need certain things to make that work.
Let’s assume that we need

• lighttpd installed and configured in a certain way
• apache installed and configured in a certain way
• some perl libraries installed
• some cron jobs set up

and so on.

The obvious way

The way I started out solving these sorts of problems turns out to not scale all that well.
As I started a module (to solve a specific problem) I would just start listing out the puppet resources it would need.

mywebapp/manifests/init.pp

package { "lighttpd": ensure => installed }
service { "lighttpd": ensure => running, enabled => true }
package { "lib-catalyst-rest-perl": ensure => installed }
package { "apache2": ensure => installed }
service { "apache2": ....

and so on.

This breaks down in several ways.

Things can only be defined once in puppet

First, puppet only lets us define a resource once. So if we decide we want a new tool that needs the package lib-catalyst-rest-perl installed, or needs to use apache to host some stats HUD,
we’d have a problem.

statshud/manifests/init.pp

...
package { "apache2": ensure => installed }
...

Puppet will freak.

Puppet::Parser::AST::Resource failed with error ArgumentError: Duplicate definition:
Package[apache2] is already defined in file statshub/manifests/init.pp at line 1;
cannot redefine at statshub/manifests/init.pp:2 on node mondrian

Things would get repeated a lot

As a practical example, I refer you to the our lighttpd config.

It has an SSL config file, in which we find this little gem:

ssl.cipher-list = "DHE-RSA-AES256-SHA DHE-RSA-AES128-SHA EDH-RSA-DES-CBC3-SHA
    AES256-SHA AES128-SHA DES-CBC3-SHA DES-CBC3-MD5 RC4-SHA RC4-MD5"

Neat! This implements the current best practices for what ciphers we should accept.

So having this in a base/ module, which is used by everything that needs to spin up a lighttpd, means that all my stuff will be running in the safest way I know how to run it.

The alternative is not very pleasant: I’d need to copy and paste this block in every one of my modules that used lighttpd. I’d need to keep it updated in each one of those files if and when a cipher turns out to be insecure.

Similarly, I can consolidate a lot of intelligence like this:

• making sure log rotation is correct
• making sure compression cache files are cleaned
• making sure monit is configured to restart it if it dies
• making sure file permissions are set up right
• ….

and, should we learn something New And Improved about any of these things, viola, all our useage of that module gets improved.

As an added benefit, this style of consolidation maps onto the way Puppet itself is going.
Much like Perl has the CPAN, Puppet Modules will be getting some new features that allow them to be centralized. Soon we will be able to get “the puppet mysql module” rather than “some guy’s cloned module from a cloned module on github”.

Module Patterns

Because of the above threats and virtues, we want to push as much functionality as we can into base modules.

Basic Design

So how this looks in practice in puppet-speak:

mywebapp/manifests/init.pp

// configure lighttpd module
include lighttpd

// configure apache module
include apache

// configure mysql module
include mysql

// set up crons
cron {
    command => "...."
}

Configuring other Classes

Ok, great, I’ve shipped all that intelligence to another module. But how do I make it work the way I want it to?

Well, we want to configure other classes. There are 3 basic methods to configure a class:

• Create subclasses and only include one or some of them
• Create ‘defines’ that we use from inside classes
• Set variables before you include it

Technique #1: Create subclasses and only include one or some of them

I’ll keep this one simple:

A lot of the time there are several distinct modes you might want to use an app in. For example, there’s a big difference between

include mysql

and

include mysql::server

Technique #2: Create ‘defines’ that we use from inside classes

This technique is the most commonly used one. Many of the application and daemon classes we want to configure have lots of “parts” that can be enabled. Some examples:

• monit config chunks
• apache/lighttpd/nginx sites
• subversion repos

These are best handled with defines. A good full-strength version of this is in our monit config:

define conf ( $source = '', $content = '' ) {
    if $source != '' {
        file { "/etc/monit.d/$name":
            notify => Service["monit"],
            source => $source,
            mode => 644,
            owner => root,
            group => root,
        }
    } else {
        file { "/etc/monit.d/$name":
            notify => Service["monit"],
            content => $content,
            mode => 644,
            owner => root,
            group => root,
        }
    }
}

Notable features:

 define conf ( $source = '', $content = '' ) 

This is useful because we can define a config file via either source or content.

I can call this from another module like:

include monit::common
monit::common::conf { "lighttpd-monit": source => "puppet:///lighttpd/lighthttpd-monitrc" }

or, if I wanted to template it:

include monit::common
monit::common::conf { "apache2": content => template("apache2/apache2-monitrc.erb") }

There’s no reason for us not to actually help people out and write common configs for them. This is easy with extra defines.

define simple_service ($pidname = $name) {
    file { "/etc/monit.d/$name":
        notify => Service["monit"],
        content => template("monit/simple_service.erb"),
        mode => 644,
        owner => root,
        group => root,
    }
}

include monit::common
monit::common::simple_service { "apache2": pidname => "apache2" }

Technique #3: Set variables before you include the class

A good example might be for the mywebapp, I only want apache2 to be listening to the lo loopback interface. This would be a dumb default behavior if someone just did

include apache2

I would probably want it listening on all the public interfaces, by default.

So I can specify configuration variables:

In

site/mywebapp/manifests/init.pp

// we only want to have apache2 listening on the loopback
$apache2_interface = "lo"

include apache2

Then, in

base/apache2/manifests/init.pp

// if someone set this variable before they included our class, use it
if($apache2_interface) {
    $interface = $apache2_interface
} else {
    // by default use '*' which means listen on all interfaces
    $interface = "*"
}

I like the idea of a consistent prefixing of configuration variables — for example, all config variables for module ‘foo’ would be ‘$foo_….’

Sometimes including a class doesn’t make sense unless we have some variable defined at all — there’s no reasonable default.
Let’s say we’re configuring our local syslog — the server we syslog to. Without defining that, it doesn’t make sense to include the module.

We get this pretty much for free, actually. If you specify in your documentation:

You must specify a value for $syslog_server before including this module

base/syslog-client/manifests/init.pp

    file { "/etc/syslog.conf":
        content => template(syslog-client/syslog.conf.erb),
    }

base/syslog-client/templates/syslog.conf.erb

#
# Remote Logging
#

destination d_remote {
        tcp("<%= syslog_server %>", port(514));
};

So if someone tries to

include syslog-client

without defining that variable, puppet will error for you.

Failed to parse template syslog.conf.erb: Could not find value for ‘syslog_server’

Conclusions

I’ll keep this page updated as more useful patterns emerge.

Thinking about decomposing modules by /base and /site is a powerful model already, as it helps develop new variants on ideas in a really rapid way with little to no copy and paste.

I’ve found that my site modules are often in the 4-7 lines long range, and I automatically get a lot of my hard-earned “best ways to do things” along for the ride.

And since I’m not the only one making things around here, everyone else saves time (and avoids some n00b mistakes) by being able to develop things more quickly as well.

To make things easy, I use the current timestamp for this, as I’ve never seen that number go backwards.

Ok, not the normal kind of thing you do with Puppet, but it can be done. We just need to know what time it is in the template.

Thankfully Puppet lets us define custom facts, so here we go…
in the module’s plugins/facter directory, I created ‘epoch_time.rb’.

Facter.add("epoch_time") do
        setcode do
                Time.now.to_i
        end
end

Then I could use that in templates/heartbeat/cib.xml I said

 <cib admin_epoch="<%= epoch_time %>">

Well, that works fine, except for one little issue.

When puppet manages a file it does this:

1. Renders out the templates and takes an md5sum of that
2. Sends that to the client, which checks it’s own md5sum
3. If the sums are different, the client overwrites the file with the old one
4. The client then updates anything ‘subscribed’ to that file (for example, restarting a service.)

So since puppet runs about every 30 minutes, that’s not good. I don’t want to be reloading the CIB database every 30 minutes. That’s bad.

This is what we get:

debug: File[/etc/ha.d/ha.cf]/checksum: Initializing checksum hash
debug: File[/etc/ha.d/ha.cf]: Creating checksum {md5}18530322762561ce59f1d414340b4c43
debug: File[/etc/ha.d/cib.xml]/checksum: Initializing checksum hash
debug: File[/etc/ha.d/cib.xml]: Creating checksum {md5}a02f0ca8a3cce64d7913faa3268e530b
debug: File[/etc/ha.d/cib.xml]/content: Executing 'diff /etc/ha.d/cib.xml /tmp/puppet-diffing20090415-3486-ska653-0'
1c1
< 
---
>  
debug: File[/etc/ha.d/cib.xml]: Changing content
debug: File[/etc/ha.d/cib.xml]: 1 change(s)

So here was my solution, and as inelegant as it is, it pretty much works.

1. Manage a file called ‘cib.xml-puppet’ instead
2. In this file, set admin_epoch=”0″
3. When THAT file changes, do a chained action which sets the epoch time correctly, and writes out the actual cib.xml file
4. Run the command to reload the CIB database in that and only that case.

So the puppet code to make this happen:

        exec { "add-epoch-cib-xml":
                command => "sed 's/admin_epoch=\"0\"/admin_epoch=\"${epoch_time}\"/' /etc/ha.d/cib.xml-puppet > /etc/ha.d/cib.xml && cibadmin -R -x /etc/ha.d/cib.xml",
                path => ["/bin", "/usr/sbin/"],
                subscribe => File["/etc/ha.d/cib.xml-puppet"],
                refreshonly => true,
        }
        file { "/etc/ha.d/cib.xml-puppet" :
                type => 'file',
                ensure => 'present',
                content => template("ha_nfsroot/heartbeat/cib.xml");
        }

So I still get to use my very first custom fact (it gets interpolated into the ‘sed’ command) but I also don’t run that terrifying update every time.

If any puppetmasters or Linux HA gurus want to tell me exactly how I’m doing it wrong I would love to hear that. This certianly doesn’t feel “elegant.”
However, since it feels “functional”, functionality trumps elegance for today.

This little tar contains all the files you need to make this work. Careful with it, as I have provided a minimalist .vimrc so don’t unpack this in your home directory.

puppet_vim.tar.gz