The default configuration

These defaults are only used if the file is present and specifies version: 5. If hiera.yaml is absent, it disables Hiera for that layer; if it specifies a different version, different defaults might apply.

The defaults key

The defaults key can set default values for the backend and datadir keys, which lets you omit those keys in your hierarchy levels.

The value of defaults must be a hash, which can have up to three keys:

datadir — A default value for datadir, used for any file-based hierarchy level that doesn’t specify its own.

A backend key, used for any hierarchy level that doesn’t specify its own. This must be one of:

data_hash

lookup_key

data_dig

hiera3_backend (global layer only)

options — A default value for options, used for any hierarchy level that doesn’t specify its own.

For the built-in backends (YAML, JSON, and HOCON), the key is always data_hash and the value is one of yaml_data, json_data, or hocon_data. If you want to set a custom backend as the default, you’ll need to check that backend’s documentation.

The hierarchy key

The hierarchy key configures the levels of the hierarchy.

The default_hierarchy key is a top-level key like the hierarchy key. It works exactly like the hierarchy key, but its values are used only if the normal hierarchy entries in the same module, or any of the higher precedence layers (environment or global) does not result in a value. Within this default hierarchy, the normal merging rules apply.
However, the default_hierarchy is not permitted in environment or global layers.

For an explanation of how hierarchies work, see How hierarchies work. This page focuses on the syntax.

name — A name for this level, shown to humans in debug messages and --explain output.

path, paths, glob, globs, or mapped_paths (choose one) — The data file(s) to use for this hierarchy level.

These paths are relative to the datadir, they support variable interpolation, and they require a file extension. See below for more details.

data_hash — Which backend to use; can be omitted if you set a default. The value must be one of the following:

yaml_data for YAML.

json_data for JSON.

hocon_data for HOCON.

datadir — The directory where data files are kept; can be omitted if you set a default.

This path is relative to hiera.yaml’s directory: if the config file is at /etc/puppetlabs/code/environments/production/hiera.yaml and the datadir is set to data, the full path to the data directory is /etc/puppetlabs/code/environments/production/data.

In the global layer, you can optionally set the datadir to an absolute path; in the other layers, it must always be relative.

Specifying file paths

There are four options for specifying a file path. You can only use one of these keys in a given hierarchy level.

Key

Data type

Expected value

path

String

One file path.

paths

Array

Any number of file paths. This acts like a sub-hierarchy: if multiple files exist, Hiera searches all of them, in the order in which they’re written.

glob

String

One shell-like glob pattern, which might match any number of files. If multiple files are found, Hiera searches all of them in alphanumerical order.

globs

Array

Any number of shell-like glob patterns. If multiple files are found, Hiera searches all of them in alphanumerical order (ignoring the order of the globs).

mapped_paths

Array or Hash

A fact that is a collection (array or hash) of values. Hiera expands these values to produce an array of paths.

Explicit file extensions are required — use something like common.yaml, not just common. (This is a change from prior versions of hiera.yaml, which magically guessed file extensions.)

File paths are relative to the datadir: if the full datadir is /etc/puppetlabs/code/environments/production/data and the file path is set to "nodes/%{trusted.certname}.yaml", the full path to the file is /etc/puppetlabs/code/environments/production/data/nodes/<NODE NAME>.yaml. (Absolute file paths are also allowed, but are rarely practical.)

Whichever approach you choose, most of your hierarchy levels should interpolate variables into the path, since that’s what makes Hiera useful. For more information about crafting useful hierarchies, see How hierarchies work.

Within hiera.yaml, the eyaml backend mostly resembles the standard built-in backends, with a few differences. (It uses lookup_key instead of data_hash, and requires an options key to locate decryption keys.)

Important: To use the eyaml backend, you must have the hiera-eyaml gem installed where Puppet can use it. You’ll need to install it twice:

To enable eyaml on the command line and with puppet apply, use sudo /opt/puppetlabs/puppet/bin/gem install hiera-eyaml.

