Configuring a hierarchy level: legacy Hiera 3 backends

If you rely on custom data backends designed for Hiera 3, you can use them in your global hierarchy. They are not supported at the environment or module layers.

This feature is a temporary measure to let you start using new features while waiting for backend updates.
Each legacy hierarchy level needs the following keys:

  • name — A name for this level, shown in debug messages and --explain output.
  • path or paths (choose one) — The data files to use for this hierarchy level.
    • For file-based backends, include the file extension, even though you would have omitted it in the v3 hiera.yaml file.
    • For non-file backends, don't use a file extension.
  • hiera3_backend — The legacy backend to use. This is the same name you'd use in the v3 config file's :backends key.
  • datadir — The directory where data files are kept. Set this only if your backend required a :datadir setting in its backend-specific options.
    • This path is relative to hiera.yaml's directory: if the config file is at /etc/puppetlabs/code/environments/production/hiera.yaml and the datadir is set to data, the full path to the data directory is /etc/puppetlabs/code/environments/production/data. Note that Hiera v3 uses 'hieradata' instead of 'data'.
    • In the global layer, you can optionally set the datadir to an absolute path.
  • options — A hash, with any backend-specific options (other than datadir) required by your backend. In the v3 config, this would have been in a top-level key named after the backend. You can use normal strings as keys. Hiera converts them to symbols for the backend.

The following example shows roughly equivalent v3 and v5 hiera.yaml files using legacy backends:

# hiera.yaml v3
---
:backends:
  - mongodb
  - xml

:mongodb:
  :connections:
    :dbname: hdata
    :collection: config
    :host: localhost

:xml:
  :datadir: /some/other/dir

:hierarchy:
  - "%{trusted.certname}"
  - "common"


# hiera.yaml v5
---
version: 5
hierarchy:
  - name: MongoDB
    hiera3_backend: mongodb
    paths:
      - "%{trusted.certname}"
      - common
    options:
      connections:
        dbname: hdata
        collection: config
        host: localhost

  - name: Data in XML
    hiera3_backend: xml
    datadir: /some/other/dir
    paths:
      - "%{trusted.certname}.xml"
      - common.xml