Arguments to the lookup function shown in [ ] are not mandatory which is covered in the preceding section.

• <name>:
  • Must be of the data type string or array.
  • The key name in the Hiera hierarchy to retrieve.
  • An array of keys may also be provided. If the resulting Hiera lookup doesn't provide a result for the first key, it will iteratively try retrievals for the subsequently given keys, finally resorting to the default if none of the array keys succeed in returning a value.
• <value type>:
  • Must be a valid data type
  • The Hiera lookup (and hence the compilation of the catalog) will fail if the datatype of the returned value does not match the data type given here
  • Defaults to Data (that is, any normal value will not fail the Hiera lookup)
• <merge behavior>:
  • Must be either a string or a hash (please see the following Deep merge lookup settings explained section).
  • Explains whether and how to merge multiple values encountered at different hierarchy levels. This overrides the merge behavior that's been specified in the Hiera data sources.
  • Defaults to no value, meaning that, if present, Hiera will first use the merge behavior defined in the data sources; otherwise it will simply use the first lookup strategy (please see the following Lookup strategies section).
• <default value>:
  • If provided, the Hiera lookup will return the value provided here when it cannot find a value in the Hiera hierarchy
  • The values found by the Hiera lookup are never merged with the given default(s)
  • The default type and value type must match
  • no value is the default; meaning that whenever the Hiera lookup cannot retrieve a normal value, the Hiera lookup (and hence the compilation) will fail

As explained in the The lookup function syntax section, there's also an alternative way of providing the lookup function arguments, using an <options hash>:

• <options hash>:
  • Must be of type hash
  • If using this alternative <options hash> style of syntax, you can't combine it with any of the preceding regular arguments except <name>
  • Permissible keys for the options hash are as follows:
    • name: Identical to the first <name> argument described previously. You can pass this either as an argument or in the options hash, but not both.
    • value_type: Identical to the second <value type> argument described previously.
    • merge: This is the same as the third <merge behavior> argument described previously.
    • default_value: This is the same as the fourth <default_value> argument described previously.
    • default_values_hash: This is a hash of lookup keys and their respective default values. If a normal value cannot be retrieved from a Hiera lookup, this hash will be checked for the key before Hiera gives up. This can be combined with either default_value or a lambda expression, which will be substituted if the value is unable to be retrieved from the Hiera hierarchy. An empty hash is the default.
    • override: This value is a hash of Hiera lookup keys and their respective override settings. Hiera checks in the overrides hash for the key; if it is found, it returns that value finally, ignoring any merge behavior. An empty hash is the default.

Additionally, as explained in the Lookup function syntax section, there is a third alternative to providing the arguments to the lookup() function using a single lambda expression. If the Hiera lookup is unable to retrieve a value, the requested key is passed into the lambda expression, the result of which becomes the default_value:

lookup(‘my::key’) |$my_key| {"Hiera couldn't find '${my_key}'. Did you forget to add this key-value pair to your hierarchy?"}

Here, <lambda_expression> is returning a custom string to provide feedback to the user and to handle Hiera being unable to retrieve the required key gracefully , which in previous versions of Hiera would fail silently, causing all sorts of mischief.

We could also add our fact values and so on to help the user find the right place to insert their key-value pair (please refer to the A more complete hierarchy section at the beginning of this chapter):

lookup(‘my::key’) |$my_key| {"Hiera couldn't find '${my_key}' using certname  ‘${trusted.certname}’, application ‘${facts.application}’, environment ${server_facts.environment}, and datacenter ${facts.datacenter}. Did you forget to add this key-value pair to your hierarchy?"}