saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #27557 from jfindlay/mine_doc

Browse source 
add doc motivating mine vs grains
This commit is contained in:
Colton Myers 2015-09-30 11:49:46 -06:00
commit 7201ce71e4
1 changed files with 29 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
doc/topics/mine/index.rst
View file

@ -6,22 +6,33 @@
The Salt Mine
=============
The Salt Mine is used to collect arbitrary data from minions and store it on
the master. This data is then made available to all minions via the
The Salt Mine is used to collect arbitrary data from Minions and store it on
the Master. This data is then made available to all Minions via the
:py:mod:`salt.modules.mine` module.
The data is gathered on the minion and sent back to the master where only
the most recent data is maintained (if long term data is required use
returners or the external job cache).
Mine data is gathered on the Minion and sent back to the Master where only the
most recent data is maintained (if long term data is required use returners or
the external job cache).
Mine vs Grains
==============
Mine data is designed to be much more up-to-date than grain data. Grains are
refreshed on a very limited basis and are largely static data. Mines are
designed to replace slow peer publishing calls when Minions need data from
other Minions. Rather than having a Minion reach out to all the other Minions
for a piece of data, the Salt Mine, running on the Master, can collect it from
all the Minions every :ref:`mine-interval`, resulting in
almost fresh data at any given time, with much less overhead.
Mine Functions
==============
To enable the Salt Mine the `mine_functions` option needs to be applied to a
minion. This option can be applied via the minion's configuration file, or the
minion's Pillar. The `mine_functions` option dictates what functions are being
executed and allows for arguments to be passed in. If no arguments are passed,
an empty list must be added:
To enable the Salt Mine the ``mine_functions`` option needs to be applied to a
Minion. This option can be applied via the Minion's configuration file, or the
Minion's Pillar. The ``mine_functions`` option dictates what functions are
being executed and allows for arguments to be passed in. If no arguments are
passed, an empty list must be added:
.. code-block:: yaml
@ -51,12 +62,14 @@ calls of the same function with different arguments.
mine_function: network.ip_addrs
lo: True
.. _mine_interval:
Mine Interval
=============
The Salt Mine functions are executed when the minion starts and at a given
The Salt Mine functions are executed when the Minion starts and at a given
interval by the scheduler. The default interval is every 60 minutes and can
be adjusted for the minion via the `mine_interval` option:
be adjusted for the Minion via the ``mine_interval`` option:
.. code-block:: yaml
@ -67,7 +80,7 @@ Mine in Salt-SSH
As of the 2015.5.0 release of salt, salt-ssh supports ``mine.get``.
Because the minions cannot provide their own ``mine_functions`` configuration,
Because the Minions cannot provide their own ``mine_functions`` configuration,
we retrieve the args for specified mine functions in one of three places,
searched in the following order:
@ -93,10 +106,10 @@ stored in a different location. Here is an example of a flat roster containing
Because of the differences in the architecture of salt-ssh, ``mine.get``
calls are somewhat inefficient. Salt must make a new salt-ssh call to each
of the minions in question to retrieve the requested data, much like a
of the Minions in question to retrieve the requested data, much like a
publish call. However, unlike publish, it must run the requested function
as a wrapper function, so we can retrieve the function args from the pillar
of the minion in question. This results in a non-trivial delay in
of the Minion in question. This results in a non-trivial delay in
retrieving the requested data.
Example
@ -104,7 +117,7 @@ Example
One way to use data from Salt Mine is in a State. The values can be retrieved
via Jinja and used in the SLS file. The following example is a partial HAProxy
configuration file and pulls IP addresses from all minions with the "web" grain
configuration file and pulls IP addresses from all Minions with the "web" grain
to add them to the pool of load balanced servers.
:file:`/srv/pillar/top.sls`: