Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Facts and Templates

EPP Templates

Generate configuration files with Puppet's EPP templates: declare parameters, use tags, loops and conditionals, trim whitespace, call epp() and inline_epp() safely.

Most configuration files are almost the same on every node, with a few values that differ. Writing a whole file resource with a giant content string for each variant gets messy fast. A template keeps the file's shape in one place and inserts the variable parts. Puppet supports two template languages: EPP (Embedded Puppet), which uses Puppet syntax, and ERB, which uses Ruby. New code should use EPP, and the next lesson explains when you still meet ERB.

This lesson teaches the EPP tag syntax, parameter handling, and the two functions that render templates. As the product cannot run here, the code blocks are read-only and the runnable blocks are a small JavaScript stand-in renderer that works like EPP for variables, conditionals and loops.

Where templates live

EPP templates are files with the extension .epp in a module's templates/ directory. You render one with the epp() function, which takes a path of the form <module>/<file>:

PUPPET
file { '/etc/ntp.conf':
  ensure  => file,
  content => epp('ntp/ntp.conf.epp', {
    'servers' => ['0.pool.ntp.org', '1.pool.ntp.org'],
    'driftfile' => '/var/lib/ntp/drift',
  }),
}

The second argument is a hash of parameters. Using it, rather than reading class variables from the template, makes the template a clean unit: it declares what it needs and receives exactly that.

The tags

An EPP file is plain text plus a few tags:

Tag Meaning
<%= expression %> Insert the value of an expression
<% code %> Run Puppet code, insert nothing
<%# comment %> A comment, produces no output
<%- ... -%> Trim the whitespace before (<%-) or after (-%>) the tag
<%% and %%> Literal <% and %> characters

A first template:

TEXT
<%- | String $server_name,
      Integer $port = 80,
      Array[String] $aliases = [],
| -%>
# Managed by Puppet. Do not edit by hand.
server {
  listen <%= $port %>;
  server_name <%= $server_name %><% unless $aliases.empty { %> <%= $aliases.join(' ') %><% } %>;
}

The parameter tag is the first line: <%- | ... | -%>. It lists the template's parameters with their data types and optional defaults, exactly like a class. If a caller passes a wrong type or forgets a required parameter, rendering fails with a clear error. That is the main advantage over ERB.

Conditionals and loops

Inside <% %> you can use if, unless, case and iteration. Loops use the each function with a block:

TEXT
<%- | Array[Hash] $upstreams | -%>
upstream backend {
<% $upstreams.each |$u| { -%>
  server <%= $u['host'] %>:<%= $u['port'] %><% if $u['backup'] { %> backup<% } %>;
<% } -%>
}

Pay attention to the trim markers. Every line of code in a template produces a newline unless the closing tag is -%>. Without the dash you get blank lines in the generated file. Blank lines are harmless in nginx, but they can break stricter formats such as sudoers or a YAML file.

Inline templates and facts

For short strings you can render a template directly from a string with inline_epp():

PUPPET
$banner = inline_epp('Welcome to <%= $host %> (<%= $os %>)', {
  'host' => $facts['networking']['fqdn'],
  'os'   => $facts['os']['name'],
})

Unlike ERB, EPP templates cannot see the variables of the calling class. Only the parameters you pass are visible. A fact such as $facts is the one exception because it is available everywhere, but even then it is cleaner to pass what you need:

PUPPET
epp('profile/motd.epp', { 'fqdn' => $facts['networking']['fqdn'] })

This isolation makes templates easier to test and to move between modules.

Whitespace: the most common headache

Most template bugs are whitespace bugs. Remember three rules:

  1. A tag alone on a line leaves an empty line unless you close it with -%>.
  2. <%- also removes the indentation spaces that precede the tag on that line.
  3. Check the rendered result. On a node, puppet epp render (also usable on a laptop) prints the output for a given parameter set without applying anything:
Terminal
puppet epp validate templates/nginx.conf.epp
puppet epp render --values '{ server_name => "example.org" }' templates/nginx.conf.epp

validate finds syntax errors, and render shows exactly what the node will receive. Use both in your pre-commit checks, see Puppet Lint and Validate.

A stand-in renderer

The following is not the real EPP engine. It is a JavaScript stand-in that supports <%= %>, if blocks and each loops through plain JavaScript, so you can practise thinking in templates: data in, text out, whitespace under control.

JS Stand-in: render a config from parameters

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Remove one -%> from the loop lines and run it again: blank lines appear. That is the whitespace lesson in one experiment.

JS Stand-in: typed parameters with defaults

Press Run (or Ctrl + Enter) to see the console output here.

No output.

flowchart LR
  P["Parameters hash"] --> E["epp() function"]
  T["templates/x.conf.epp"] --> E
  E --> C["Rendered text"]
  C --> F["file resource content"]

A template is a function: parameters in, text out.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which function renders a template stored in a module's templates directory?

    epp('module/file.epp', params) renders a file; inline_epp() renders a string.
  2. 2. What does the first line <%- | String $name | -%> do?

    The parameter tag declares names, types and defaults, and causes an error when a caller passes wrong values.
  3. 3. Why do blank lines appear in the output around loop code?

    The -%> trim marker swallows the newline after the tag.
  4. 4. Can an EPP template read variables of the class that calls it?

    EPP templates are isolated: pass what they need through the parameter hash.
  5. 5. Which command shows what a template will produce without applying it?

    puppet epp render evaluates the template with given values and prints the result.

Summary

  • EPP is the Puppet-syntax template language, files end in .epp and live in templates/.
  • Declare typed parameters in the <%- | ... | -%> tag and pass a hash with epp().
  • Use <%= %> to print, <% %> for logic, and -%>/<%- to control whitespace.
  • Templates cannot see the caller's variables, which keeps them testable.
  • Validate and render templates from the command line before deploying.

Next: ERB Templates and Legacy Code