Each eyaml hierarchy level needs the following keys:

name — A name for this level, shown to humans in debug messages and --explain output.

lookup_key — Which backend to use. The value must be eyaml_lookup_key. (Use this instead of the data_hash setting.)

path, paths, glob, or globs (choose one) — The data file(s) to use for this hierarchy level.

These paths are relative to the datadir, they support variable interpolation, and they require a file extension. (In this case, you’ll usually use .eyaml.) They work the same way they do for the standard backends.

datadir — The directory where data files are kept; can be omitted if you set a default. Works the same way it does for the standard backends.

options — A hash of options specific to hiera-eyaml, mostly used to configure decryption. For the default encryption method, this hash must have the following keys:

pkcs7_private_key — The location of the PKCS7 private key to use.

pkcs7_public_key — The location of the PKCS7 public key to use.

If you use an alternate encryption plugin, its docs should specify which options to set. You’ll usually set an encrypt_method option, plus some plugin-specific options to replace the pkcs7_ ones.

Note that you can use normal strings as keys in this hash; you don’t need to use :symbols.

Configuring a hierarchy level (legacy Hiera 3 backends)

Note: This feature is a temporary measure, to let you start using Hiera’s new features while waiting for backend updates. We expect to remove Hiera 3 backend support in Puppet 6.

If you rely on custom data backends designed for Hiera 3, you can use them in your global hierarchy. (They are not supported at the environment or module layers.)

Each legacy hierarchy level needs the following keys:

name — A name for this level, shown to humans in debug messages and --explain output.

path or paths (choose one) — The data file(s) to use for this hierarchy level.

For file-based backends, include the file extension, even though you would have omitted it in the v3 hiera.yaml file.

For non-file backends, don’t use a file extension.

hiera3_backend — The legacy backend to use. This is the same name you’d use in the v3 config file’s :backends key.

datadir — The directory where data files are kept. Only set this if your backend required a :datadir setting in its backend-specific options.

This path is relative to hiera.yaml’s directory: if the config file is at /etc/puppetlabs/code/environments/production/hiera.yaml and the datadir is set to data, the full path to the data directory is /etc/puppetlabs/code/environments/production/data.

In the global layer, you can optionally set the datadir to an absolute path.

options — A hash, with any backend-specific options (other than datadir) required by your backend. In the v3 config, this would have been in a top-level key named after the backend.

You can use normal strings as keys; Hiera automatically converts them to symbols for the backend.

Configuring a hierarchy level (general format)

Your backend’s documentation should explain how to configure hierarchy levels for it, so you won’t usually have to consult these rules. They’re presented here as an aid for backend authors, and as a fallback in case of incomplete backend docs.

Each hierarchy level is represented by a hash, which needs the following keys:

name — A name for this level, shown to humans in debug messages and --explain output.

A backend key, which must be one of:

data_hash

lookup_key

data_dig

hiera3_backend (global layer only)

The backend determines which key you must use, so you’ll have to check its documentation. In general, file-based backends usually use data_hash, fast non-file backends usually use lookup_key, and slow non-file backends usually use data_dig.

A path or URI key (only if required by the backend). These keys support variable interpolation. The following path/URI keys are available:

path

paths

glob

globs

uri

uris

path(s) and glob(s) work the same way they do for the built-in backends. Hiera handles the work of locating files, so any backend that supports path automatically supports paths, glob, and globs.

uri (string) and uris (array) can represent any kind of data source. Hiera doesn’t ensure URIs are resolvable before calling the backend, and doesn’t need to understand any given URI schema.

It’s also possible for a backend to omit the path/URI key, and rely wholly on the options key to locate its data.

datadir — The directory where data files are kept; the path is relative to hiera.yaml’s directory. Only required if the backend uses the path(s) and glob(s) keys, and can be omitted if you set a default.

options — A hash of arbitrary extra options for the backend; for example, database credentials or the location of a decryption key. See the backend’s documentation for details. All values in the options hash support variable interpolation.