A problem I ran into early when I was bringing services into Puppet was slightly different configurations on servers with different specs. For example, I run Tomcat on three servers but one is also running some other services. On this one server the JVM maximum heap size needs to be lower than on the others, but the rest of the Tomcat configuration is the same. To manage this without making a second class definition I used the template system in Puppet.

There are four steps to making this work. First you need to define a default for the variable. Next you need to write the template. Third, connect the template to a file on the client. Finally override the variable where you need it.

Define a default

The default variable definition goes in the module’s manifest file before the class definition. Putting it before the class definition makes sure that it is in scope for overriding in the node definition. The top of the manifest file will look like this:

$heapsize = 1000

class jvm {
...

Note that variables have leading dollar signs.

Write the template

Puppet uses Ruby’s ERB templating system. The template language is powerful, but I’m only going to cover variable substitution here.

Start with putting the configuration file in the templates subdirectory of the module, i.e. <module name>/templates/<config> so that Puppet knows where to find it. To substitute the variables, use < %= name %>. Here the variable name does not start with a dollar sign. Continuing the earlier example, this is part of our template:

export JAVA_OPTS="-Xmx<%= heapsize %>M"

Connecting the template to a file

Using the template in a file declaration is not as simple as just changing the path from the static source. Instead, you have to use the content parameter and the template function. The parameter to the template function is a weird path fragment: the first segment is the module name, and the rest is the path to your file underneath the templates directory. Continuing our example, assuming that the module is named jvm and the template is at modules/jvm/templates/options.erb, this declaration is in the jvm class:

file {"/usr/local/bin/jvm_options.sh":
mode    => "664",
content => template("jvm/options.erb"),
}

Notice that the name of the template file doesn’t have to match the target name on the client.

Override the variable

Finally, you have to add a line to the node for the server which needs a different configuration. In the node definition before including the class, redefine the variable to what you need. Example:

node "lowmem" {
$heapsize = 750
include jvm
}

Nodes that don’t override the variable will get the default value defined in the module’s manifest file.

Puppet’s templates can do a lot more than simple variable substitution, but this should get you started. Beyond this it’s mostly ERB.

Puppet uses a declarative syntax built on top of ruby for defining rules. The documentation is mediocre at best, so you may struggle at first learning how to write the rules. Just read through the example recipes and test it out with a non-production server. The easiest way I found to test a rule is to run

sudo puppetd --test

on the server that should be getting the configuration. It will tell you there if there are any errors.

The version of puppet in Ubuntu 9.10 doesn’t support defining node names with regular expressions, so you might want to grab the version in Debian sid.

I’m still trying to figure out the best way to split up modules and organize my node definitions, so if you’ve used Puppet leave a comment and let me know what you think.