GRAINS

Salt提供了一个接口，用于获取被管理系统的有关信息。这被称为grains interface，因为它为salt提供grains信息。 Grains信息涉及操作系统、域名、IP地址、内核、操作系统类型、内存和许多其他系统属性。

Salt模块和组件可以利用grain接口，以在正确的系统上自动地获得正确的salt minion命令参数。

Grains数据是相对静态的，但如果系统信息发生变化（例如，如果网络设置发生变化），或者如果将新值分配给自定义grain，那么grains数据将会被刷新。

本文亦可参考github上这这份资料：GRAINS

注意:Grains被统一解析为小写字母。例如，FOO和foo指的是同一个grain。

LISTING GRAINS

可以使用’grains.ls’模块列出可用的grains：

salt '*' grains.ls

而grains 的数据则可以使用 ‘grains.items’ 模块查看:

salt '*' grains.items

USING GRAINS IN A STATE

你可以简单地在state定义文件中通过这种方式引用grains数据{{ grains['key'] }} 。

GRAINS IN THE MINION CONFIG

可以在minion配置文件中按需定义grains。只需添加选项grain并将配置项传递给它：

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

然后，就可以通过Salt检索特定于服务器的状态数据了，或者在State系统内部使用以进行目标匹配。你上述的示例，它提供了可以基于有关部署属性的特定数据辅助进行minions目标定位。

GRAINS IN /ETC/SALT/GRAINS

如果你不想将自定义的grains放在minion配置文件中，也可以将它们放在/etc/salt/grain中。它们的配置方式与上例相同，只不过没有一个top-level grains:的键：

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

注意： /etc/salt/grains are ignored if you specify the same grains in the minion config.

注意：Grains是静态的，因为它们不经常更换，它们在更新时需要主动进行刷新。这可以通过调用：salt minion saltutil.refresh_modules来完成此操作。

注意：可以为Proxy Minions配置自定义grains。由于多个Proxy Minion进程可以在同一台机器上运行，因此你需要使用/etc/salt/proxy.d/<minion ID>/grains下的Minion ID索引文件。例如，Proxy Minion router1的grains可以在/etc/salt/proxy.d/router1/grains下定义，而Proxy Minion switch7的grains可以放在/etc/salt/proxy.d/switch7/中。

MATCHING GRAINS IN THE TOP FILE

在Minions上正确配置了grains后，Pillar或Highstate中使用的topfile文件就可以非常高效。例如下面的配置：

'roles:webserver':
  - match: grain
  - state0

'roles:memcache':
  - match: grain
  - state1
  - state2

要使此示例起作用，你需要为要匹配的minions定义好grains角色。

WRITING GRAINS

通过执行位于Salt核心grains代码模块中的所有“public”函数（即那些不以下划线开头的函数），以及自定义grains模块中的函数，得到需要的grains数据。 grain模块中的函数必须要返回一个Python字典，其中字典的键是grain的名称，每个键的值是该grain的值。

自定义grains模块应放在名为_grains的子目录中，该子目录位于master配置文件指定的file_roots下。默认路径为/srv/salt/_grains。运行state.highstate时，或者通过执行saltutil.sync_grains或saltutil.sync_all函数时，会将自定义grains模块分发给minions。

Grains模块易于编写，并且（如上所述）只需要返回一个字典数据。例如：

def yourfunction():
     # initialize a grains dictionary
     grains = {}
     # Some code for logic that sets grains like
     grains['yourcustomgrain'] = True
     grains['anothergrain'] = 'somevalue'
     return grains

函数的名称无关紧要，根本不会影响grains数据; 只有返回的key/value才会成为grains数据中的一部分。

WHEN TO USE A CUSTOM GRAIN

在定义一个新的grain之前，请考虑数据的特点是什么，并记住grains应该（大部分）是静态类型的数据。

如果数据可能会发生变化，请考虑使用Pillar或execution模块。如果它是一组简单的键/值对，那么pillar是一个很好的匹配。如果编译信息过程中需要运行系统命令，那么将此信息放在执行模块中可能是更好的主意。

一个grains的最佳使用实践是在topfile文件或Salt CLI中作为定位minions的数据。 Grains的名称和数据结构应设计为支持多平台、操作系统或应用程序。另外，请记住，Salt中的Jinja模板支持引用pillar数据以及从执行模块调用函数，因此不需要在grain中放置信息以使其可用于Jinja模板。例如：

...
...
{{ salt['module.function_name']('argument_1', 'argument_2') }}
{{ pillar['my_pillar_key'] }}
...
...

警告：在执行了第一次的highstate之后，自定义grains才会在topfile文件中生效。而为了在使用minion执行第一欠highstate时，自定义grains就是有效的，建议使用此reator的示例以确保在minion进程启动时就执行了自定义grains数据的同步。

LOADING CUSTOM GRAINS

如果你使用子函数帮助生成grains数据，请确保在grains子函数名称前添加一个下划线。这可以防止Salt从最终grain数据结构中的grain函数中包含加载的grains。例如，考虑这个自定义grain文件：

#!/usr/bin/env python
def _my_custom_grain():
    my_grain = {'foo': 'bar', 'hello': 'world'}
    return my_grain


def main():
    # initialize a grains dictionary
    grains = {}
    grains['my_grains'] = _my_custom_grain()
    return grains

此示例的输出如下：

# salt-call --local grains.items
local:
    ----------
    <Snipped for brevity>
    my_grains:
        ----------
        foo:
            bar
        hello:
            world

但是，如果你没有在my_custom_grain函数前面添加下划线，那么函数将在items输出中由Salt呈现两次：一次用于my_custom_grain调用本身，另一次用于在main函数中调用它：

# salt-call --local grains.items
local:
----------
    <Snipped for brevity>
    foo:
        bar
    <Snipped for brevity>
    hello:
        world
    <Snipped for brevity>
    my_grains:
        ----------
        foo:
            bar
        hello:
            world

PRECEDENCE

核心grains可以被定制grains覆盖。由于有几种自定义grains的方法，因此在定义它们时应该记住生效的优先顺序。顺序如下：

Core grains.
Custom grains in /etc/salt/grains.
Custom grains in /etc/salt/minion.
Custom grain modules in _grains directory, synced to minions.

每个后续的都会覆盖以前的，因此由自定义grains模块定义的任何与核心grains同名的grain，在同步到minions时将覆盖该核心grain。同样，来自/etc/salt/minion的grains会覆盖核心grains和自定义grains模块，而_grains中的grains将覆盖任何相同名称的grains。

对于自定义grains，如果函数采用参数grains，则最早被渲染的grains将被传入。因为其余grains可以以任何顺序进行渲染，所以可以依赖的唯一grains是核心grains。这是在2019.2.0版本中添加的。

EXAMPLES OF GRAINS

Grains package中的core模块是由Salt minion加载主要grains数据的地方，提供了如何写一个grains的示例：

https://github.com/saltstack/salt/blob/develop/salt/grains/core.py

SYNCING GRAINS

同步grains数据可以通过多种方式完成，当调用state.highstate时它们会自动同步，或者（如上所述）可以通过调用saltutil.sync_grains或saltutil.sync_all函数手动同步和重新加载。

注意：当grain_cache设置为False时，构建grain字典并将其存储在minion的内存中。每次minion重新启动或运行saltutil.refresh_grains时，都会从头开始重建grain字典。

SaltStack Grains 使用指南