Your company here — click to reach over 10,000 unique daily visitors

puppet-lookup - Man Page

Interactive Hiera lookup


Does Hiera lookups from the command line.

Since this command needs access to your Hiera data, make sure to run it on a node that has a copy of that data. This usually means logging into a Puppet Server node and running ´puppet lookup´ with sudo.

The most common version of this command is:

´puppet lookup KEY --node NAME --environment ENV --explain´


puppet lookup [--help] [--type TYPESTRING] [--merge first|unique|hash|deep] [--knock-out-prefix PREFIX-STRING] [--sort-merged-arrays] [--merge-hash-arrays] [--explain] [--environment ENV] [--default VALUE] [--node NODE-NAME] [--facts FILE] [--compile] [--render-as s|json|yaml|binary|msgpack] keys


The lookup command is a CLI for Puppet´s ´lookup()´ function. It searches your Hiera data and returns a value for the requested lookup key, so you can test and explore your data. It is a modern replacement for the ´hiera´ command. Lookup uses the setting for global hiera.yaml from puppet´s config, and the environment to find the environment level hiera.yaml as well as the resulting modulepath for the environment (for hiera.yaml files in modules). Hiera usually relies on a node´s facts to locate the relevant data sources. By default, ´puppet lookup´ uses facts from the node you run the command on, but you can get data for any other node with the ´--node NAME´ option. If possible, the lookup command will use the requested node´s real stored facts from PuppetDB; if PuppetDB isn´t configured or you want to provide arbitrary fact values, you can pass alternate facts as a JSON or YAML file with ´--facts FILE´.

If you´re debugging your Hiera data and want to see where values are coming from, use the ´--explain´ option.

If ´--explain´ isn´t specified, lookup exits with 0 if a value was found and 1 otherwise. With ´--explain´, lookup always exits with 0 unless there is a major error.

You can provide multiple lookup keys to this command, but it only returns a value for the first found key, omitting the rest.

For more details about how Hiera works, see the Hiera documentation: https://puppet.com/docs/puppet/latest/hiera_intro.html



To look up ´key_name´ using the Puppet Server node´s facts: $ puppet lookup key_name

To look up ´key_name´ using the Puppet Server node´s arbitrary variables from a manifest, and classify the node if applicable: $ puppet lookup key_name --compile

To look up ´key_name´ using the Puppet Server node´s facts, overridden by facts given in a file: $ puppet lookup key_name --facts fact_file.yaml

To look up ´key_name´ with agent.local´s facts: $ puppet lookup --node agent.local key_name

To get the first value found for ´key_name_one´ and ´key_name_two´ with agent.local´s facts while merging values and knocking out the prefix ´foo´ while merging: $ puppet lookup --node agent.local --merge deep --knock-out-prefix foo key_name_one key_name_two

To lookup ´key_name´ with agent.local´s facts, and return a default value of ´bar´ if nothing was found: $ puppet lookup --node agent.local --default bar key_name

To see an explanation of how the value for ´key_name´ would be found, using agent.local´s facts: $ puppet lookup --node agent.local --explain key_name


April 2024 Puppet, Inc. Puppet manual