Enable the environment layer for existing Hiera data

A key feature in Hiera 5 is per-environment hierarchy configuration. Because you probably store data in each environment, local hiera.yaml files are more logical and convenient than a single global hierarchy.

1. Check your code for Hiera function calls with "hierarchy override arguments" (as shown later), which cause errors.
2. Add a local hiera.yaml file.
3. Update your custom backends if you have them.
4. Rename the data directory to exclude this environment from the global layer. Unmigrated environments still rely on the global layer, which gets checked before the environment layer. If you want to maintain both migrated and unmigrated environments during the migration process, choose a different data directory name for migrated environments. The new name 'data' is a good choice because it is also the new default (unless you are already using 'data', in which case choose a different name and set datadir in hiera.yaml). This process has no particular time limit and doesn't involve any downtime. After all of your environments are migrated, you can phase out or greatly reduce the global hierarchy.

   The environment layer does not support Hiera 3 backends. If any of your data uses a custom backend that has not been ported to Hiera 5, omit those hierarchy levels from the environment config and continue to use the global layer for that data. Because the global layer is checked before the environment layer, it's possible to run into situations where you cannot migrate data to the environment layer yet. For example, if your old :backends setting was [custom_backend, yaml], you can do a partial migration, because the custom data was all going before the YAML data anyway. But if :backends was [yaml, custom_backend], and you frequently use YAML data to override the custom data, you can't migrate until you have a Hiera 5 version of that custom backend. If you run into a situation like this, get an upgraded backend before enabling the environment layer.

5. Check your Puppet code for classic Hiera functions (hiera, hiera_array, hiera_hash, and hiera_include) that are passing the optional hierarchy override argument, and remove the argument.

   In Hiera 5, the hierarchy override argument is an error.

   A quick way to find instances of using this argument is to search for calls with two or more commas. Search your codebase using the following regular expression:

   hiera(_array|_hash|_include)?\(([^,\)]*,){2,}[^\)]*\)

   This results in some false positives, but helps find the errors before you run the code.

   Alternatively, continue to the next step and fix errors as they come up. If you use environments for code testing and promotion, you’re probably migrating a temporary branch of your control repo first, then pointing some canary nodes at it to make sure everything works as expected. If you think you’ve never used hierarchy override arguments, you’ll be verifying that assumption when you run your canary nodes. If you do find any errors, you can fix them before merging your branch to production, the same way you would with any work-in-progress code.

   If your environments are similar to each other, you might only need to check for the hierarchy override argument in function calls in one environment. If you find none, likely the others won’t have many either.

6. Choose a new data directory name to use in the next two steps. The default data directory name in Hiera 3 was <ENVIRONMENT>/hieradata, and the default in Hiera 5 is <ENVIRONMENT>/data. If you used the old default, use the new default. If you were already using data, choose something different.
7. Add a Hiera 5 hiera.yaml file to the environment.

   Each environment needs a Hiera config file that works with its existing data. If this is the first environment you’re migrating, see converting a version 3 hiera.yaml to version 5. Make sure to reference the new datadir name. If you’ve already migrated at least one environment, copy the hiera.yaml file from a migrated environment and make changes to it if necessary.

   Save the resulting file as <ENVIRONMENT>/hiera.yaml. For example, /etc/puppetlabs/code/environments/production/hiera.yaml.

8. If any of your data relies on custom backends that have been ported to Hiera 5, install them in the environment. Hiera 5 backends are distributed as Puppet modules, so each environment can use its own version of them.
9. If you use only file-based Hiera 5 backends, move the environment’s data directory by renaming it from its old name (hieradata) to its new name (data). If you use custom file-based Hiera 3 backends, the global layer still needs access to their data, so you need to sort the files: Hiera 5 data moves to the new data directory, and Hiera 3 data stays in the old data directory. When you have Hiera 5 versions of your custom backends, you can move the remaining files to the new datadir. If you use non-file backends that don’t have a data directory:
   1. Decide that the global hierarchy is the right place for configuring this data, and leave it there permanently.
   2. Do something equivalent to moving the datadir; for example, make a new database table for migrated data and move values into place as you migrate environments.
   3. Allow the global and environment layers to use duplicated configuration for this data until the migration is done.
10. Repeat these steps for each environment. If you manage your code by mapping environments to branches in a control repo, you can migrate most of your environments using your version control system’s merging tools.
11. After you have migrated the environments that have active node populations, delete the parts of your global hierarchy that you transferred into environment hierarchies.