<commit_before>.. _grains:

======
Grains
======

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. Grains are collected for the operating system, domain name,
IP address, kernel, OS type, memory, and many other system properties.

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.

Grain data is relatively static, though if system information changes
(for example, if network settings are changed), or if a new value is assigned
to a custom grain, grain data is refreshed.

.. note::

    Grains resolve to lowercase letters. For example, ``FOO``, and ``foo``
    target the same grain.


Listing Grains
==============

Available grains can be listed by using the 'grains.ls' module:

.. code-block:: bash

    salt '*' grains.ls

Grains data can be listed by using the 'grains.items' module:

.. code-block:: bash

    salt '*' grains.items


.. _static-custom-grains:

Grains in the Minion Config
===========================

Grains can also be statically assigned within the minion configuration file.
Just add the option :conf_minion:`grains` and pass options to it:

.. code-block:: yaml

    grains:
      roles:
        - webserver
        - memcache
      deployment: datacenter4
      cabinet: 13
      cab_u: 14-15

Then status data specific to your servers can be retrieved via Salt, or used
inside of the State system for matching. It also makes targeting, in the case
of the example above, simply based on specific data about your deployment.


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`` on the minion. 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

.. note::

    The content of ``/etc/salt/grains`` is ignored if you specify grains in the minion config.

.. note::

    Grains are static, and since they are not often changed, they will need a grains refresh when they are updated. You can do this by calling: ``salt minion saltutil.refresh_modules``

Matching Grains in the Top File
===============================

With correctly configured grains on the Minion, the :term:`top file` used in
Pillar or during Highstate can be made very efficient. For example, consider
the following configuration:

.. code-block:: yaml

    'node_type:webserver':
      - match: grain
      - webserver

    'node_type:postgres':
      - match: grain
      - postgres

    'node_type:redis':
      - match: grain
      - redis<commit_msg>Add doc note regarding static grains on proxy minions<commit_after>.. _grains:

======
Grains
======

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. Grains are collected for the operating system, domain name,
IP address, kernel, OS type, memory, and many other system properties.

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.

Grain data is relatively static, though if system information changes
(for example, if network settings are changed), or if a new value is assigned
to a custom grain, grain data is refreshed.

.. note::

    Grains resolve to lowercase letters. For example, ``FOO``, and ``foo``
    target the same grain.


Listing Grains
==============

Available grains can be listed by using the 'grains.ls' module:

.. code-block:: bash

    salt '*' grains.ls

Grains data can be listed by using the 'grains.items' module:

.. code-block:: bash

    salt '*' grains.items


.. _static-custom-grains:

Grains in the Minion Config
===========================

Grains can also be statically assigned within the minion configuration file.
Just add the option :conf_minion:`grains` and pass options to it:

.. code-block:: yaml

    grains:
      roles:
        - webserver
        - memcache
      deployment: datacenter4
      cabinet: 13
      cab_u: 14-15

Then status data specific to your servers can be retrieved via Salt, or used
inside of the State system for matching. It also makes targeting, in the case
of the example above, simply based on specific data about your deployment.


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`` on the minion. 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

.. note::

    The content of ``/etc/salt/grains`` is ignored if you specify grains in the minion config.

.. note::

    Grains are static, and since they are not often changed, they will need a grains refresh when they are updated. You can do this by calling: ``salt minion saltutil.refresh_modules``

.. note::

    You can equally configure static grains for Proxy Minions.
    As multiple Proxy Minion processes can run on the same machine, you need
    to index the files using the Minion ID, under ``/etc/salt/proxy.d/<minion ID>/grains``.
    For example, the grains for the Proxy Minion ``router1`` can be defined
    under ``/etc/salt/proxy.d/router1/grains``, while the grains for the
    Proxy Minion ``switch7`` can be put in ``/etc/salt/proxy.d/switch7/grains``.

Matching Grains in the Top File
===============================

With correctly configured grains on the Minion, the :term:`top file` used in
Pillar or during Highstate can be made very efficient. For example, consider
the following configuration:

.. code-block:: yaml

    'node_type:webserver':
      - match: grain
      - webserver

    'node_type:postgres':
      - match: grain
      - postgres

    'node_type:redis':
      - match: grain
      - redis
{'fraction_non_alphanumeric': 0.10196638122423089, 'fraction_numerical': 0.00507453219156359, 'mean_word_length': 3.4166666666666665, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3279445', 'n_tokens_mistral': 1795, 'n_tokens_neox': 1689, 'n_words': 828}