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 is a key/value lookup tool for configuration data, built to make Puppet better and let you set node-specific data without repeating yourself. See “Why Hiera?” below for more information, or get started using it right away:
Getting started with Hiera
To get started with Hiera, you’ll need to do all of the following:
- Make sure it’s installed. Hiera ships with Puppet agent, so install the puppet-agent package if you haven’t already. (Linux, Windows, OS X.)
- Make a
hiera.yamlconfig file.- Arrange a hierarchy that fits your site and data.
- Write data sources.
- Use your Hiera data in Puppet (or any other tool).
After you have Hiera working, you can adjust your data and hierarchy whenever you need to. You can also test Hiera from the command line to make sure it’s fetching the right data for each node.
Learning from Example
If you learn best from example code, start with this simple end-to-end Hiera and Puppet walkthrough. To learn more, you can go back and read the sections linked above.
Why Hiera?
Making Puppet better
Hiera makes Puppet better by keeping site-specific data out of your manifests. Puppet classes can request whatever data they need, and your Hiera data will act like a site-wide config file.
This makes it:
- Easier to configure your own nodes: default data with multiple levels of overrides is finally easy.
- Easier to re-use public Puppet modules: don’t edit the code, just put the necessary data in Hiera.
- Easier to publish your own modules for collaboration: no need to worry about cleaning out your data before showing it around, and no more clashing variable names.
Avoiding repetition
With Hiera, you can:
- Write common data for most nodes
- Override some values for machines located at a particular facility…
- …and override some of those values for one or two unique nodes.
This way, you only have to write down the differences between nodes. When each node asks for a piece of data, it will get the specific value it needs.
To decide which data sources can override which, Hiera uses a configurable hierarchy. This ordered list can include both static data sources (with names like “common”) and dynamic ones (which can switch between data sources based on the node’s name, operating system, and more).