Hiera 2: Release Notes

This version of Hiera is not included in Puppet Enterprise. The latest version of PE includes Hiera 3.1. A newer version is available; see the version menu above for details.

Note: We’ve released a major update to Hiera called Hiera 5.

It’s built into Puppet 4.9 and higher, and includes features like per-environment hierarchies, module data, simplified custom backends, improved debugging with puppet lookup --explain, and more.

As part of this update, we’ve moved Hiera’s documentation into the Puppet reference manual. Once you’ve upgraded to Puppet 4.9 or higher, see the following pages for more info about the new Hiera:

Hiera 2.0.1

Released April 13, 2015

This release is identical to 2.0.0. We only changed some tests and packaging data.

Hiera 2.0.0

Released March 25, 2015.

Hiera 2.0.0 is a new major version of Hiera, which includes several new features and one breaking change. Please read the section below labeled “BREAK,” because you may need to edit your configuration and/or move some files around.

Hiera 2.0.0 is available as a gem (run gem install hiera) or a tarball (download from http://downloads.puppetlabs.com/hiera/). Official delivery of Hiera 2.0.0 is via the puppet-agent package with Puppet 4, which was released on 13 April 2015.

BREAK: New Default Locations for Config File and Data Directory

This release changes the default locations for the config file and the data directory used by the YAML and JSON backends. If you were relying on the old default behavior, you’ll need to either move your files or configure Hiera to use non-default locations.

On *nix systems:

  • hiera.yaml is now at /etc/puppetlabs/code/hiera.yaml
    • (was: /etc/hiera.yaml or /etc/puppetlabs/puppet/hiera.yaml or /etc/puppet/hiera.yaml)
  • :datadir is now at /etc/puppetlabs/code/hieradata/
    • (was: /var/lib/hiera)

On Windows systems:

  • hiera.yaml is now at <COMMON_APPDATA>\PuppetLabs\code\hiera.yaml
    • (was: <COMMON_APPDATA>\PuppetLabs\puppet\etc\hiera.yaml)
  • :datadir is now at <COMMON_APPDATA>\PuppetLabs\code\hieradata
    • (was: <COMMON_APPDATA>\PuppetLabs\Hiera\var)

Also, Hiera will now always use the same default location, whether you’re using it from the CLI, as a Ruby library, or via Puppet.

API Change for Custom Backends (Backwards Compatible)

This release makes several changes to the custom backends API, in order to fix infinite interpolation recursion, forgotten order overrides, and other problems.

These changes are optional for custom backends: they’ll continue to work without an update, but you can get improved behavior by updating.

To update to the new API, you’ll need to:

  • Change your backend’s lookup method to accept an additional argument at the end, named context.
    • When the lookup method is called, this context hash will contain a key named :recurse_guard. You never need to call methods on this object, but you’ll need to pass it along later.
  • Change your lookup method to call throw(:no_such_key) when it doesn’t find a match, instead of returning nil. (nil is now a normal value that backends can return.)
  • If your lookup method uses the value of its resolution_type argument to switch between behaviors, be aware that in addition to its symbol values, it may also now be a Hash containing, at minimum, a :behavior key. Your backend should treat this the same as if it received a resolution_type value of :hash.
  • Change any calls to the Backend.parse_answer or Backend.parse_string helper methods. Whenever your backend calls these methods:
    • It should always provide an explicit value for the extra_data argument. Use an empty hash {} if you’re not providing any extra data.
    • It should provide an additional argument at the end. This argument should be a hash with two keys:
      • :recurse_guard — the value should be context[:recurse_guard].
      • :order_override — the value should be the order_override value that was passed to your lookup method (as its third argument).
  • Change any calls to the Backend.merge_answer helper method. Your backend should pass the value of its resolution_type argument as a third argument to merge_answer.

  • HI-328: Hiera does not detect interpolation recursion
  • HI-304: Override does not propagate to hiera() function in interpolation tokens
  • HI-337: Hiera Backends should distinguish key with null value from key not found
  • HI-348: Enable deep-merge options to be passed in lookup

New Feature: Lookups Can Index Into Data Structures

Previously, you could only look up top-level keys in Hiera, and it would return the entire value of that key. Sometimes, especially when the value was a large hash or array, that would be more data than you wanted, and you would have to manipulate the data structure after receiving the entire thing.

Now, you can use sub-keys to request only part of a data structure. For example, hiera('user.uid') or hiera('user.groups.0').

For details, see the docs about performing lookups.

New Feature: literal() Function — Escape % Signs in Data

Some pieces of data need to include literal text that looks like a Hiera interpolation token, without triggering interpolation. This was previously impossible, but you can now escape percent signs to put things like Apache variables in Hiera data. You’ll need to escape each literal % with %{literal('%')}.

So to get a final string that looks like this:


Write the Hiera value like this:


For more info, see the docs about lookup functions in interpolation tokens.

New Feature: alias() Function — Make Key an Alias For Other Key

Previously, you could re-use strings from other pieces of Hiera data by using the hiera() lookup function in an interpolation token, but you couldn’t re-use hashes or arrays. Now, Hiera will treat a string containing an %{alias('key_name')} token as the value of key_name, no matter what kind of data it is. For more details, see the docs about lookup functions in interpolation tokens.

New Feature: Pass Options to Deep Merge Gem

The deep_merge gem has several options that can modify its behavior, but Hiera was unable to take advantage of them. Now, there’s a new setting in hiera.yaml that can pass options to the gem. For details, see the configuration page and the docs about hash merge lookups.

New Feature: Output YAML on Command Line

You can now run hiera -f yaml to get YAML-formatted data.

Bug Fixes

Not Quite Bug Fixes

Puppet 4 will pass Hiera a new pseudo-variable named calling_class_path, which is the name of the current class with any occurrences of :: replaced with /.

We introduced this because : is an illegal character in Windows and OS X file names, and people trying to use calling_class in their hierarchies to create class-specific data sources were running into trouble. Now, you can use calling_class_path in the hierarchy to convert namespaced class names into a directory structure. (But only in Puppet 4 and higher.)

This isn’t a change to Hiera itself, but putting it in the Hiera release notes seems like the best way to point it out to the people who want it.

Operating System Support and Packaging

This release included some routine work to improve support on new platforms and drop old ones.

↑ Back to top