Creating templates using Embedded Ruby

Expression-printing tags

<%= @networking.fqdn %>

For example, to insert the value of the fqdn and hostname facts in an ERB template for an Apache config file:

ServerName <%= @networking.fqdn %>
ServerAlias <%= @networking.hostname %>

Non-printing tags

For example, to insert text only if a certain variable was set, write:

<% if @broadcastclient == true -%>
broadcastclient
<% end -%>

Expressions in non-printing tags don’t have to resolve to a value or be a complete statement, but the tag must close at a place where it would be legal to write another expression. For example, this doesn't work:

<%# Syntax error: %>
<% @servers.each -%>
# some server
<% do |server| %>server <%= server %>
<% end -%>

You must keep do |server| inside the first tag, because you can’t insert an arbitrary statement between a function call and its required block.

Comment tags

<%# This is a comment. %>

Literal tag delimiters

If you need the template’s final output to contain a literal <% or %>, you can escape the characters as <%% or %%>. The first literal tag is taken, and the rest of the line is treated as a literal. This means that <%% Test %%> in an ERB template would turn out as <% Test %%>, not <% Test %>.

@variable

All variables in the current scope (including global variables) are passed to templates as Ruby instance variables, which begin with “at” signs (@). If you can access a variable by its short name in the surrounding manifest, you can access it in the template by replacing its $ sign with an @, so that $os becomes @os, and $trusted becomes @trusted.

This is the most legible way to access variables, but it doesn’t support variables from other scopes. For that, you need to use the scope object.

scope['variable'] or scope.lookupvar('variable')

Puppet also passes templates an object called scope, which can access all variables (including out-of-scope variables) with a hash-style access expression. For example, to access $ntp::tinker you would use scope['ntp::tinker'].

Another way to use the scope object is to call its lookupvar method and pass the variable’s name as its argument, as in scope.lookupvar('ntp::tinker'). This is exactly equivalent to the above, if slightly less convenient. This usage predates the hash-style indexing added in Puppet 3.0.

Puppet data types in Ruby

Using if statements

<% if <CONDITION> %> text goes here <% end %>

<% if @broadcast != "NONE" %>broadcast <%= @broadcast %><% end %>

if <CONDITION>
  ... code ...
elsif <CONDITION>
  ... other code ...
end

Using iteration

Ruby lets you iterate over arrays and hashes with the each method. This method takes a block of code and executes it one time for each element in the array or hash. In a template, untagged text is treated as part of the code that gets repeated. You can think of literal text as an instruction, telling the evaluator to insert that text into the final output.

<% @values.each do |val| -%>
Some stuff with <%= val %>
<% end -%>

Some stuff with one
Some stuff with two

Manipulating data

Your templates generally use data from Puppet variables. These values almost always be strings, numbers, arrays, and hashes.

These become the equivalent Ruby objects when you access them from an ERB template.

For information about the ways you can transform these objects, see the Ruby documentation for strings, integers, arrays, and hashes.

Also, note that the special undef value in Puppet becomes the special nil value in Ruby in ERB templates.

ERB validation

erb -P -x -T '-' example.erb | ruby -c

validate_erb() {
  erb -P -x -T '-' $1 | ruby -c
}

Evaluating ERB templates that are in a template file

Put template files in the templates directory of a module. ERB files use the .erb extension.

# template(<FILE REFERENCE>, [<ADDITIONAL FILES>, ...])
file { '/etc/ntp.conf':
  ensure  => file,
  content => template('ntp/ntp.conf.erb'),
  # Loads /etc/puppetlabs/code/environments/production/modules/ntp/templates/ntp.conf.erb
}

The first argument to the function is the file reference: a string in the form '<MODULE>/<FILE>', which loads <FILE> from <MODULE>’s templates directory. For example, the file reference activemq/amq/activemq.xml.erb loads the <MODULES DIRECTORY>/activemq/templates/amq/activemq.xml.erb file.

The template function can take any number of additional template files, and concatenate their outputs together to produce the final string.

Evaluating ERB template strings

If you have a string value that contains template content, you can evaluate it with the inline_template function.

In older versions of Puppet, inline templates were mostly used to get around limitations — tiny Ruby fragments were useful for transforming and manipulating data before Puppet had iteration functions like map or puppetlabs/stdlib functions like chomp and keys.

In modern versions of Puppet, inline templates are usable in some of the same situations template files are. Because the heredoc syntax makes it easy to write large and complicated strings in a manifest, you can use inline_erb to reduce the number of files needed for a simple module that manages a small config file.

For example:

$ntp_conf_template = @(END)
...template content goes here...
END

# inline_template(<TEMPLATE STRING>, [<ADDITIONAL STRINGS>, ...])
file { '/etc/ntp.conf':
  ensure  => file,
  content => inline_template($ntp_conf_template),
}

The inline_template function can take any number of additional template strings, and concatenate their outputs together to produce the final value.