The hiera.yaml config file

Important: This is old documentation; read the new version instead.

Puppet 4.9 and later use Hiera 5, and its documentation is in the Puppet reference manual. See the following pages for more info:

• What is Hiera? How do hierarchies and layers work?
• Migrating existing Hiera configurations to Hiera 5
• Automatic class parameter lookup

We are preserving this Hiera 3 documentation for historical reference, but the Hiera 5 documentation is a complete replacement for it.

Hiera’s config file is usually referred to as hiera.yaml. Use this file to configure the hierarchy, which backend(s) to use, and settings for each backend.

Hiera will fail with an error if the config file can’t be found, although an empty config file is allowed.

Location

By default, the config file is:

• /etc/puppetlabs/puppet/hiera.yaml on *nix systems
• COMMON_APPDATA\PuppetLabs\puppet\hiera.yaml on Windows

Changing the config file location

You can specify a different config file for Hiera via Puppet, the command line, or Ruby code.

In Puppet

You can use the hiera_config setting in puppet.conf to specify a different config file.

From the command line

You can specify a different config file with the -c (--config) option.

From Ruby code

You can specify a different config file or a hash of settings when calling Hiera.new.

Format

Hiera’s config file must be a YAML hash. The file must be valid YAML, but may contain no data.

Each top-level key in the hash must be a Ruby symbol with a colon (:) prefix. The available settings are listed below, under “Global Settings” and “Backend-Specific Settings”.

Example config file

---
:backends:
  - yaml
  - json
:yaml:
  :datadir: "/etc/puppetlabs/code/environments/%{::environment}/hieradata"
:json:
  :datadir: "/etc/puppetlabs/code/environments/%{::environment}/hieradata"
:hierarchy:
  - "nodes/%{::trusted.certname}"
  - "virtual/%{::virtual}"
  - "common"

Default config values

If the config file exists but has no data, the default settings will be equivalent to the following:

---
:backends: yaml
:yaml:
  # on *nix:
  :datadir: "/etc/puppetlabs/code/environments/%{environment}/hieradata"
  # on Windows:
  :datadir: "C:\ProgramData\PuppetLabs\code\environments\%{environment}\hieradata"
:hierarchy:
  - "nodes/%{::trusted.certname}"
  - "common"
:logger: console
:merge_behavior: native
:deep_merge_options: {}

Global settings

The Hiera config file may contain any the following settings. If absent, they will have default values. Note that each setting must be a Ruby symbol with a colon (:) prefix.

:hierarchy

Must be a string or an array of strings, where each string is the name of a static or dynamic data source. (A dynamic source is simply one that contains a %{variable} interpolation token. See “Creating Hierarchies” for more details.)

The data sources in the hierarchy are checked in order, top to bottom.

Default value: ["nodes/%{::trusted.certname}", "common"]

:backends

Must be a string or an array of strings, where each string is the name of an available Hiera backend. The built-in backends are yaml and json. Additional backends are available as add-ons.

Custom backends: See “Writing Custom Backends” for details on writing new backend. Custom backends can interface with nearly any existing data store.

The list of backends is processed in order: in the example above, Hiera would check the entire hierarchy in the yaml backend before starting again with the json backend.

Default value: "yaml"

:logger

Must be the name of an available logger, as a string.

Loggers only control where warnings and debug messages are routed. You can use one of the built-in loggers, or write your own. The built-in loggers are:

• console (messages go directly to STDERR)
• puppet (messages go to Puppet’s logging system)
• noop (messages are silenced)

Custom loggers: You can make your own logger by providing a class called, e.g., Hiera::Foo_logger (in which case Hiera’s internal name for the logger would be foo), and giving it class methods called warn and debug, each of which should accept a single string.

Default value: "console"; note that Puppet overrides this and sets it to "puppet", regardless of what’s in the config file.

:merge_behavior

Must be one of the following:

• native (default) — merge top-level keys only.
• deep — merge recursively; in the event of conflicting keys, allow lower priority values to win. You almost never want this.
• deeper — merge recursively; in the event of a conflict, allow higher priority values to win.

Anything but native requires the deep_merge Ruby gem to be installed. If you’re using Puppet Server, you’ll need to use the puppetserver gem command to install the gem.

For more details about hash merge lookup strategies, see “Hash Merge” and “Deep Merging in Hiera”.

:deep_merge_options

Must be a hash of options to pass to the deep merge gem, if :merge_behavior is set to deeper or deep. For example:

:merge_behavior: deeper
:deep_merge_options:
  :knockout_prefix: '--'

Available options are documented in the deep_merge gem.

Default value: An empty hash of options.

Backend-specific settings

Any backend can define its own settings and read them from Hiera’s config file. If present, the value of a given backend’s key must be a hash, whose keys are the settings it uses.

The following settings are available for the built-in backends:

:yaml and :json

:datadir

The directory in which to find data source files. This must be a string.

You can interpolate variables into the datadir using %{variable} interpolation tokens. This allows you to, for example, point it at "/etc/puppetlabs/code/hieradata/%{::environment}" to keep your production and development data entirely separate.

Default value: "/etc/puppetlabs/code/environments/%{environment}/hieradata" on *nix, and "C:\ProgramData\PuppetLabs\code\environments\%{environment}\hieradata" on Windows.