2011-05-23 07:17:30 +00:00
|
|
|
======
|
|
|
|
Grains
|
|
|
|
======
|
|
|
|
|
2011-06-24 01:36:44 +00:00
|
|
|
Salt comes with an interface to derive information about the underlying system.
|
|
|
|
This is called the grains interface, because it presents salt with grains of
|
|
|
|
information.
|
|
|
|
|
2012-10-11 06:22:01 +00:00
|
|
|
.. glossary::
|
|
|
|
|
|
|
|
Grains
|
|
|
|
Static bits of information that a minion collects about the system when
|
|
|
|
the minion first starts.
|
|
|
|
|
2011-06-24 01:36:44 +00:00
|
|
|
The grains interface is made available to Salt modules and components so that
|
|
|
|
the right salt minion commands are automatically available on the right
|
|
|
|
systems.
|
|
|
|
|
|
|
|
It is important to remember that grains are bits of information loaded when
|
|
|
|
the salt minion starts, so this information is static. This means that the
|
|
|
|
information in grains is unchanging, therefore the nature of the data is
|
|
|
|
static. So grains information are things like the running kernel, or the
|
|
|
|
operating system.
|
|
|
|
|
2012-05-06 18:46:08 +00:00
|
|
|
Match all CentOS minions::
|
|
|
|
|
|
|
|
salt -G 'os:CentOS' test.ping
|
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
Match all minions with 64-bit CPUs and return number of available cores::
|
2012-05-06 18:46:08 +00:00
|
|
|
|
|
|
|
salt -G 'cpuarch:x86_64' grains.item num_cpus
|
|
|
|
|
2013-06-14 02:05:19 +00:00
|
|
|
Additionally, globs can be used in grain matches, and grains that are nested in
|
|
|
|
a dictionary can be matched by adding a colon for each level that is traversed.
|
|
|
|
For example, the following will match hosts that have a grain called
|
|
|
|
``ec2_tags``, which itself is a dict with a key named ``environment``, which
|
|
|
|
has a value that contains the word ``production``::
|
2013-06-14 01:28:11 +00:00
|
|
|
|
|
|
|
salt -G 'ec2_tags:environment:*production*'
|
|
|
|
|
|
|
|
|
2013-03-07 21:32:46 +00:00
|
|
|
Listing Grains
|
|
|
|
==============
|
|
|
|
|
|
|
|
Available grains can be listed by using the 'grains.ls' module::
|
|
|
|
|
|
|
|
salt '*' grains.ls
|
|
|
|
|
|
|
|
Grains data can be listed by using the 'grains.items' module::
|
|
|
|
|
2013-03-07 22:27:22 +00:00
|
|
|
salt '*' grains.items
|
2013-03-07 21:32:46 +00:00
|
|
|
|
2013-07-08 04:23:27 +00:00
|
|
|
|
2012-02-09 20:14:35 +00:00
|
|
|
Grains in the Minion Config
|
|
|
|
===========================
|
|
|
|
|
|
|
|
Grains can also be statically assigned within the minion configuration file.
|
|
|
|
Just add the option ``grains`` and pass options to it:
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
grains:
|
2012-03-15 00:09:19 +00:00
|
|
|
roles:
|
2012-02-09 20:14:35 +00:00
|
|
|
- webserver
|
|
|
|
- memcache
|
|
|
|
deployment: datacenter4
|
|
|
|
cabinet: 13
|
|
|
|
cab_u: 14-15
|
|
|
|
|
2012-03-15 00:09:19 +00:00
|
|
|
Then status data specific to your servers can be retrieved via Salt, or used
|
2012-05-23 04:43:12 +00:00
|
|
|
inside of the State system for matching. It also makes targeting, in the case
|
2012-02-09 20:14:35 +00:00
|
|
|
of the example above, simply based on specific data about your deployment.
|
|
|
|
|
2013-07-08 04:23:27 +00:00
|
|
|
|
|
|
|
Grains in /etc/salt/grains
|
|
|
|
==========================
|
|
|
|
|
|
|
|
If you do not want to place your custom static grains in the minion config
|
|
|
|
file, you can also put them in ``/etc/salt/grains``. They are configured in the
|
|
|
|
same way as in the above example, only without a top-level ``grains:`` key:
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
roles:
|
|
|
|
- webserver
|
|
|
|
- memcache
|
|
|
|
deployment: datacenter4
|
|
|
|
cabinet: 13
|
|
|
|
cab_u: 14-15
|
|
|
|
|
|
|
|
.. admonition:: Precedece of Custom Static Grains
|
|
|
|
|
|
|
|
Be careful when defining grains both in ``/etc/salt/grains`` and within the
|
|
|
|
minion config file. If a grain is defined in both places, the value in the
|
|
|
|
minion config file takes precedence, and will always be used over its
|
|
|
|
counterpart in ``/etc/salt/grains``.
|
|
|
|
|
|
|
|
|
2011-06-24 01:36:44 +00:00
|
|
|
Writing Grains
|
|
|
|
==============
|
|
|
|
|
2012-03-15 00:09:19 +00:00
|
|
|
Grains are easy to write. The grains interface is derived by executing
|
|
|
|
all of the "public" functions found in the modules located in the grains
|
|
|
|
package or the custom grains directory. The functions in the modules of
|
2012-05-23 04:43:12 +00:00
|
|
|
the grains must return a Python `dict`_, where the keys in the dict are the
|
2012-03-15 00:09:19 +00:00
|
|
|
names of the grains and the values are the values.
|
2011-06-24 01:36:44 +00:00
|
|
|
|
2012-12-19 05:29:36 +00:00
|
|
|
Custom grains should be placed in a ``_grains`` directory located under the
|
|
|
|
:conf_master:`file_roots` specified by the master config file. They will be
|
2013-02-03 20:54:04 +00:00
|
|
|
distributed to the minions when :mod:`state.highstate
|
|
|
|
<salt.modules.state.highstate>` is run, or by executing the
|
|
|
|
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
|
|
|
|
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
2012-12-19 05:29:36 +00:00
|
|
|
|
|
|
|
Before adding a grain to Salt, consider what the grain is and remember that
|
|
|
|
grains need to be static data. If the data is something that is likely to
|
|
|
|
change, consider using :doc:`Pillar <../pillar/index>` instead.
|
2011-06-24 01:36:44 +00:00
|
|
|
|
2012-05-23 04:43:12 +00:00
|
|
|
.. _`dict`: http://docs.python.org/library/stdtypes.html#typesmapping
|
|
|
|
|
2013-07-08 04:23:27 +00:00
|
|
|
|
2011-06-24 01:36:44 +00:00
|
|
|
Examples of Grains
|
|
|
|
------------------
|
|
|
|
|
|
|
|
The core module in the grains package is where the main grains are loaded by
|
2012-05-23 04:43:12 +00:00
|
|
|
the Salt minion and provides the principal example of how to write grains:
|
2011-06-24 01:36:44 +00:00
|
|
|
|
2011-09-25 06:36:41 +00:00
|
|
|
:blob:`salt/grains/core.py`
|
2012-01-31 23:53:48 +00:00
|
|
|
|
2013-07-08 04:23:27 +00:00
|
|
|
|
2012-01-31 23:53:48 +00:00
|
|
|
Syncing Grains
|
|
|
|
--------------
|
|
|
|
|
2012-02-01 00:05:42 +00:00
|
|
|
Syncing grains can be done a number of ways, they are automatically synced when
|
|
|
|
state.highstate is called, or the grains can be synced and reloaded by calling
|
|
|
|
the saltutil.sync_grains or saltutil.sync_all functions.
|