Hiera is Puppet’s built-in key/value data lookup system. By default, it uses simple YAML or JSON files, although you can extend it to work with almost any data source. Almost every successful Puppet user relies on it heavily, and you should too.
Puppet’s primary strength is in reusable code. But code that serves many needs has to be configurable — site-specific information should usually be in configuration data, rather than in the code itself.
Hiera is the most flexible way to get configuration data into Puppet. Puppet automatically searches Hiera for class parameters, so you can use Hiera to configure any module.
Hiera’s hierarchical lookups are built for a “defaults, with overrides” pattern. This lets you specify common data once, then override it in situations where the default won’t work. And since Hiera uses Puppet’s facts to specify data sources, you can structure your overrides in whatever way makes sense for your infrastructure.
Hiera is immensely powerful, and with great power comes great responsibility. Specifically, you’re responsible for making your infrastructure maintainable and legible, both for your co-workers and for your future self.
The best way to do this is to adopt sensible, rigorous rules about where and how Hiera data should enter your system. This makes your code and data easier to reason about and safer to edit.
For most Puppet users, the roles and profiles method is a good starting point. It sets simple rules about what should and shouldn’t be configured with Hiera, and strikes a good balance between flexibility and maintainability.
“Hiera 5” is a backwards-compatible evolution of Hiera. It’s built into this version of Puppet — you’re already using it, though you might not have enabled its new features yet.
Hiera began as an independent Ruby library that worked with Puppet. Over time, it became a requirement and was even included in the puppet-agent package, but it was limited by its original design.
Now, Hiera is fully integrated into Puppet.
The biggest new feature in Hiera 5 is independent hierarchy configurations for each environment and module. This means:
Read about Hiera’s system of three layers for more info.
We’ve totally overhauled the interface for building custom backends, so it’s easy to integrate Hiera with almost any data source. See How custom backends work for more info.
The experimental “Puppet lookup” feature (from Puppet 4.3 through 4.8) was effectively Hiera 4 — it used a “version: 4” hiera.yaml file, and included rough drafts of many features we completed for Hiera 5.
Hiera 5 is backwards compatible with Puppet lookup, and supports v4 hiera.yaml files. Hiera still uses the
lookup function and
puppet lookup command.
Your data probably won’t need any changes, and Hiera 5 is compatible with your old configuration. But if you want to take full advantage of Hiera 5’s new features, you’ll need to make some configuration edits to enable them. See the migration guide for details.
Even with all the new features enabled, you can keep using your Hiera 3 backends at the global layer.
As soon as possible, the backend’s maintainer should rewrite it to support Hiera 5. Hiera 5 backends are much easier to write, and support per-environment configuration.
Probably in Puppet 6. You have some time.
The current list of deprecated Hiera features includes:
hiera_*functions. (They’re fully replaced by the
hieracommand line tool, which was used for testing and exploring data. (It’s replaced by the
puppet lookupcommand, which understands concepts like nodes and environments and can automatically get facts from PuppetDB.)
data_binding_terminussetting. If you use a custom terminus, convert it to a Hiera 5 custom backend.
Hiera 3 could use these as a hacky predecessor of module data, but anything you were doing with them is better accomplished with the module layer. You can continue using these in a version 3 hiera.yaml file, but you’ll need to remove them once you update your global config to version 5.