2011-05-23 07:17:30 +00:00
|
|
|
=======
|
|
|
|
Modules
|
|
|
|
=======
|
|
|
|
|
2014-01-07 02:57:01 +00:00
|
|
|
Salt modules are the functions called by the :command:`salt` command. It should
|
|
|
|
be noted that the modules listed here are execution modules, not state modules.
|
2011-05-23 07:17:30 +00:00
|
|
|
|
2011-11-13 10:06:00 +00:00
|
|
|
.. seealso:: :ref:`Full list of builtin modules <all-salt.modules>`
|
2011-06-25 07:34:33 +00:00
|
|
|
|
|
|
|
Salt ships with many modules that cover a wide variety of tasks.
|
|
|
|
|
2013-02-11 04:20:56 +00:00
|
|
|
Modules Are Easy to Write!
|
|
|
|
==========================
|
2011-05-23 07:17:30 +00:00
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
Salt modules are amazingly simple to write. Just write a regular Python module
|
2013-07-18 17:26:39 +00:00
|
|
|
or a regular `Cython`_ module and place it a directory called ``_modules/``
|
|
|
|
within the :conf_master:`file_roots` specified by the master config file, and
|
|
|
|
they will be synced to the minions when :mod:`state.highstate
|
2013-02-03 20:54:04 +00:00
|
|
|
<salt.modules.state.highstate>` is run, or by executing the
|
|
|
|
:mod:`saltutil.sync_modules <salt.modules.saltutil.sync_modules>` or
|
|
|
|
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
2011-05-23 07:17:30 +00:00
|
|
|
|
2013-07-09 02:36:34 +00:00
|
|
|
Any custom modules which have been synced to a minion, that are named the
|
|
|
|
same as one of Salt's default set of modules, will take the place of the default
|
|
|
|
module with the same name. Note that a module's default name is its filename
|
|
|
|
(i.e. ``foo.py`` becomes module ``foo``), but that its name can be overridden
|
|
|
|
by using a :ref:`__virtual__ function <virtual-modules>`.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
Since Salt modules are just Python/Cython modules, there are no restraints on
|
|
|
|
what you can put inside of a Salt module. If a Salt module has errors and
|
|
|
|
cannot be imported, the Salt minion will continue to load without issue and the
|
|
|
|
module with errors will simply be omitted.
|
2011-05-23 07:17:30 +00:00
|
|
|
|
|
|
|
If adding a Cython module the file must be named ``<modulename>.pyx`` so that
|
|
|
|
the loader knows that the module needs to be imported as a Cython module. The
|
|
|
|
compilation of the Cython module is automatic and happens when the minion
|
|
|
|
starts, so only the ``*.pyx`` file is required.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
.. _`Cython`: http://cython.org/
|
|
|
|
|
2011-06-22 03:29:51 +00:00
|
|
|
Cross Calling Modules
|
|
|
|
=====================
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
All of the Salt modules are available to each other, and can be "cross called".
|
|
|
|
This means that, when creating a module, functions in modules that already exist
|
2011-06-22 03:29:51 +00:00
|
|
|
can be called.
|
|
|
|
|
|
|
|
The variable ``__salt__`` is packed into the modules after they are loaded into
|
2013-07-23 16:20:50 +00:00
|
|
|
the Salt minion. This variable is a :ref:`Python dictionary <python2:typesmapping>`
|
|
|
|
of all of the Salt functions, laid out in the same way that they are made available
|
|
|
|
to the Salt command.
|
2011-06-22 03:29:51 +00:00
|
|
|
|
2013-07-23 16:20:50 +00:00
|
|
|
Salt modules can be cross called by accessing the value in the ``__salt__`` dict:
|
2011-06-22 03:29:51 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
2012-03-15 00:09:19 +00:00
|
|
|
|
2011-06-22 03:29:51 +00:00
|
|
|
def foo(bar):
|
|
|
|
return __salt__['cmd.run'](bar)
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
This code will call the Salt cmd module's ``run`` function and pass the argument
|
2011-06-22 03:29:51 +00:00
|
|
|
``bar``.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
|
2011-05-23 07:17:30 +00:00
|
|
|
Preloaded Modules Data
|
|
|
|
======================
|
|
|
|
|
|
|
|
When interacting with modules often it is nice to be able to read information
|
|
|
|
dynamically about the minion, or load in configuration parameters for a module.
|
|
|
|
Salt allows for different types of data to be loaded into the modules by the
|
|
|
|
minion, as of this writing Salt loads information gathered from the Salt Grains
|
|
|
|
system and from the minion configuration file.
|
|
|
|
|
|
|
|
Grains Data
|
|
|
|
-----------
|
|
|
|
|
|
|
|
The Salt minion detects information about the system when started. This allows
|
|
|
|
for modules to be written dynamically with respect to the underlying hardware
|
2012-05-23 04:43:12 +00:00
|
|
|
and operating system. This information is referred to as Salt Grains, or
|
|
|
|
"grains of salt". The Grains system was introduced to replace Facter, since
|
|
|
|
relying on a Ruby application from a Python application was both slow and
|
|
|
|
inefficient. Grains support replaces Facter in all Salt releases after 0.8
|
2011-05-23 07:17:30 +00:00
|
|
|
|
2013-07-23 16:20:50 +00:00
|
|
|
The values detected by the Salt Grains on the minion are available in a
|
|
|
|
:ref:`dict <python2:typesmapping>` named ``__grains__`` and can be accessed
|
|
|
|
from within callable objects in the Python modules.
|
2011-05-23 07:17:30 +00:00
|
|
|
|
|
|
|
To see the contents of the grains dict for a given system in your deployment
|
|
|
|
run the :func:`grains.items` function:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
salt 'hostname' grains.items
|
|
|
|
|
|
|
|
To use the ``__grains__`` dict simply call it as a Python dict from within your
|
|
|
|
code, an excellent example is available in the Grains module:
|
|
|
|
:mod:`salt.modules.grains`.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
|
2011-05-23 07:17:30 +00:00
|
|
|
Module Configuration
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
Since parameters for configuring a module may be desired, Salt allows for
|
|
|
|
configuration information stored in the main minion config file to be passed to
|
|
|
|
the modules.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
Since the minion configuration file is a YAML document, arbitrary configuration
|
2011-05-23 07:17:30 +00:00
|
|
|
data can be passed in the minion config that is read by the modules. It is
|
|
|
|
**strongly** recommended that the values passed in the configuration file match
|
|
|
|
the module. This means that a value intended for the ``test`` module should be
|
|
|
|
named ``test.<value>``.
|
|
|
|
|
|
|
|
Configuration also requires that default configuration parameters need to be
|
|
|
|
loaded as well. This can be done simply by adding the ``__opts__`` dict to the
|
|
|
|
top level of the module.
|
|
|
|
|
|
|
|
The test module contains usage of the module configuration, and the default
|
|
|
|
configuration file for the minion contains the information and format used to
|
|
|
|
pass data to the modules. :mod:`salt.modules.test`, :file:`conf/minion`.
|
|
|
|
|
2011-07-09 20:24:54 +00:00
|
|
|
Printout Configuration
|
|
|
|
======================
|
|
|
|
|
|
|
|
Since module functions can return different data, and the way the data is
|
|
|
|
printed can greatly change the presentation, Salt has a printout
|
|
|
|
configuration.
|
|
|
|
|
|
|
|
When writing a module the ``__outputter__`` dict can be declared in the module.
|
|
|
|
The ``__outputter__`` dict contains a mapping of function name to Salt
|
|
|
|
Outputter.
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
2011-07-17 23:13:32 +00:00
|
|
|
__outputter__ = {
|
2011-07-09 20:24:54 +00:00
|
|
|
'run': 'txt'
|
|
|
|
}
|
|
|
|
|
|
|
|
This will ensure that the text outputter is used.
|
|
|
|
|
2013-07-09 02:36:34 +00:00
|
|
|
|
|
|
|
.. _virtual-modules:
|
|
|
|
|
2011-06-22 04:44:10 +00:00
|
|
|
Virtual Modules
|
|
|
|
===============
|
|
|
|
|
|
|
|
Sometimes a module should be presented in a generic way. A good example of this
|
|
|
|
can be found in the package manager modules. The package manager changes from
|
2012-05-23 04:43:12 +00:00
|
|
|
one operating system to another, but the Salt module that interfaces with the
|
2011-06-22 04:44:10 +00:00
|
|
|
package manager can be presented in a generic way.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
The Salt modules for package managers all contain a ``__virtual__`` function
|
2011-06-22 04:44:10 +00:00
|
|
|
which is called to define what systems the module should be loaded on.
|
|
|
|
|
2013-07-23 16:55:45 +00:00
|
|
|
The ``__virtual__`` function is used to return either a
|
2013-07-23 17:21:01 +00:00
|
|
|
:ref:`string <python2:typesseq>` or :py:data:`False`. If
|
2011-06-22 04:44:10 +00:00
|
|
|
False is returned then the module is not loaded, if a string is returned then
|
|
|
|
the module is loaded with the name of the string.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
This means that the package manager modules can be presented as the ``pkg`` module
|
2011-06-22 04:44:10 +00:00
|
|
|
regardless of what the actual module is named.
|
|
|
|
|
|
|
|
The package manager modules are the best example of using the ``__virtual__``
|
2013-11-09 21:10:12 +00:00
|
|
|
function. Some examples:
|
|
|
|
|
|
|
|
- :blob:`pacman.py <salt/modules/pacman.py>`
|
|
|
|
- :blob:`yumpkg.py <salt/modules/yumpkg.py>`
|
|
|
|
- :blob:`apt.py <salt/modules/apt.py>`
|
2011-06-22 04:44:10 +00:00
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
|
2011-05-23 07:17:30 +00:00
|
|
|
Documentation
|
|
|
|
=============
|
|
|
|
|
|
|
|
Salt modules are self documenting, the :func:`sys.doc` function will return the
|
2012-08-30 21:28:52 +00:00
|
|
|
documentation for all available modules:
|
2011-05-23 07:17:30 +00:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
salt '*' sys.doc
|
|
|
|
|
2013-07-27 12:07:44 +00:00
|
|
|
This function simply prints out the docstrings found in the modules; when
|
2013-03-18 19:59:27 +00:00
|
|
|
writing Salt modules, please follow the formatting conventions for docstrings as
|
2011-05-23 07:17:30 +00:00
|
|
|
they appear in the other modules.
|
|
|
|
|
2011-06-22 04:44:10 +00:00
|
|
|
Adding Documentation to Salt Modules
|
|
|
|
------------------------------------
|
|
|
|
|
|
|
|
Since life is much better with documentation, it is strongly suggested that
|
|
|
|
all Salt modules have documentation added. Any Salt modules submitted for
|
|
|
|
inclusion in the main distribution of Salt will be required to have
|
|
|
|
documentation.
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
Documenting Salt modules is easy! Just add a `Python docstring`_ to the function.
|
2011-06-22 04:44:10 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
def spam(eggs):
|
|
|
|
'''
|
|
|
|
A function to make some spam with eggs!
|
|
|
|
|
2012-05-13 18:50:33 +00:00
|
|
|
CLI Example::
|
|
|
|
|
|
|
|
salt '*' test.spam eggs
|
2011-06-22 04:44:10 +00:00
|
|
|
'''
|
|
|
|
return eggs
|
|
|
|
|
|
|
|
Now when the sys.doc call is executed the docstring will be cleanly returned
|
|
|
|
to the calling terminal.
|
|
|
|
|
2013-07-23 20:45:26 +00:00
|
|
|
.. _`Python docstring`: http://docs.python.org/2/glossary.html#term-docstring
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
|
2013-02-11 04:20:56 +00:00
|
|
|
Add Module metadata
|
|
|
|
-------------------
|
2012-12-03 18:39:38 +00:00
|
|
|
|
|
|
|
Add information about the module using the following field lists:
|
|
|
|
|
|
|
|
.. code-block:: text
|
|
|
|
|
|
|
|
:maintainer: Thomas Hatch <thatch@saltstack.com, Seth House <shouse@saltstack.com>
|
|
|
|
:maturity: new
|
|
|
|
:depends: python-mysqldb
|
|
|
|
:platform: all
|
|
|
|
|
2013-02-18 08:11:51 +00:00
|
|
|
The maintainer field is a comma-delimited list of developers who help maintain
|
2012-12-03 18:39:38 +00:00
|
|
|
this module.
|
|
|
|
|
|
|
|
The maturity field indicates the level of quality and testing for this module.
|
|
|
|
Standard labels will be determined.
|
|
|
|
|
|
|
|
The depends field is a comma-delimited list of modules that this module depends
|
|
|
|
on.
|
|
|
|
|
2013-02-18 07:26:28 +00:00
|
|
|
The platform field is a comma-delimited list of platforms that this module is
|
2012-12-03 18:39:38 +00:00
|
|
|
known to run on.
|
|
|
|
|
2011-05-23 07:17:30 +00:00
|
|
|
How Functions are Read
|
|
|
|
======================
|
|
|
|
|
2012-12-03 18:39:38 +00:00
|
|
|
In Salt, Python callable objects contained within a module are made available
|
|
|
|
to the Salt minion for use. The only exception to this rule is a callable
|
|
|
|
object with a name starting with an underscore ``_``.
|
2011-05-23 07:17:30 +00:00
|
|
|
|
|
|
|
Objects Loaded Into the Salt Minion
|
|
|
|
-----------------------------------
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
def foo(bar):
|
|
|
|
return bar
|
|
|
|
|
|
|
|
class baz:
|
|
|
|
def __init__(self, quo):
|
2012-05-13 20:49:43 +00:00
|
|
|
pass
|
2011-05-23 07:17:30 +00:00
|
|
|
|
|
|
|
Objects NOT Loaded into the Salt Minion
|
|
|
|
---------------------------------------
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
def _foobar(baz): # Preceded with an _
|
|
|
|
return baz
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
cheese = {} # Not a callable Python object
|
2011-06-22 04:44:10 +00:00
|
|
|
|
2013-10-16 17:10:02 +00:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
Some callable names also end with an underscore ``_``, to avoid keyword clashes
|
|
|
|
with Python keywords. When using Salt modules, or state modules, with these
|
|
|
|
in them the trailing underscore should be omitted.
|
|
|
|
|
2013-06-15 00:19:53 +00:00
|
|
|
Useful Decorators for Modules
|
2013-06-26 17:29:40 +00:00
|
|
|
=============================
|
2013-06-15 00:19:53 +00:00
|
|
|
Sometimes when writing modules for large scale deployments you run into some small
|
|
|
|
things that end up severely complicating the code. To alleviate some of this pain
|
|
|
|
Salt has some useful decorators for use within modules!
|
|
|
|
|
|
|
|
Depends Decorator
|
|
|
|
-----------------
|
|
|
|
When writing custom modules there are many times where some of the module will
|
|
|
|
work on all hosts, but some functions require (for example) a service to be installed.
|
|
|
|
Instead of trying to wrap much of the code in large try/except blocks you can use
|
2013-07-05 20:35:51 +00:00
|
|
|
a simple decorator to do this. If the dependencies passed to the decorator don't
|
2013-06-15 00:19:53 +00:00
|
|
|
exist, then the salt minion will remove those functions from the module on that host.
|
2013-11-15 20:50:17 +00:00
|
|
|
If a "fallback_function" is defined, it will replace the function instead of removing it
|
2013-06-15 00:19:53 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
from salt.utils.decorators import depends
|
|
|
|
try:
|
2013-07-05 20:35:51 +00:00
|
|
|
import dependency_that_sometimes_exists
|
2013-06-15 00:19:53 +00:00
|
|
|
except ImportError:
|
|
|
|
pass
|
|
|
|
|
2013-07-05 20:35:51 +00:00
|
|
|
@depends('dependency_that_sometimes_exists')
|
2013-06-15 00:19:53 +00:00
|
|
|
def foo():
|
|
|
|
'''
|
2013-07-05 20:35:51 +00:00
|
|
|
Function with a dependency on the "dependency_that_sometimes_exists" module,
|
|
|
|
if the "dependency_that_sometimes_exists" is missing this function will not exist
|
2013-06-15 00:19:53 +00:00
|
|
|
'''
|
|
|
|
return True
|
|
|
|
|
|
|
|
def _fallback():
|
|
|
|
'''
|
|
|
|
Fallback function for the depends decorator to replace a function with
|
|
|
|
'''
|
2013-07-05 20:35:51 +00:00
|
|
|
return '"dependency_that_sometimes_exists" needs to be installed for this function to exist'
|
2013-06-15 00:19:53 +00:00
|
|
|
|
2013-11-15 20:50:17 +00:00
|
|
|
@depends('dependency_that_sometimes_exists', fallback_function=_fallback)
|
2013-06-15 00:19:53 +00:00
|
|
|
def foo():
|
|
|
|
'''
|
2013-07-05 20:35:51 +00:00
|
|
|
Function with a dependency on the "dependency_that_sometimes_exists" module.
|
|
|
|
If the "dependency_that_sometimes_exists" is missing this function will be
|
2013-06-15 00:19:53 +00:00
|
|
|
replaced with "_fallback"
|
|
|
|
'''
|
|
|
|
return True
|
|
|
|
|
|
|
|
|
2011-06-22 04:44:10 +00:00
|
|
|
Examples of Salt Modules
|
|
|
|
========================
|
|
|
|
|
|
|
|
The existing Salt modules should be fairly easy to read and understand, the
|
|
|
|
goal of the main distribution's Salt modules is not only to build a set of
|
2012-05-23 04:43:12 +00:00
|
|
|
functions for Salt, but to stand as examples for building out more Salt
|
2011-06-22 04:44:10 +00:00
|
|
|
modules.
|
|
|
|
|
|
|
|
The existing modules can be found here:
|
2011-09-25 06:36:41 +00:00
|
|
|
:blob:`salt/modules`
|
2011-06-22 04:44:10 +00:00
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
The most simple module is the test module, it contains the simplest Salt
|
|
|
|
function, ``test.ping``:
|
2011-06-22 04:44:10 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
def ping():
|
|
|
|
'''
|
|
|
|
Just used to make sure the minion is up and responding
|
|
|
|
Return True
|
|
|
|
|
2012-05-13 18:50:33 +00:00
|
|
|
CLI Example::
|
|
|
|
|
|
|
|
salt '*' test.ping
|
2011-06-22 04:44:10 +00:00
|
|
|
'''
|
|
|
|
return True
|