Configuring a hierarchy level: hiera-eyaml

Hiera 5 ( Puppet 4.9.3 and later) includes a native interface for the Hiera eyaml extension, which keeps data encrypted on disk but lets Puppet read it during catalog compilation.

To learn how to create keys and edit encrypted files, see the Hiera eyaml documentation.

Within hiera.yaml, the eyaml backend resembles the standard built-in backends, with a few differences: it uses lookup_key instead of data_hash, and requires an options key to locate decryption keys. Note that the eyaml backend can read regular yaml files as well as yaml files with encrypted data.

To use the eyaml backend, you must have the hiera-eyaml gem installed where Puppet can use it. It's included in Puppet Server since version 5.2.0, so you just need to make it available for command line usage. To enable eyaml on the command line and with

puppet
            apply

, use

sudo
            /opt/puppetlabs/puppet/bin/gem install hiera-eyaml

Each eyaml hierarchy level needs the following keys:

name — A name for this level, shown in debug messages and --explain output.
lookup_key — Which backend to use. The value must be eyaml_lookup_key. Use this instead of the data_hash setting.
path, paths, mapped_paths, glob, or globs (choose one) — The data files to use for this hierarchy level. These paths are relative to the datadir, they support variable interpolation, and they require a file extension. In this case, you'll usually use .eyaml. They work the same way they do for the standard backends.
datadir — The directory where data files are kept. Can be omitted if you set a default. Works the same way it does for the standard backends.
options — A hash of options specific to hiera-eyaml, mostly used to configure decryption. For the default encryption method, this hash must have the following keys:
- pkcs7_private_key — The location of the PKCS7 private key to use.
- pkcs7_public_key — The location of the PKCS7 public key to use.
- If you use an alternate encryption plugin, search the plugin's docs for the encryption options. Set an encrypt_method option, plus some plugin-specific options to replace the pkcs7 ones.
- You can use normal strings as keys in this hash; you don't need to use symbols.

The file path key and the options key both support variable interpolation.

An example hierarchy level:

hierarchy:
  - name: "Per-datacenter secret data (encrypted)"
    lookup_key: eyaml_lookup_key
    path: "secrets/%{facts.whereami}.eyaml"
    options:
      pkcs7_private_key: /etc/puppetlabs/puppet/eyaml/private_key.pkcs7.pem
      pkcs7_public_key:  /etc/puppetlabs/puppet/eyaml/public_key.pkcs7.pem

Related information

Interpolation