Convert an experimental (version 4) hiera.yaml to version 5

If you used the experimental version of Puppet lookup ( Hiera 5's predecessor), you might have some version 4 hiera.yaml files in your environments and modules. Hiera 5 can use these, but you need to convert them, especially if you want to use any backends other than YAML or JSON. Version 4 and version 5 formats are similar.

Consider this example of a version 4 hiera.yaml file:

# /etc/puppetlabs/code/environments/production/hiera.yaml
---
version: 4
datadir: data
hierarchy:
  - name: "Nodes"
    backend: yaml
    path: "nodes/%{trusted.certname}"

  - name: "Exported JSON nodes"
    backend: json
    paths:
      - "nodes/%{trusted.certname}"
      - "insecure_nodes/%{facts.networking.fqdn}"

  - name: "virtual/%{facts.virtual}"
    backend: yaml

  - name: "common"
    backend: yaml

To convert to version 5, make the following changes:

Change the value of the version key to 5.
Add a file extension to every file path — use "common.yaml", not "common".
If any hierarchy levels are missing a path, add one. In version 5, path no longer defaults to the value of name
If there is a top-level datadir key, change it to a defaults key. Set a default backend. For example:
```
defaults:
  datadir: data
  data_hash: yaml_data
```

In each hierarchy level, delete the backend key and replace it with a data_hash key. (If you set a default backend in the defaults key, you can omit it here.)

v4 backend	v5 equivalent
`backend: yaml`	`data_hash: yaml_data`
`backend: json`	`data_hash: json_data`

Delete the environment_data_provider and data_provider settings, which enabled Puppet lookup for an environment or module.
You’ll find these settings in the following locations:
- environment_data_provider in puppet.conf.
- environment_data_provider in environment.conf.
- data_provider in a module’s metadata.json.

Results

After being converted to version 5, the example looks like this:

# /etc/puppetlabs/code/environments/production/hiera.yaml
---
version: 5
defaults:
  datadir: data          # Datadir has moved into `defaults`.
  data_hash: yaml_data   # Default backend: New feature in v5.
hierarchy:
  - name: "Nodes"        # Can omit `backend` if using the default.
    path: "nodes/%{trusted.certname}.yaml"   # Add file extension!

  - name: "Exported JSON nodes"
    data_hash: json_data        # Specifying a non-default backend.
    paths:
      - "nodes/%{trusted.certname}.json"
      - "insecure_nodes/%{facts.networking.fqdn}.json"

  - name: "Virtualization platform"
    path: "virtual/%{facts.virtual}.yaml"   # Name and path are now separated.

  - name: "common"
    path: "common.yaml"

For full syntax details, see the hiera.yaml version 5 reference.

Related information