PUPPET-EPP(8)

📦
version 8.10.0 · 10 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05

💖 NAME 💖

puppet-epp — bestie, this is your direct line to the EPP template parser/renderer. No middleman, no puppet agent drama, just you and the parser. Interact directly with it. Slay.

✨ SYNOPSIS ✨

puppet epp action

🌸 OPTIONS 🌸

okay so first things first: any setting that's valid in the configuration file is also a valid long argument, even if it may or may not be relevant to the action you're doing. Like, server and run_mode are valid settings, so you can pass --server <servername> or --run_mode <runmode> as an argument. Cute, right?

The full list of acceptable parameters lives in the configuration file docs over at https://puppet.com/docs/puppet/latest/configuration.html — go read it, iykyk. And if you want a commented list of literally all the configuration options, just run puppet with --genconfig. Chef's kiss. 💅

  • --render-as FORMAT — the format you want your output rendered in. The most common formats are json, s (that's string), yaml, and console, but other options like dot are sometimes available too. Mix it up bestie.
  • --verbose — whether to log verbosely. Yes queen, tell me everything.
  • --debug — whether to log debug information. For when you need the maximum amount of yapping. 🦋

🎀 ACTIONS 🎀

💜 dump

Outputs a dump of the internal template parse tree for debugging.

SYNOPSIS

puppet epp dump [--e source] [--[no-]validate] [--format old, pn, or json] [--pretty] [--[no-]header] [--format old|pn|json] [--pretty] { -e source | [templates ...] }

DESCRIPTION

The dump action parses and validates the EPP syntax and then dumps the resulting AST model in a human readable (but not necessarily an easy to understand) format. It's giving ✨mystery✨ but make it parseable.

You control the output format with --format old|pn|json, where:

  • old is the default, but it's now deprecated format and is not API. 🫠
  • pn is the Puppet Extended S-Expression Notation. Fancy!
  • json outputs the same graph as pn, just with JSON syntax. Bestie-friendly. 💖

The output gets "pretty printed" when you give the option --pretty together with --format pn or --format json. Heads up though: this option has no effect on the old format. Not me giving old the silent treatment.

This command accepts one or more templates (.epp files), or an -e followed by the template source text. The templates you hand it can be paths to template files, or references to templates in modules when given on the form modulename/template-name.epp. And if you give no arguments at all? It reads stdin (unless stdin is attached to a terminal, in which case, nope).

If multiple templates are given, they get separated with a header indicating the name of the template. You can suppress that with --no-header. And lowkey important: the option --[no-]header has no effect when a single template is dumped. One template, no drama.

When you're debugging the epp parser itself, it may be useful to suppress the validation step with the --no-validate option so you can observe what the parser actually produced from the given source. Chaos mode, but intentional. 🔥

Also, this command ignores the --render-as setting/option. It said what it said.

OPTIONS

  • --e <source> — Dump one epp source expression given on the command line.
  • --format <old, pn, or json> — Get result in old (deprecated format), pn (new format), or json (new format in JSON).
  • --[no-]header — Whether or not to show a file name header between files.
  • --pretty — Pretty print output. Only applicable together with --format pn or json
  • --[no-]validate — Whether or not to validate the parsed result, if no-validate only syntax errors are reported.

RETURNS

A dump of the resulting AST model — unless there are syntax or validation errors, in which case, 💀.

🦋 render

Renders an epp template as text. This is the main character of the actions, fr fr.

SYNOPSIS

puppet epp render [--node node_name] [--e source] [--values values_hash] [--values_file pp_or_yaml_file] [--facts facts_file] [--[no-]header] -e source | [templates ...]

DESCRIPTION

This action renders one or more EPP templates. Obsessed.

The command accepts one or more templates (.epp files), given the same way as templates are given to the puppet epp function (a full path, or a relative reference on the form modulename/template-name.epp), or as a relative path.args In case the given path matches both a modulename/template and a file, the template from the module is used. Module wins, periodt.

An inline_epp equivalent can also be performed by giving the template after an -e, or by piping the EPP source text to the command. Pipe it like it's hot. 🌈

Values to the template can be defined using the Puppet Language on the command line with --values, or in a .pp or .yaml file referenced with --values_file. If you specify both, the result is merged with --values having higher precedence. Your CLI values are the CEO.

The --values option allows a Puppet Language sequence of expressions to be defined on the command line the same way as it may be given in a .pp file referenced with --values_file. It may set variable values (which then become available in the template), and it must produce either undef or a Hash of values (that hash may be empty, no pressure). Producing undef simulates that the template is called without an arguments hash and thus only references variables in its outer scope. When a hash is given, a template is limited to seeing only the global scope. So basically you can simulate the different types of calls to the epp and inline_epp functions, with or without a given hash. Simulation era. ✨

Not me forgetting this one: if variables are given, they are always available in this simulation. So if you want to test that the template only references variables given as arguments, produce a hash in --values or the --values_file, do not specify any variables that are not global, and turn on the --strict_variables setting. Do that and you'll know for real.

If multiple templates are given, the same set of values is given to each template. If both --values and --value_file are used, the --values are merged on top of those given in the file.

When multiple templates are rendered, a separating header is output between the templates showing the name of the template before the output. That header output can be turned off with --no-header. And doing that also concatenates the template results without any added newline separators. Zero spacing, zero chill.

Facts from the node where the command is being run are used by default.args Facts can be obtained for other nodes if they have called in and reported their facts, by using the --node <nodename> flag. Look at them calling in. 👑

Overriding node facts as well as adding additional facts can be given in a .yaml or .json file and referencing it with the --facts option. (You can grab values in yaml format directly from facter, or from puppet for a given node.) Note that it is not possible to simulate the reserved variable name $facts in any other way. That's the only door in.

Real talk: it is not possible to set variables using the Puppet Language that have the same names as facts, because this results in an error — "attempt to redefine a variable" — since facts are set first. Facts said first come first served.

Exits with 0 if there were no validation errors. On errors, no rendered output is produced for that template file.

When designing EPP templates, it is strongly recommended to define all template arguments in the template, and to give them in a hash when calling epp or inline_epp, and to use as few global variables as possible — preferably only the $facts hash. This makes templates more free standing, easier to reuse, and easier to test. Bestie, do this. It's the glow-up your templates deserve. 💅

OPTIONS

  • --e <source> — Render one inline epp template given on the command line.
  • --facts <facts_file> — A .yaml or .json file containing a hash of facts made available in $facts and $trusted
  • --[no-]header — Whether or not to show a file name header between rendered results.
  • --node <node_name> — The name of the node for which facts are obtained. Defaults to facts for the local node.
  • --values <values_hash> — A Hash in Puppet DSL form given as arguments to the template being rendered.
  • --values_file <pp_or_yaml_file> — A .pp or .yaml file that is processed to produce a hash of values for the template.

RETURNS

A rendered result of one or more given templates. Gorgeous. 🎀

🧚 validate

Validate the syntax of one or more EPP templates. The vibe check of actions.

SYNOPSIS

puppet epp validate [--[no-]continue_on_error] [template] [template ...]

DESCRIPTION

This action validates EPP syntax without producing any output. Silent but judging. 🙈

When validating, multiple issues per file are reported, up to the settings of max_error and max_warnings. The processing stops after having reported issues for the first encountered file with errors — unless you give the option --continue_on_error. Then it keeps going, icon behavior.

Files can be given using the modulename/template.epp style to look up the template from a module, or be given as a reference to a file. If the reference to a file can be resolved against a template in a module, the module version wins — so in that case, use an absolute path to reference the template file if the module version is not what you wanted. Choose your fighter.

Exits with 0 if there were no validation errors. Clean run, clean conscience. ✨

OPTIONS

  • --[no-]continue_on_error — Whether or not to continue after errors are reported for a template.

RETURNS

Nothing, or encountered syntax errors. That's it, that's the whole return. 💀

🌸 to be continued, bestie… 🌸

✨ EXAMPLES ✨

okay bestie this is the part where it all clicks, fr fr. real commands, real output vibes, no cap 💖

💅 render

Render the template in module mymodule called mytemplate.epp, and give it two arguments a and b:

$ puppet epp render mymodule/mytemplate.epp --values ´{a => 10, b => 20}´

Render a template using an absolute path:

$ puppet epp render /tmp/testing/mytemplate.epp --values ´{a => 10, b => 20}´

Render a template with data from a .pp file:

$ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp

Render a template with data from a .pp file and override one value on the command line:

$ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp --values ´{a=>10}´

Render from STDIN:

$ cat template.epp | puppet epp render --values ´{a => 10, b => 20}´

Set variables in a .pp file and render a template that uses variable references:

# data.pp file
$greeted = ´a global var´
undef

$ puppet epp render -e ´hello <%= $greeted %>´ --values_file data.pp

Render a template that outputs a fact:

$ facter --yaml > data.yaml
$ puppet epp render -e ´<% $facts[osfamily] %>´ --facts data.yaml
🌸 notice how undef sits at the end of that data.pp file? that's not me being quirky, that's literally in the example, so keep it there bestie.

🦋 validate

Validate the template template.epp in module mymodule:

$ puppet epp validate mymodule/template.epp

Validate two arbitrary template files:

$ puppet epp validate mymodule/template1.epp yourmodule/something.epp

Validate a template somewhere in the file system:

  $ puppet epp validate /tmp/testing/template1.epp

Validate a template against a file relative to the current directory:

 $ puppet epp validate template1.epp
 $ puppet epp validate ./template1.epp

Validate from STDIN:

$ cat template.epp | puppet epp validate

Continue on error to see errors for all templates:

$ puppet epp validate mymodule/template1.epp mymodule/template2.epp --continue_on_error

Copyright 2014 by Puppet Inc. Apache 2 license; see COPYING

and that's the whole page bestie, you made it to the end, main character energy fr 🎀👑

Puppet, Inc. — September 2024 — PUPPET-EPP(8) 💖 that's the source, the version vibe, and the date stamp, all wrapped up with a bow. go forth and render responsibly, ily 🫶✨
📦 where this page comes from