mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +00:00
120 lines
3.7 KiB
ReStructuredText
120 lines
3.7 KiB
ReStructuredText
===================
|
|
Dunder Dictionaries
|
|
===================
|
|
|
|
Salt provides several special "dunder" dictionaries as a convenience for Salt
|
|
development. These include ``__opts__``, ``__context__``, ``__salt__``, and
|
|
others. This document will describe each dictionary and detail where they exist
|
|
and what information and/or functionality they provide.
|
|
|
|
|
|
__opts__
|
|
--------
|
|
|
|
Available in
|
|
~~~~~~~~~~~~
|
|
|
|
- All loader modules
|
|
|
|
The ``__opts__`` dictionary contains all of the options passed in the
|
|
configuration file for the master or minion.
|
|
|
|
.. note::
|
|
|
|
In many places in salt, instead of pulling raw data from the __opts__
|
|
dict, configuration data should be pulled from the salt `get` functions
|
|
such as config.get, aka - __salt__['config.get']('foo:bar')
|
|
The `get` functions also allow for dict traversal via the *:* delimiter.
|
|
Consider using get functions whenever using __opts__ or __pillar__ and
|
|
__grains__ (when using grains for configuration data)
|
|
|
|
The configuration file data made available in the ``__opts__`` dictionary is the
|
|
configuration data relative to the running daemon. If the modules are loaded and
|
|
executed by the master, then the master configuration data is available, if the
|
|
modules are executed by the minion, then the minion configuration is
|
|
available. Any additional information passed into the respective configuration
|
|
files is made available
|
|
|
|
__salt__
|
|
--------
|
|
|
|
Available in
|
|
~~~~~~~~~~~~
|
|
|
|
- Execution Modules
|
|
- State Modules
|
|
- Returners
|
|
- Runners
|
|
|
|
``__salt__`` contains the execution module functions. This allows for all
|
|
functions to be called as they have been set up by the salt loader.
|
|
|
|
.. code-block:: python
|
|
|
|
__salt__['cmd.run']('fdisk -l')
|
|
__salt__['network.ip_addrs']()
|
|
|
|
.. note::
|
|
|
|
When used in runners, ``__salt__`` references other runner modules, and not
|
|
execution modules.
|
|
|
|
__grains__
|
|
----------
|
|
|
|
Available in
|
|
~~~~~~~~~~~~
|
|
|
|
- Execution Modules
|
|
- State Modules
|
|
- Returners
|
|
- External Pillar
|
|
|
|
The ``__grains__`` dictionary contains the grains data generated by the minion
|
|
that is currently being worked with. In execution modules, state modules and
|
|
returners this is the grains of the minion running the calls, when generating
|
|
the external pillar the ``__grains__`` is the grains data from the minion that
|
|
the pillar is being generated for.
|
|
|
|
__pillar__
|
|
-----------
|
|
|
|
Available in
|
|
~~~~~~~~~~~~
|
|
|
|
- Execution Modules
|
|
- State Modules
|
|
- Returners
|
|
|
|
The ``__pillar__`` dictionary contains the pillar for the respective minion.
|
|
|
|
__context__
|
|
-----------
|
|
|
|
``__context__`` exists in state modules and execution modules.
|
|
|
|
During a state run the ``__context__`` dictionary persists across all states
|
|
that are run and then is destroyed when the state ends.
|
|
|
|
When running an execution module ``__context__`` persists across all module
|
|
executions until the modules are refreshed; such as when
|
|
:py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>` or
|
|
:py:func:`state.apply <salt.modules.state.apply_>` are executed.
|
|
|
|
A great place to see how to use ``__context__`` is in the cp.py module in
|
|
salt/modules/cp.py. The fileclient authenticates with the master when it is
|
|
instantiated and then is used to copy files to the minion. Rather than create a
|
|
new fileclient for each file that is to be copied down, one instance of the
|
|
fileclient is instantiated in the ``__context__`` dictionary and is reused for
|
|
each file. Here is an example from salt/modules/cp.py:
|
|
|
|
.. code-block:: python
|
|
|
|
if not 'cp.fileclient' in __context__:
|
|
__context__['cp.fileclient'] = salt.fileclient.get_file_client(__opts__)
|
|
|
|
|
|
.. note:: Because __context__ may or may not have been destroyed, always be
|
|
sure to check for the existence of the key in __context__ and
|
|
generate the key before using it.
|