Upgrading to Hiera 5
Upgrading to Hiera 5 offers some major advantages. A real environment data layer means changes to your hierarchy are now routine and testable, using multiple backends in your hierarchy is easier and you can make a custom backend.
Hiera 5 uses the same built-in data formats as Hiera 3. You don't need to do mass edits of any data files.
Updating your code to take advantage of Hiera 5 features involves the following tasks:
| Task | Benefit |
|---|---|
Enable the environment layer,
by giving each environment its own hiera.yaml file. Enabling the environment layer takes the most work,
but yields the biggest benefits. Focus on that first, then do the
rest at your own pace. |
Future hierarchy changes are
cheap and testable. The legacy Hiera functions (hiera, hiera_array,
hiera_hash, and hiera_include) gain full Hiera 5 powers in any migrated
environment, only if there is a hiera.yaml in the environment root. |
Convert your global hiera.yaml
file to the version 5 format. |
You can use new Hiera 5 backends at the global layer. |
Convert any experimental
(version 4) hiera.yaml files to version 5. |
Future-proof any environments or modules where you used the experimental version of Puppet lookup. |
In Puppet code, replace legacy Hiera
functions (hiera, hiera_array, hiera_hash, and hiera_include) with lookup(). |
Future-proof your Puppet code. |
| Use Hiera for default data in modules. | Simplify your modules with an
elegant alternative to the "params.pp" pattern. |
Considerations for hiera-eyaml users
Upgrade now. In Puppet 4.9.3, we added a built-in
hiera-eyaml backend for Hiera 5. (It still requires that the hiera-eyaml gem be installed.) See the usage instructions in the
hiera.yaml (v5) syntax reference. This means you
can move your existing encrypted YAML data into the environment layer at the same
time you move your other data.
Considerations for custom backend users
Wait for updated backends. You can keep using custom Hiera 3 backends with Hiera 5, but they'll make upgrading more complex, because you can't move legacy data to the environment layer until there's a Hiera 5 backend for it. If an updated version of the backend is coming out soon, wait.
If you're using an off-the-shelf custom backend, check its website or contact its developer. If you developed your backend in-house, read the documentation about writing Hiera 5 backends.
Considerations for custom data_binding_terminus users
Upgrade now, and replace it with a Hiera 5 backend as
soon as possible. There's a deprecated data_binding_terminus
setting in the puppet.conf file, which changes the behavior of
automatic class parameter lookup. It can be set to hiera (normal),
none (deprecated; disables auto-lookup), or the name of a
custom plug-in.
With a custom data_binding_terminus, automatic lookup results are
different from function-based lookups for the same keys. If you're one of the few
who use this feature, you've already had to design your Puppet code to avoid that problem, so it's safe to
upgrade your configuration to Hiera 5. But because
we've deprecated that extension point, you have to replace your custom terminus with
a Hiera 5 backend.
If you're using an off-the-shelf plug-in, such as Jerakia, check its website or contact its developer. If you developed your plug-in in-house, read the documentation about writing Hiera 5 backends.
After you have a Hiera 5 backend, integrate it into
your hierarchies and delete the data_binding_terminus setting.
Related information