Troubleshoot Hiera keys using “puppet lookup --explain” in Puppet Enterprise

When you’re applying a manifest, your code might pull either no value or an unexpected value for a Hiera key. You can use puppet lookup --explain to get the value for a given key and learn where the value is set. You can use that information to troubleshoot Hiera key issues.

Version and installation information

PE version: All supported versions
Installation type: standard, large

Solution

First, we’ll use a simple example to explain how to read and use the output, and second, we’ll look at troubleshooting an issue on a key associated with a specific node.

A simple example of puppet lookup --explain output

For example, to check the value of the key foo, on the the primary server run:

puppet lookup foo --explain

# puppet lookup foo --explain
Searching for "foo"
  Global Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/puppet/hiera.yaml"
    No such key: "foo"
  Environment Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/code/environments/production/hiera.yaml"
    Hierarchy entry "Per-node data (yaml version)"
      Path "/etc/puppetlabs/code/environments/production/data/nodes/pe-201730-server.yaml"
        Original path: "nodes/%{::trusted.certname}.yaml"
        Path not found
    Hierarchy entry "Other YAML hierarchy levels"
      Path "/etc/puppetlabs/code/environments/production/data/common.yaml"
        Original path: "common.yaml"
        Found key: "foo" value: "bar"

The lines under Global Data Provider and Environment Data Provider show the Hiera configuration files for the global and environment layers. In the output, foo isn’t found in the global layer. In the environment layer, there are two paths defined in /etc/puppetlabs/code/environments/production/hiera.yaml. Checking the environment layer can help you find out if the value is being set in the appropriate environment. In this example, foo is set in the environment layer for production in /etc/puppetlabs/code/environments/production/hiera.yaml in common.yaml as "bar".

Let’s take a look at the contents of /etc/puppetlabs/code/environments/production/hiera.yaml:

# cat /etc/puppetlabs/code/environments/production/hiera.yaml
version: 5
defaults:
hierarchy:
  - name: "Per-node data (yaml version)"
    path: "nodes/%{::trusted.certname}.yaml"
  - name: "Other YAML hierarchy levels"
    paths:
      - "common.yaml"

If you find issues with those paths or anything else in the lookup output, you can get guidance from our Hiera documentation.

Troubleshooting a key associated with a specific node

If there’s an issue with a key associated with a specific node, you can check the value of the key using the --node parameter. When you do a lookup using the --node parameter, the lookup uses the facts stored in PuppetDB for that node.

Note: If the node has never completed a Puppet run, there are no facts or environment information stored in PuppetDB, so using the --node parameter returns nothing.

For example, on the affected node, run:

puppet lookup foo --node="<NODE CERTNAME>" --explain

If you find issues with those paths or anything else in the lookup output, you can get guidance from our Hiera documentation.