valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 08:58:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Renderer index re-write for clarity.

Browse Source
This commit is contained in:
Mike Place 2014-02-19 14:16:14 -07:00
parent 6186eeab68
commit 2a6ee163f0
1 changed files with 31 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
doc/ref/returners/index.rst
View File

@ -3,24 +3,23 @@ Returners
=========
By default the return values of the commands sent to the Salt minions are
returned to the salt-master. But since the commands executed on the Salt
minions are detached from the call on the Salt master, anything at all can be
done with the results data.
returned to the Salt master, however anything at all can be done with the results
data.
This is where the returner interface comes in. Returners are modules called
in addition to returning the data to the Salt master.
By using a Salt returner, results data can be redirected to external data-stores
for analysis and archival.
The returner interface allows the return data to be sent to any system that
can receive data. This means that return data can be sent to a Redis server,
a MongoDB server, a MySQL server, or any system!
a MongoDB server, a MySQL server, or any system.
.. seealso:: :ref:`Full list of builtin returners <all-salt.returners>`
Using Returners
===============
All commands will return the command data back to the master. Adding more
returners will ensure that the data is also sent to the specified returner
All Salt commands will return the command data back to the master. Specifying
returners will ensure that the data is _also_ sent to the specified returner
interfaces.
Specifying what returners to use is done when the command is invoked:
@ -43,12 +42,13 @@ test.ping command will be sent out to the three named returners.
Writing a Returner
==================
A returner is a module which contains a returner function, the returner
function must accept a single argument. this argument is the return data from
A returner is a Python module which contains a function called ``returner``.
The ``returner`` function must accept a single argument for the return data from
the called minion function. So if the minion function ``test.ping`` is called
the value of the argument will be ``True``.
A simple returner is implemented here:
A simple returner is implemented below:
.. code-block:: python
@ -69,23 +69,28 @@ A simple returner is implemented here:
serv.sadd('jobs', ret['jid'])
serv.sadd(ret['jid'], ret['id'])
This simple example of a returner set to send the data to a redis server
serializes the data as json and sets it in redis.
The above example of a returner set to send the data to a Redis server
serializes the data as JSON and sets it in redis.
You can place your custom returners in a ``_returners`` directory within the
:conf_master:`file_roots` specified by the master config file. These custom
returners are distributed when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
Place custom returners in a ``_returners`` directory within the
:conf_master:`file_roots` specified by the master config file.
Any custom returners which have been synced to a minion, that are named the
same as one of Salt's default set of returners, will take the place of the
default returner with the same name. Note that a returner's default name is its
filename (i.e. ``foo.py`` becomes returner ``foo``), but that its name can be
overridden by using a :ref:`__virtual__ function <virtual-modules>`. A good
example of this can be found in the `redis`_ returner, which is named
``redis_return.py`` but is loaded as simply ``redis``:
Custom returners are distributed when any of the following are called:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom returners which have been synced to a minion that are named the
same as one of Salt's default set of returners will take the place of the
default returner with the same name.
Note that a returner's default name is its filename (i.e. ``foo.py`` becomes
returner ``foo``), but that its name can be overridden by using a
:ref:`__virtual__ function <virtual-modules>`. A good example of this can be
found in the `redis`_ returner, which is named ``redis_return.py`` but is
loaded as simply ``redis``:
.. code-block:: python
@ -101,9 +106,3 @@ example of this can be found in the `redis`_ returner, which is named
return 'redis'
.. _`redis`: https://github.com/saltstack/salt/blob/develop/salt/returners/redis_return.py
Examples
--------
The collection of built-in Salt returners can be found here:
:blob:`salt/returners`