Hiera: Using the deprecated hiera functions

The hiera, hiera_array, hiera_hash, and hiera_include functions are Hiera’s classic interface; they predate automatic class parameter lookup and the lookup function.

Those newer interfaces are better, so the classic functions are now deprecated. They’ll be removed in Puppet 6.

For info about updating uses of the hiera_* functions to use lookup, see Update classic hiera function calls.

Note: These classic functions cannot use configured merge behavior (lookup_options), because each one is dedicated to one particular merge behavior. (hiera_array always does a unique merge, etc.)

hiera

Does a first-found lookup.

hiera takes up to three arguments, in this order:

1. A string key that Hiera searches for in the hierarchy. Required.
2. An optional default value to return if Hiera doesn’t find anything matching the key.
   • If this argument isn’t provided and this function results in a lookup failure, Puppet fails with a compilation error.
3. (Deprecated) The optional name of an arbitrary hierarchy level to insert at the top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
   • If Hiera doesn’t find a matching key in the overriding hierarchy level, it continues searching the rest of the hierarchy.

Important: If the environment layer is enabled, Hiera 5 does not support the third argument to this function, and raises an error if it is present. See Enable the environment layer for more details.

Example: Using hiera

# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming web01.example.com.yaml:
# users:
#   - "Amy Barry"
#   - "Carrie Douglas"

# Assuming common.yaml:
users:
  admins:
    - "Edith Franklin"
    - "Ginny Hamilton"
  regular:
    - "Iris Jackson"
    - "Kelly Lambert"

# Assuming we are not web01.example.com:

$users = hiera('users', undef)

# $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
#                  regular => ["Iris Jackson", "Kelly Lambert"]}

You can optionally generate the default value with a lambda that takes one parameter.

Example: Using hiera with a lambda

# Assuming the same Hiera data as the previous example:

$users = hiera('users') | $key | { "Key '${key}' not found" }

# $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
#                  regular => ["Iris Jackson", "Kelly Lambert"]}
# If hiera couldn't match its key, it would return the lambda result,
# "Key 'users' not found".

hiera_array

Does a unique merge lookup.

hiera_array takes up to three arguments, in this order:

1. A string key that Hiera searches for in the hierarchy. Required.
2. An optional default value to return if Hiera doesn’t find anything matching the key.
   • If this argument isn’t provided and this function results in a lookup failure, Puppet fails with a compilation error.
3. (Deprecated) The optional name of an arbitrary hierarchy level to insert at the top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
   • If Hiera doesn’t find a matching key in the overriding hierarchy level, it continues searching the rest of the hierarchy.

Important: If the environment layer is enabled, Hiera 5 does not support the third argument to this function, and raises an error if it is present. See Enable the environment layer for more details.

Example: Using hiera_array

# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming common.yaml:
# users:
#   - 'cdouglas = regular'
#   - 'efranklin = regular'

# Assuming web01.example.com.yaml:
# users: 'abarry = admin'

$allusers = hiera_array('users', undef)

# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].

You can optionally generate the default value with a lambda that takes one parameter.

Example: Using hiera_array with a lambda

# Assuming the same Hiera data as the previous example:

$allusers = hiera_array('users') | $key | { "Key '${key}' not found" }

# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
# If hiera_array couldn't match its key, it would return the lambda result,
# "Key 'users' not found".

hiera_array expects that all values returned will be strings or arrays. If any matched value is a hash, Puppet raises a type mismatch error.

hiera_hash

Normally does a hash merge lookup. However, if the global layer uses a version 3 hiera.yaml file and its :merge_behavior setting is set to deeper, this function does a deep merge lookup instead. (Note that the :merge_behavior setting only affects hiera_hash; it does not affect automatic class parameter lookup, the lookup function, or the puppet lookup command.)

The hiera_hash function takes up to three arguments, in this order:

1. A string key that Hiera searches for in the hierarchy. Required.
2. An optional default value to return if Hiera doesn’t find anything matching the key.
   • If this argument isn’t provided and this function results in a lookup failure, Puppet fails with a compilation error.
3. (Deprecated) The optional name of an arbitrary hierarchy level to insert at the top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
   • If Hiera doesn’t find a matching key in the overriding hierarchy level, it continues searching the rest of the hierarchy.

Important: If the environment layer is enabled, Hiera 5 does not support the third argument to this function, and raises an error if it is present. See Enable the environment layer for more details.

Example: Using hiera_hash

# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming common.yaml:
# users:
#   regular:
#     'cdouglas': 'Carrie Douglas'

# Assuming web01.example.com.yaml:
# users:
#   administrators:
#     'aberry': 'Amy Berry'

# Assuming we are not web01.example.com:

$allusers = hiera_hash('users', undef)

# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
#                     administrators => {"aberry" => "Amy Berry"}}

You can optionally generate the default value with a lambda that takes one parameter.

Example: Using hiera_hash with a lambda

# Assuming the same Hiera data as the previous example:

$allusers = hiera_hash('users') | $key | { "Key '${key}' not found" }

# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
#                     administrators => {"aberry" => "Amy Berry"}}
# If hiera_hash couldn't match its key, it would return the lambda result,
# "Key 'users' not found".

hiera_hash expects that all values returned will be hashes. If any of the values found in the data sources are strings or arrays, Puppet raises a type mismatch error.

hiera_include

Does a unique merge lookup for the requested key, then calls the include function on the resulting array.

hiera_include requires:

• A string key name to use for classes.
• A call to this function (i.e. hiera_include('classes')) in your environment’s sites.pp manifest, outside of any node definitions and below any top-scope variables that Hiera uses in lookups.
• classes keys in the appropriate Hiera data sources, with an array for each classes key and each value of the array containing the name of a class.

The function takes up to three arguments, in this order:

1. A string key that Hiera searches for in the hierarchy. Required.
2. An optional default value to return if Hiera doesn’t find anything matching the key.
   • If this argument isn’t provided and this function results in a lookup failure, Puppet fails with a compilation error.
3. (Deprecated) The optional name of an arbitrary hierarchy level to insert at the top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
   • If Hiera doesn’t find a matching key in the overriding hierarchy level, it continues searching the rest of the hierarchy.

Important: If the environment layer is enabled, Hiera 5 does not support the third argument to this function, and raises an error if it is present. See Enable the environment layer for more details.

Example: Using hiera_include

# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming web01.example.com.yaml:
# classes:
#   - apache::mod::php

# Assuming common.yaml:
# classes:
#   - apache

# In site.pp, outside of any node definitions and below any top-scope variables:
hiera_include('classes', undef)

# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.

You can optionally generate the default value with a lambda that takes one parameter.

Example: Using hiera_include with a lambda

# Assuming the same Hiera data as the previous example:

# In site.pp, outside of any node definitions and below any top-scope variables:
hiera_include('classes') | $key | {"Key '${key}' not found" }

# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
# If hiera_include couldn't match its key, it would return the lambda result,
# "Key 'classes' not found".