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. Lookup uses the setting for global  hiera.yaml
31       from puppet´s config, and the environment to find the environment level
32       hiera.yaml as well as the resulting modulepath for the environment (for
33       hiera.yaml files in modules). Hiera usually relies on a node´s facts to
34       locate the relevant data sources.  By  default,  ´puppet  lookup´  uses
35       facts  from  the  node you run the command on, but you can get data for
36       any other node with the ´--node NAME´ option. If possible,  the  lookup
37       command  will use the requested node´s real stored facts from PuppetDB;
38       if PuppetDB isn´t configured or you want to provide arbitrary fact val‐
39       ues,  you can pass alternate facts as a JSON or YAML file with ´--facts
40       FILE´.
41
42       If you´re debugging your Hiera data and want to see  where  values  are
43       coming from, use the ´--explain´ option.
44
45       If  ´--explain´  isn´t  specified,  lookup  exits with 0 if a value was
46       found and 1 otherwise. With ´--explain´, lookup always exits with 0 un‐
47       less there is a major error.
48
49       You  can  provide multiple lookup keys to this command, but it only re‐
50       turns a value for the first found key, omitting the rest.
51
52       For more details about how Hiera works, see  the  Hiera  documentation:
53       https://puppet.com/docs/puppet/latest/hiera_intro.html
54

OPTIONS

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

EXAMPLE

125       To  look  up  ´key_name´ using the Puppet Server node´s facts: $ puppet
126       lookup key_name
127
128       To look up ´key_name´ using the Puppet Server  node´s  arbitrary  vari‐
129       ables  from  a  manifest, and classify the node if applicable: $ puppet
130       lookup key_name --compile
131
132       To look up ´key_name´ using the Puppet Server node´s facts,  overridden
133       by   facts   given   in  a  file:  $  puppet  lookup  key_name  --facts
134       fact_file.yaml
135
136       To look up ´key_name´ with agent.local´s facts: $ puppet lookup  --node
137       agent.local key_name
138
139       To get the first value found for ´key_name_one´ and ´key_name_two´ with
140       agent.local´s facts while merging values and knocking  out  the  prefix
141       ´foo´  while  merging:  $ puppet lookup --node agent.local --merge deep
142       --knock-out-prefix foo key_name_one key_name_two
143
144       To lookup ´key_name´ with agent.local´s facts,  and  return  a  default
145       value of ´bar´ if nothing was found: $ puppet lookup --node agent.local
146       --default bar key_name
147
148       To see an explanation of how the value for ´key_name´ would  be  found,
149       using agent.local´s facts: $ puppet lookup --node agent.local --explain
150       key_name
151
153       Copyright (c) 2015 Puppet Inc., LLC Licensed under the Apache  2.0  Li‐
154       cense
155
156
157
158Puppet, Inc.                     October 2023                 PUPPET-LOOKUP(8)
Impressum