Extract the pillar data for this minion
salt.modules.pillar.
ext
(external, pillar=None)¶Changed in version 2016.3.6,2016.11.3,2017.7.0: The supported ext_pillar types are now tunable using the
on_demand_ext_pillar
config option. Earlier releases
used a hard-coded default.
Generate the pillar and apply an explicit external pillar
A single ext_pillar to add to the ext_pillar configuration. This must
be passed as a single section from the ext_pillar configuration (see
CLI examples below). For more complicated ext_pillar
configurations, it can be helpful to use the Python shell to load YAML
configuration into a dictionary, and figure out
>>> import salt.utils.yaml
>>> ext_pillar = salt.utils.yaml.safe_load("""
... ext_pillar:
... - git:
... - issue38440 https://github.com/terminalmage/git_pillar:
... - env: base
... """)
>>> ext_pillar
{'ext_pillar': [{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}]}
>>> ext_pillar['ext_pillar'][0]
{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}
In the above example, the value to pass would be
{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}
.
Note that this would need to be quoted when passing on the CLI (as in
the CLI examples below).
If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. These pillar variables will also override any variables of the same name in pillar or ext_pillar.
New in version 2015.5.0.
CLI Examples:
salt '*' pillar.ext '{libvirt: _}'
salt '*' pillar.ext "{'git': ['master https://github.com/myuser/myrepo']}"
salt '*' pillar.ext "{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}"
salt.modules.pillar.
fetch
(key, default=<class 'KeyError'>, merge=False, merge_nested_lists=None, delimiter=':', pillarenv=None, saltenv=None)¶New in version 0.14.
Attempt to retrieve the named value from in-memory pillar data. If the pillar key is not present in the in-memory
pillar, then the value specified in the default
option (described
below) will be returned.
If the merge parameter is set to True
, the default will be recursively
merged into the returned pillar data.
The value can also represent a value in a nested dict using a ":" delimiter for the dict. This means that if a dict in pillar looks like this:
{'pkg': {'apache': 'httpd'}}
To retrieve the value associated with the apache
key in the pkg
dict this key can be passed as:
pkg:apache
The pillar key to get value from
The value specified by this option will be returned if the desired pillar key does not exist.
If a default value is specified, then it will be an empty string,
unless pillar_raise_on_missing
is set to True
, in
which case an error will be raised.
False
If True
, the retrieved values will be merged into the passed
default. When the default and the retrieved value are both
dictionaries, the dictionaries will be recursively merged.
New in version 2014.7.0.
Changed in version 2016.3.7,2016.11.4,2017.7.0: If the default and the retrieved value are not of the same type, then merging will be skipped and the retrieved value will be returned. Earlier releases raised an error in these cases.
If set to False
, lists nested within the retrieved pillar
dictionary will overwrite lists in default
. If set to True
,
nested lists will be merged into lists in default
. If unspecified
(the default), this option is inherited from the
pillar_merge_lists
minion config option.
Note
This option is ignored when merge
is set to False
.
New in version 2016.11.6.
Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage.
New in version 2014.7.0.
If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion's pillar data in memory (which can be sourced from more than one pillar environment).
Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment.
New in version 2017.7.0.
Included only for compatibility with
pillarenv_from_saltenv
, and is otherwise ignored.
New in version 2017.7.0.
CLI Example:
salt '*' pillar.get pkg:apache
salt '*' pillar.get abc::def|ghi delimiter='|'
salt.modules.pillar.
file_exists
(path, saltenv=None)¶New in version 2016.3.0.
This is a master-only function. Calling from the minion is not supported.
Use the given path and search relative to the pillar environments to see if a file exists at that path.
If the saltenv
argument is given, restrict search to that environment
only.
Will only work with pillar_roots
, not external pillars.
Returns True if the file is found, and False otherwise.
The path to the file in question. Will be treated as a relative path
Optional argument to restrict the search to a specific saltenv
CLI Example:
salt '*' pillar.file_exists foo/bar.sls
salt.modules.pillar.
filter_by
(lookup_dict, pillar, merge=None, default='default', base=None)¶New in version 2017.7.0.
Look up the given pillar in a given dictionary and return the result
lookup_dict --
A dictionary, keyed by a pillar, containing a value or values relevant to systems matching that pillar. For example, a key could be a pillar for a role and the value could the name of a package on that particular OS.
The dictionary key can be a globbing pattern. The function will return
the corresponding lookup_dict
value where the pillar value matches
the pattern. For example:
# this will render 'got some salt' if ``role`` begins with 'salt'
salt '*' pillar.filter_by '{salt*: got some salt, default: salt is not here}' role
pillar --
The name of a pillar to match with the system's pillar. For
example, the value of the "role" pillar could be used to pull values
from the lookup_dict
dictionary.
The pillar value can be a list. The function will return the
lookup_dict
value for a first found item in the list matching
one of the lookup_dict
keys.
merge -- A dictionary to merge with the results of the pillar
selection from lookup_dict
. This allows another dictionary to
override the values in the lookup_dict
.
default -- default lookup_dict's key used if the pillar does not exist or if the pillar value has no match on lookup_dict. If unspecified the value is "default".
base -- A lookup_dict key to use for a base dictionary. The
pillar-selected lookup_dict
is merged over this and then finally
the merge
dictionary is merged. This allows common values for
each case to be collected in the base and overridden by the pillar
selection dictionary and the merge dictionary. Default is unset.
CLI Example:
salt '*' pillar.filter_by '{web: Serve it up, db: I query, default: x_x}' role
salt.modules.pillar.
get
(key, default=<class 'KeyError'>, merge=False, merge_nested_lists=None, delimiter=':', pillarenv=None, saltenv=None)¶New in version 0.14.
Attempt to retrieve the named value from in-memory pillar data. If the pillar key is not present in the in-memory
pillar, then the value specified in the default
option (described
below) will be returned.
If the merge parameter is set to True
, the default will be recursively
merged into the returned pillar data.
The value can also represent a value in a nested dict using a ":" delimiter for the dict. This means that if a dict in pillar looks like this:
{'pkg': {'apache': 'httpd'}}
To retrieve the value associated with the apache
key in the pkg
dict this key can be passed as:
pkg:apache
The pillar key to get value from
The value specified by this option will be returned if the desired pillar key does not exist.
If a default value is specified, then it will be an empty string,
unless pillar_raise_on_missing
is set to True
, in
which case an error will be raised.
False
If True
, the retrieved values will be merged into the passed
default. When the default and the retrieved value are both
dictionaries, the dictionaries will be recursively merged.
New in version 2014.7.0.
Changed in version 2016.3.7,2016.11.4,2017.7.0: If the default and the retrieved value are not of the same type, then merging will be skipped and the retrieved value will be returned. Earlier releases raised an error in these cases.
If set to False
, lists nested within the retrieved pillar
dictionary will overwrite lists in default
. If set to True
,
nested lists will be merged into lists in default
. If unspecified
(the default), this option is inherited from the
pillar_merge_lists
minion config option.
Note
This option is ignored when merge
is set to False
.
New in version 2016.11.6.
Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage.
New in version 2014.7.0.
If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion's pillar data in memory (which can be sourced from more than one pillar environment).
Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment.
New in version 2017.7.0.
Included only for compatibility with
pillarenv_from_saltenv
, and is otherwise ignored.
New in version 2017.7.0.
CLI Example:
salt '*' pillar.get pkg:apache
salt '*' pillar.get abc::def|ghi delimiter='|'
salt.modules.pillar.
item
(*args, **kwargs)¶New in version 0.16.2.
Return one or more pillar entries from the in-memory pillar data.
Delimiter used to traverse nested dictionaries.
Note
This is different from pillar.get
in that no default value can be
specified. pillar.get
should
probably still be used in most cases to retrieve nested pillar
values, as it is a bit more flexible. One reason to use this
function instead of pillar.get
however is when it is desirable to retrieve the values of more than
one key, since pillar.get
can
only retrieve one key at a time.
New in version 2015.8.0.
If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion's pillar data in memory (which can be sourced from more than one pillar environment).
Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment.
New in version 2017.7.6,2018.3.1.
Included only for compatibility with
pillarenv_from_saltenv
, and is otherwise ignored.
New in version 2017.7.6,2018.3.1.
CLI Examples:
salt '*' pillar.item foo
salt '*' pillar.item foo:bar
salt '*' pillar.item foo bar baz
salt.modules.pillar.
items
(*args, **kwargs)¶Calls the master for a fresh pillar and generates the pillar data on the fly
Contrast with raw()
which returns the pillar data that is
currently loaded into the minion.
If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. these pillar variables will also override any variables of the same name in pillar or ext_pillar.
New in version 2015.5.0.
If specified, the data passed in the pillar
argument will be passed
through this renderer to decrypt it.
Note
This will decrypt on the minion side, so the specified renderer must be set up on the minion for this to work. Alternatively, pillar data can be decrypted master-side. For more information, see the Pillar Encryption documentation. Pillar data that is decrypted master-side, is not decrypted until the end of pillar compilation though, so minion-side decryption will be necessary if the encrypted pillar data must be made available in an decrypted state pillar/ext_pillar rendering.
New in version 2017.7.0.
Pass a specific pillar environment from which to compile pillar data.
If not specified, then the minion's pillarenv
option is
not used, and if that also is not specified then all configured pillar
environments will be merged into a single pillar dictionary and
returned.
New in version 2016.11.2.
Included only for compatibility with
pillarenv_from_saltenv
, and is otherwise ignored.
CLI Example:
salt '*' pillar.items
salt.modules.pillar.
keys
(key, delimiter=':')¶New in version 2015.8.0.
Attempt to retrieve a list of keys from the named value from the pillar.
The value can also represent a value in a nested dict using a ":" delimiter for the dict, similar to how pillar.get works.
Specify an alternate delimiter to use when traversing a nested dict
CLI Example:
salt '*' pillar.keys web:sites
salt.modules.pillar.
ls
(*args)¶New in version 2015.8.0.
Calls the master for a fresh pillar, generates the pillar data on the
fly (same as items()
), but only shows the available main keys.
CLI Examples:
salt '*' pillar.ls
salt.modules.pillar.
obfuscate
(*args)¶New in version 2015.8.0.
Same as items()
, but replace pillar values with a simple type indication.
This is useful to avoid displaying sensitive information on console or flooding the console with long output, such as certificates. For many debug or control purposes, the stakes lie more in dispatching than in actual values.
In case the value is itself a collection type, obfuscation occurs within the value. For mapping types, keys are not obfuscated. Here are some examples:
'secret password'
becomes '<str>'
['secret', 1]
becomes ['<str>', '<int>']
{'login': 'somelogin', 'pwd': 'secret'}
becomes
{'login': '<str>', 'pwd': '<str>'}
CLI Examples:
salt '*' pillar.obfuscate
salt.modules.pillar.
raw
(key=None)¶Return the raw pillar data that is currently loaded into the minion.
Contrast with items()
which calls the master to fetch the most
up-to-date Pillar.
CLI Example:
salt '*' pillar.raw
With the optional key argument, you can select a subtree of the pillar raw data.:
salt '*' pillar.raw key='roles'