NAME

       puppet-lookup - Interactive Hiera lookup

SYNOPSIS

       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´

USAGE

       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

DESCRIPTION

       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.

       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

OPTIONS

       ○   --help: Print this help message.

       ○   --explain Explain the details of how the lookup was performed and where the final value came from (or
           the reason no value was found).

       ○   --node  NODE-NAME  Specify  which node to look up data for; defaults to the node where the command is
           run. Since Hiera´s purpose is to provide different values for different nodes (usually based on their
           facts), you´ll usually want to use some specific node´s facts to explore your data. If the node where
           you´re running this command is configured to talk to PuppetDB, the command  will  use  the  requested
           node´s most recent facts. Otherwise, you can override facts with the ´--facts´ option.

       ○   --facts  FILE  Specify  a .json or .yaml file of key => value mappings to override the facts for this
           lookup. Any facts not specified in this file maintain their original value.

       ○   --environment ENV Like with most Puppet commands, you can specify an environment on the command line.
           This is important for lookup because different environments can have different Hiera data.

       ○   --merge first|unique|hash|deep: Specify the merge behavior, overriding any merge  behavior  from  the
           data´s  lookup_options.  ´first´  returns  the  first  value  found. ´unique´ appends everything to a
           merged, deduplicated array. ´hash´ performs a simple hash merge by overwriting keys of  lower  lookup
           priority. ´deep´ performs a deep merge on values of Array and Hash type. There are additional options
           that can be used with ´deep´.

       ○   --knock-out-prefix  PREFIX-STRING  Can  be used with the ´deep´ merge strategy. Specifies a prefix to
           indicate a value should be removed from the final result.

       ○   --sort-merged-arrays Can be used with the ´deep´ merge strategy. When this flag is used,  all  merged
           arrays are sorted.

       ○   --merge-hash-arrays Can be used with the ´deep´ merge strategy. When this flag is used, hashes WITHIN
           arrays are deep-merged with their counterparts by position.

       ○   --explain-options  Explain  whether  a lookup_options hash affects this lookup, and how that hash was
           assembled. (lookup_options is how Hiera configures merge behavior in data.)

       ○   --default VALUE A value to return if Hiera can´t find a value in data. For  emulating  calls  to  the
           ´lookup()´ function that include a default.

       ○   --type  TYPESTRING:  Assert  that  the  value  has  the  specified  type.  For emulating calls to the
           ´lookup()´ function that include a data type.

       ○   --compile Perform a full catalog compilation prior to the lookup. If your hierarchy and data only use
           the $facts, $trusted, and $server_facts variables, you don´t need this option; however, if your Hiera
           configuration uses arbitrary variables set by a Puppet manifest, you might need this  option  to  get
           accurate data. No catalog compilation takes place unless this flag is given.

       ○   --render-as  s|json|yaml|binary|msgpack  Specify  the  output  format of the results; "s" means plain
           text. The default when producing a value is yaml and the default when producing an explanation is s.

EXAMPLE

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

       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

COPYRIGHT

       Copyright (c) 2015 Puppet Inc., LLC Licensed under the Apache 2.0 License

Puppet, Inc.                                       March 2020                                   PUPPET-LOOKUP(8)