Man Page: puppet lookup
Included in Puppet Enterprise 2016.1. A newer version is available; see the version menu above for details.
puppet-lookup - Data in modules lookup function
The lookup command is used for debugging and testing a given data configuration. For a given data key, lookup will produce either a value or an explanation of how that value was obtained on the standard output stream with the specified rendering format. Lookup is designed to be run on a puppet master or a node in a masterless setup.
puppet lookup [--help] [--type TYPESTRING] [--merge unique|hash|deep] [--knock-out-prefix PREFIX-STRING] [--sort-merged-arrays] [--unpack-arrays STRING-VALUE] [--merge-hash-arrays] [--explain] [--default VALUE] [--node NODE-NAME] [--facts FILE] [--compile] [--render-as s|json|yaml|binary|msgpack] keys
The lookup command is a CLI interface for the puppet lookup function. When given one or more keys, the lookup command will return the first value found when run from the puppet master or a masterless node.
When an explanation has not been requested and lookup is simply looking up a value, the application will exit with 0 if a value was found and 1 otherwise. When an explanation is requested, lookup will always exit with 0 unless there is a major error.
The other options are as passed into the lookup function, and the effect they have on the lookup is described in more detail in the header for the lookup function:
These options and their effects are decribed in more detail in the puppet lookup function linked to above.
--help: Print this help message.
--type TYPESTRING: Assert that the value has the specified type.
--merge unique|hash|deep: Specify the merge strategy. 'hash' performs a simple hash-merge by overwriting keys of lower lookup priority. 'unique' appends everything to an array containing no nested arrays and where all duplicates have been removed. 'deep' Performs a deep merge on values of Array and Hash type. There are additional option flags that can be used with 'deep'.
--knock_out_prefix PREFIX-STRING Can be used with the 'deep' merge strategy. Specify string value to signify prefix which deletes elements from existing element.
--sort_merged_arrays Can be used with the 'deep' merge strategy. When this flag is used all merged arrays will be sorted.
--unpack_arrays STRING-VALUE Can be used with the 'deep' merge strategy. Specify a string value used as a deliminator to join all array values and then split them again.
--merge_hash_arrays Can be used with the 'deep' merge strategy. When this flag is used arrays and hashes will be merged.
--explain Print an explanation for the details of how the lookup performed rather than the value returned for the key. The explaination will describe how the result was obtained or why lookup failed to obtain the result.
--explain-options Explain if a lookup_options hash will be used and how it was assembled when performing a lookup.
--default VALUE A value produced if no value was found in the lookup.
--node NODE-NAME Specify node which defines the scope in which the lookup will be performed. If a node is not given, lookup will default to the machine from which the lookup is being run (which should be the master).
--facts FILE Specify a .json, or .yaml file holding key => value mappings that will override the facts for the current node. Any facts not specified by the user will maintain their original value.
--compile Perform a full catalog compilation prior to the lookup. This is meaningful when the catalog changes global variables that are referenced in interpolated values. No catalog compilation takes place unless this flag is given.
--render-as s|json|yaml|binary|msgpack Determines how the results will be rendered to the standard output where s means plain text. The default when lookup is producing a value is yaml and the default when producing an explanation is s.
If you wanted to lookup 'key_name' within the scope of the master, you would call lookup like this: $ puppet lookup key_name
If you wanted to lookup 'key_name' within the scope of the agent.local node, you would call lookup like this: $ puppet lookup --node agent.local key_name
If you wanted to get the first value found for 'key_name_one' and 'key_name_two' within the scope of the agent.local node while merging values and knocking out the prefix 'foo' while merging, you would call lookup like this: $ puppet lookup --node agent.local --merge deep --knock_out_prefix foo key_name_one key_name_two
If you wanted to lookup 'key_name' within the scope of the agent.local node, and return a default value of 'bar' if nothing was found, you would call lookup like this: $ puppet lookup --node agent.local --default bar key_name
If you wanted to see an explanation of how the value for 'key_name' would be obtained in the context of the agent.local node, you would call lookup like this: $ puppet lookup --node agent.local --explain key_name
Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License