If you’re already a Hiera user, you don’t have to migrate anything yet. Hiera 5 is fully backwards-compatible with Hiera 3, and we won’t remove any legacy features until Puppet 6. You can even start using some Hiera 5 features (like module data) without migrating anything.
But there are major advantages to fully adopting Hiera 5:
Since Hiera 5 uses the same built-in data formats as Hiera 3, you don’t need to do mass edits of any data files. When we say “migrate to Hiera 5,” we’re talking about updating configuration. Specifically, we’re talking about the following tasks:
|Enable the environment layer, by giving each environment its own hiera.yaml file.||Future hierarchy changes are cheap and testable. The legacy
|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
||Future-proof your Puppet code.|
|Use Hiera for default data in modules.||Simplify your modules with an elegant alternative to the “params.pp” pattern.|
Enabling the environment layer takes the most work, and yields the biggest benefits. Focus on that first, then do the rest at your own pace.
Probably! But there are a few situations where you might want to delay upgrading.
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.
You can keep using custom Hiera 3 backends with Hiera 5, but they’ll make migration 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, it might be more efficient to wait (or even help contribute to its development).
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 — updating it might be easier than you think.
data_binding_terminususers: go ahead, but replace it with a Hiera 5 backend ASAP
There’s a deprecated
data_binding_terminus setting in puppet.conf, which changes the behavior of automatic class parameter lookup. It can be set to
none (deprecated; disables auto-lookup), or the name of a custom plugin.
With a custom
data_binding_terminus, automatic lookup results are radically different from function-based lookups for the same keys. If you’re one of the rare few who use this feature, you’ve already had to design your Puppet code to avoid that problem, so it’s probably safe to migrate your configuration to Hiera 5. But since we’ve deprecated that extension point, you’ll have to replace your custom terminus with a Hiera 5 backend before Puppet 6 rolls around.
Once you have a Hiera 5 backend, integrate it into your global and/or environment hierarchies and delete the