Note: We’ve released a major update to Hiera called Hiera 5.
Hiera 5 is 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 uses an ordered hierarchy to look up data. This allows you to have a large amount of common data and override smaller amounts of it wherever necessary.
Hiera loads the hierarchy from the hiera.yaml config file. The hierarchy must be the value of the top-level :hierarchy
key.
The hierarchy should be an array. (Alternately, it may be a string; this will be treated like a one-element array.)
Each element in the hierarchy must be a string, which may or may not include interpolation tokens. Hiera will treat each element in the hierarchy as the name of a data source.
# /etc/hiera.yaml
---
:hierarchy:
- "%{::clientcert}"
- "%{::environment}"
- "virtual_%{::is_virtual}"
- common
Best Practice: Use Fully-Qualified Puppet Variables
If your hierarchy includes any variables set by Puppet, we recommend that you use their fully-qualified top-scope name. (E.g.
::clientcert
.)For more details, see the Best Practices section of the Using Hiera With Puppet page.
We use these two terms within the Hiera docs and in various other places:
common
is a static data source — a virtual machine named web01
and a physical machine named db01
would both use common
.$::clientcert
Puppet variable has a unique value for every node. A machine named web01
would have a data source named web01
at the top of its hierarchy, while a machine named db01
would have db01
at the top.Each element in the hierarchy resolves to the name of a data source. Hiera will check these data sources in order, starting with the first.
You can specify multiple backends as an array in hiera.yaml
. If you do, they function as a second hierarchy.
Hiera will give priority to the first backend, and will check every level of the hierarchy in it before moving on to the second backend. This means that, with the following hiera.yaml
:
---
:backends:
- yaml
- json
:hierarchy:
- one
- two
- three
…hiera would check the following data sources, in order:
one.yaml
two.yaml
three.yaml
one.json
two.json
three.json
Assume the following hierarchy:
# /etc/hiera.yaml
---
:hierarchy:
- "%{::clientcert}"
- "%{::environment}"
- "virtual_%{::is_virtual}"
- common
…and the following set of data sources:
web01.example.com
web02.example.com
db01.example.com
production.yaml
development.yaml
virtual_true.yaml
common.yaml
…and only the yaml
backend.
Given two different nodes with different Puppet variables, here are two ways the hierarchy could be interpreted:
::clientcert
= web01.example.com
::environment
= production
::is_virtual
= true
::clientcert
= db01.example.com
::environment
= development
::is_virtual
= false
Note that, since virtual_false.yaml
doesn’t exist, it gets skipped entirely.