Config file syntax

The hiera.yaml file is a YAML file, containing a hash with up to four top-level keys.

The following keys are in a hiera.yaml file:

• version - Required. Must be the number 5, with no quotes.
• defaults - A hash, which can set a default datadir, backend, and options for hierarchy levels.
• hierarchy - An array of hashes, which configures the levels of the hierarchy.
• default_hierarchy - An array of hashes, which sets a default hierarchy to be used only if the normal hierarchy entries do not result in a value. Only allowed in a module's hiera.yaml.

version: 5
defaults:  # Used for any hierarchy level that omits these keys.
  datadir: data         # This path is relative to hiera.yaml's directory.
  data_hash: yaml_data  # Use the built-in YAML backend.

hierarchy:
  - name: "Per-node data"                   # Human-readable name.
    path: "nodes/%{trusted.certname}.yaml"  # File path, relative to datadir.
                                   # ^^^ IMPORTANT: include the file extension!

  - name: "Per-datacenter business group data" # Uses custom facts.
    path: "location/%{facts.whereami}/%{facts.group}.yaml"

  - name: "Global business group data"
    path: "groups/%{facts.group}.yaml"

  - name: "Per-datacenter secret data (encrypted)"
    lookup_key: eyaml_lookup_key   # Uses non-default backend.
    path: "secrets/nodes/%{trusted.certname}.eyaml"
    options:
      pkcs7_private_key: /etc/puppetlabs/puppet/eyaml/private_key.pkcs7.pem
      pkcs7_public_key:  /etc/puppetlabs/puppet/eyaml/public_key.pkcs7.pem

  - name: "Per-OS defaults"
    path: "os/%{facts.os.family}.yaml"

  - name: "Common data"
    path: "common.yaml"

The default configuration

If you omit the hierarchy or defaults keys, Hiera uses the following default values.

version: 5
hierarchy:
  - name: Common
    path: common.yaml
defaults:
  data_hash: yaml_data
  datadir: data

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 apply.

The defaults key

The defaults key sets default values for the lookup function 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, options, and one of the mutually exclusive lookup function keys.

datadir: a default value for datadir, used for any file-based hierarchy level that doesn't specify its own. If not given, the datadir is the directory data in the same directory as the hiera.yaml configuration file.

options: a default value for options, used for any hierarchy level that does not specify its own.

The lookup function keys: used for any hierarchy level that doesn't specify its own. This must be one of:

• data_hash - produces a hash of key-value pairs (typically from a data file)
• lookup_key - produces values key by key (typically for a custom data provider)
• data_dig - produces values key by key (for a more advanced data provider)
• hiera3_backend - a data provider that calls out to a legacy Hiera 3 backend (global layer only).

For the built-in data providers — YAML, JSON, and HOCON — the key is always data_hash and the value is one of yaml_data, json_data, or hocon_data. To set a custom data provider as the default, see the data provider documentation. Whichever key you use, the value must be the name of the custom Puppet function that implements the lookup function.

The hierarchy key

The hierarchy key configures the levels of the hierarchy. The value of hierarchy must be an array of hashes.

Indent the hash's keys by four spaces, so they line up with the first key. Put an empty line between hashes, to visually distinguish them. For example:

hierarchy:
  - name: "Per-node data"
    path: "nodes/%{trusted.certname}.yaml"

  - name: "Per-datacenter business group data"
    path: "location/%{facts.whereami}/%{facts.group}.yaml"

The default_hierarchy key

The default_hierarchy key is a top-level key. It is initiated when, and only when, the lookup in the regular hierarchy does not find a value. Within this default hierarchy, the normal merging rules apply. The default_hierarchy is not permitted in environment or global layers.

If lookup_options is used, the values found in the regular hierarchy have no effect on the values found in the default_hierarchy, and vice versa. A merge parameter, given in a call to lookup, is only used in the regular hierarchy. It does not affect how a value in the default hierarchy is assembled. The only way to influence that, is to use lookup_options, found in the default hierarchy.

For more information about the YAML file, see YAML.

Related information

Hiera hierarchies