This document discusses changes to Hiera data lookup in Puppet 4, including the introduction of per-module Hiera data and the Hiera v5 hierarchy. It recommends using the lookup() function and Hiera v5 to provide module-level data in layers from global to module-specific. The default Hiera v5 configuration provides common, OS family, and node-specific data layers that modules can augment with their own module-specific data.

1. Puppet 4 Module Data
Pre-environment & per-module Hiera
Raleigh PUG 3/2017
Jere Julian

2. Where we were
Single, global hiera.yaml
Incantations to have per-environment hieradata/
Modules relied on params.pp model

3. Experimental (deprecated) - 2016.1 [4.4]
Puppet $var = hiera() replaced by $var = lookup()
Tiers: Classic Hiera, Environment Data, Module Data
Module Data lookup require module namespace!
New hiera.yaml format: v4
puppet.conf:
environment_data_provider = hiera

4. Hiera.yaml v4 (deprecated)
# /etc/puppetlabs/code/environments/production/hiera.yaml
---
version: 4
datadir: data
hierarchy:
- name: "Nodes"
backend: yaml
path: "nodes/%{trusted.certname}"
# Putting a JSON level between YAML levels like this was impossible in the old format.
- name: "Exported JSON nodes"
backend: json
paths:
# Puppet checks these in order. Even though this is a single item in the hierarchy,
it acts like multiple hierarchy levels.
- "nodes/%{trusted.certname}"
- "insecure_nodes/%{facts.fqdn}"
- name: "virtual/%{facts.virtual}"
backend: yaml
- name: "common"
backend: yaml

5. Current Module Data - Hiera 5 - 2017.1 [4.9]
Hiera 5 now included in Puppet
Environment and Module Data
lookup() function and 'puppet lookup' CLI command
hiera_* functions and hiera.yaml v4 deprecated
Layers: Global, Environment, Module

6. Hiera.yaml v5---
version: 5
defaults: # Used for any hierarchy level that omits these keys.
datadir: data # This path is relative to hiera.yaml's directory.
data_hash: yaml_data # Use the built-in YAML backend.
hierarchy:
- name: "Per-node data" # Human-readable name.
path: "nodes/%{trusted.certname}.yaml" # File path, relative to datadir.
# ^^^ IMPORTANT: include the file extension!
- name: "Per-datacenter business group data" # Uses custom facts.
path: "location/%{facts.whereami}/%{facts.group}.yaml"
- name: "Global business group data"
path: "groups/%{facts.group}.yaml"
- name: "Per-datacenter secret data (encrypted)"
lookup_key: eyaml_lookup_key # Uses non-default backend.
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
- name: "Per-OS defaults"
path: "os/%{facts.os.family}.yaml"
- name: "Common data"
path: "common.yaml"

7. Default hiera.yaml v5
---
version: 5
hierarchy:
- name: Common
path: common.yaml
defaults:
data_hash: yaml_data
datadir: data

8. Notes & Recommendations
lookup() does NOT merge values. Still use hiera_array & hiera_hash
Hiera_include does an array merge from all levels
Don't use the lookup() function within templates
Lookups within data.yaml:
profile::wordpress::database_server:
"%{lookup('profile::mysql::public_hostname')}"
Alias:
original:
- 'one'
- 'two'
aliased: "%{alias('original')}"

9. References
Don't use the lookup() function within templates
Hiera v5 syntax
Puppet 4.4 lookup() quick reference
Example Puppet module using hiera module data:
aristanetworks-cloudvision