1PUPPET-LOOKUP(8)                 Puppet manual                PUPPET-LOOKUP(8)
2
3
4

NAME

6       puppet-lookup - Interactive Hiera lookup
7

SYNOPSIS

9       Does Hiera lookups from the command line.
10
11       Since this command needs access to your Hiera data, make sure to run it
12       on a node that has a copy of that data. This usually means logging into
13       a Puppet Server node and running ´puppet lookup´ with sudo.
14
15       The most common version of this command is:
16
17       ´puppet lookup KEY --node NAME --environment ENV --explain´
18

USAGE

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

DESCRIPTION

27       The  lookup  command  is  a  CLI  for  Puppet´s ´lookup()´ function. It
28       searches your Hiera data and returns a value for the  requested  lookup
29       key,  so you can test and explore your data. It is a modern replacement
30       for the ´hiera´ command.
31
32       Hiera usually relies on a node´s facts  to  locate  the  relevant  data
33       sources.  By  default, ´puppet lookup´ uses facts from the node you run
34       the command on, but you can get  data  for  any  other  node  with  the
35       ´--node  NAME´ option. If possible, the lookup command will use the re‐
36       quested node´s real stored facts from PuppetDB; if PuppetDB isn´t  con‐
37       figured  or you want to provide arbitrary fact values, you can pass al‐
38       ternate facts as a JSON or YAML file with ´--facts FILE´.
39
40       If you´re debugging your Hiera data and want to see  where  values  are
41       coming from, use the ´--explain´ option.
42
43       If  ´--explain´  isn´t  specified,  lookup  exits with 0 if a value was
44       found and 1 otherwise. With ´--explain´, lookup always exits with 0 un‐
45       less there is a major error.
46
47       You  can  provide multiple lookup keys to this command, but it only re‐
48       turns a value for the first found key, omitting the rest.
49
50       For more details about how Hiera works, see  the  Hiera  documentation:
51       https://puppet.com/docs/puppet/latest/hiera_intro.html
52

OPTIONS

54       •   --help: Print this help message.
55
56       •   --explain  Explain  the details of how the lookup was performed and
57           where the final value came from (or the reason no value was found).
58
59       •   --node NODE-NAME Specify which node to look up data  for;  defaults
60           to  the  node where the command is run. Since Hiera´s purpose is to
61           provide different values for  different  nodes  (usually  based  on
62           their facts), you´ll usually want to use some specific node´s facts
63           to explore your data. If the node where you´re running this command
64           is  configured  to  talk  to PuppetDB, the command will use the re‐
65           quested node´s most recent facts. Otherwise, you can override facts
66           with the ´--facts´ option.
67
68       •   --facts FILE Specify a .json or .yaml file of key => value mappings
69           to override the facts for this lookup. Any facts not  specified  in
70           this file maintain their original value.
71
72       •   --environment  ENV  Like with most Puppet commands, you can specify
73           an environment on the command line. This is  important  for  lookup
74           because different environments can have different Hiera data.
75
76       •   --merge  first|unique|hash|deep:  Specify the merge behavior, over‐
77           riding any merge behavior from the data´s  lookup_options.  ´first´
78           returns  the  first  value  found. ´unique´ appends everything to a
79           merged, deduplicated array. ´hash´ performs a simple hash merge  by
80           overwriting  keys  of lower lookup priority. ´deep´ performs a deep
81           merge on values of Array and Hash type. There  are  additional  op‐
82           tions that can be used with ´deep´.
83
84       •   --knock-out-prefix  PREFIX-STRING Can be used with the ´deep´ merge
85           strategy. Specifies a prefix to indicate a value should be  removed
86           from the final result.
87
88       •   --sort-merged-arrays  Can  be  used with the ´deep´ merge strategy.
89           When this flag is used, all merged arrays are sorted.
90
91       •   --merge-hash-arrays Can be used with  the  ´deep´  merge  strategy.
92           When  this  flag is used, hashes WITHIN arrays are deep-merged with
93           their counterparts by position.
94
95       •   --explain-options Explain whether  a  lookup_options  hash  affects
96           this  lookup,  and  how that hash was assembled. (lookup_options is
97           how Hiera configures merge behavior in data.)
98
99       •   --default VALUE A value to return if Hiera can´t find  a  value  in
100           data. For emulating calls to the ´lookup()´ function that include a
101           default.
102
103       •   --type TYPESTRING: Assert that the value has  the  specified  type.
104           For  emulating calls to the ´lookup()´ function that include a data
105           type.
106
107       •   --compile Perform a full catalog compilation prior to  the  lookup.
108           If  your  hierarchy  and  data  only  use the $facts, $trusted, and
109           $server_facts variables, you don´t need this  option;  however,  if
110           your  Hiera  configuration uses arbitrary variables set by a Puppet
111           manifest, you might need this option to get accurate data. No cata‐
112           log compilation takes place unless this flag is given.
113
114       •   --render-as s|json|yaml|binary|msgpack Specify the output format of
115           the results; "s" means plain text. The  default  when  producing  a
116           value is yaml and the default when producing an explanation is s.
117
118
119

EXAMPLE

121       To  look  up  ´key_name´ using the Puppet Server node´s facts: $ puppet
122       lookup key_name
123
124       To look up ´key_name´ with agent.local´s facts: $ puppet lookup  --node
125       agent.local key_name
126
127       To get the first value found for ´key_name_one´ and ´key_name_two´ with
128       agent.local´s facts while merging values and knocking  out  the  prefix
129       ´foo´  while  merging:  $ puppet lookup --node agent.local --merge deep
130       --knock-out-prefix foo key_name_one key_name_two
131
132       To lookup ´key_name´ with agent.local´s facts,  and  return  a  default
133       value of ´bar´ if nothing was found: $ puppet lookup --node agent.local
134       --default bar key_name
135
136       To see an explanation of how the value for ´key_name´ would  be  found,
137       using agent.local´s facts: $ puppet lookup --node agent.local --explain
138       key_name
139
141       Copyright (c) 2015 Puppet Inc., LLC Licensed under the Apache  2.0  Li‐
142       cense
143
144
145
146Puppet, Inc.                     October 2021                 PUPPET-LOOKUP(8)
Impressum