Salt Returners-作业结果数据返回器的使用与定制开发方法

RETURNERS

默认情况下，发送给Salt minions的命令的返回值将返回给Salt master，但是我们还可以很多其它的方式来使用这份结果数据。

通过使用Salt returner，可以将结果数据重定向到外部数据存储服务以做进一步的分析和归档。

Returners从Salt minions中提取它们的配置信息，且仅支持在程序起动时加载一次配置信息。

Returners接口允许将返回数据发送到可以接收数据的任何系统。 这意味着可以将返回数据发送到Redis服务器，MongoDB服务器，MySQL服务器或任何系统。

更多returners参见 Full list of builtin returners

USING RETURNERS

所有Salt命令都会将命令结果数据返回给master。 指定returners时将会把数据也发送到指定的returner接口一份。

在调用命令时指定要使用的returners：

salt '*' test.version --return redis_return

这个命令将会把结果数据给 redis_return returner 一份。

可以同时指定多个 returners:

salt '*' test.version --return mongo_return,redis_return,cassandra_return

在这种情况下，将调用所有三个returners，并将test.version命令的数据发送给它们。

WRITING A RETURNER

Returners也是一种Salt模块，支持将结果数据重定向到Salt Master以外的目标。

RETURNERS ARE EASY TO WRITE!

写一个salt returner很简单。

Returner是一个Python模块，至少包含一个return功能。 可以包含其他可选功能，以支持使用master_job_cache、在外部系统中存储作业结果以及Event Returners等功能。

returner

returner函数必须接受单个参数。 该参数包含来自被调用的minion函数的返回数据。 如果调用minion函数test.version，则参数的值将是字典类型。 从Salt master运行以下命令以获取一个字典类型参数的示例：

salt-call --local --metadata test.version --out=pprint

import redis
import salt.utils.json

def returner(ret):
    '''
    Return information to a redis server
    '''
    # Get a redis connection
    serv = redis.Redis(
        host='redis-serv.example.com',
        port=6379,
        db='0')
    serv.sadd("%(id)s:jobs" % ret, ret['jid'])
    serv.set("%(jid)s:%(id)s" % ret, salt.utils.json.dumps(ret['return']))
    serv.sadd('jobs', ret['jid'])
    serv.sadd(ret['jid'], ret['id'])

上面设置为一个Returner将数据发送到Redis服务器，并将数据序列化为JSON后写入redis。

USING CUSTOM RETURNER MODULES

将自定义returners放在master配置文件指定的file_roots中的_returners/目录中。

当调用以下任何一个函数时，都将触发分发自定义returners的操作：

• state.apply
• saltutil.sync_returners
• saltutil.sync_all

任何已经同步到minion上的名称与Salt的默认returners相同的自定义returners，都将取代具有相同名称的默认returners。

NAMING THE RETURNER

请注意，returner的默认名称是其文件名（即foo.py成为返回者foo），但是可以使用virtual函数覆盖其名称。 一个很好的例子可以在redis returner中找到，它名为redis_return.py，但只是简单地通过redis名称进行加载：

try:
    import redis
    HAS_REDIS = True
except ImportError:
    HAS_REDIS = False

__virtualname__ = 'redis'

def __virtual__():
    if not HAS_REDIS:
        return False
    return __virtualname__

MASTER JOB CACHE SUPPORT

master_job_cache、在外部系统中存储作业结果以及Event Returners。Salt的 master_job_cache 功能 允许将returners作为Salt默认的Job CACHE数据的可插拔组件使用。为了支持这一功能，一个returner模块必须要实现以下几个功能函数：

注意：以下示例使用的代码片段是从 cassandra_cql returner 中获取的。

prep_jid

除非提供了pass_jid，否则确保作业ID（jid）不会发生冲突。

nocache是一个可选的布尔值，表示是否应该缓存返回数据。 pass_jid是一个调用者提供的jid，应该无条件地返回。

def prep_jid(nocache, passed_jid=None):  # pylint: disable=unused-argument
    '''
    Do any work necessary to prepare a JID, including sending a custom id
    '''
    return passed_jid if passed_jid is not None else salt.utils.jid.gen_jid()

save_load

保存job信息。 jid由prep_jid生成，应被视为作业的唯一标识符。 例如，jid可以用作数据库中的primary/unique key。 load是由minion返回给Salt master的负载。 minions是这个job所针对的目标minions节点。 以下代码示例将把load数据转换为字符串形式后存储到salt.jids表中。

import salt.utils.json

def save_load(jid, load, minions=None):
    '''
    Save the load to the specified jid id
    '''
    query = '''INSERT INTO salt.jids (
                 jid, load
               ) VALUES (
                 '{0}', '{1}'
               );'''.format(jid, salt.utils.json.dumps(load))

    # cassandra_cql.cql_query may raise a CommandExecutionError
    try:
        __salt__['cassandra_cql.cql_query'](query)
    except CommandExecutionError:
        log.critical('Could not save load in jids table.')
        raise
    except Exception as e:
        log.critical(
            'Unexpected error while inserting into jids: {0}'.format(e)
        )
        raise

get_load

必须使用一个job id (jid)的参数，返回使用 save_load所存储的作业结果数据, 当未查询到时则返回一个空字典。

def get_load(jid):
    '''
    Return the load data that marks a specified jid
    '''
    query = '''SELECT load FROM salt.jids WHERE jid = '{0}';'''.format(jid)

    ret = {}

    # cassandra_cql.cql_query may raise a CommandExecutionError
    try:
        data = __salt__['cassandra_cql.cql_query'](query)
        if data:
            load = data[0].get('load')
            if load:
                ret = json.loads(load)
    except CommandExecutionError:
        log.critical('Could not get load from jids table.')
        raise
    except Exception as e:
        log.critical('''Unexpected error while getting load from
         jids: {0}'''.format(str(e)))
        raise

    return ret

EXTERNAL JOB CACHE SUPPORT

通过使用 the master_job_cache这个扩展功能模块，可以把Job结果数据存储到一个外部的存储服务系统中去。 一个Returner插件如果要支持 External Job Cache 功能， 除了需要实现上面 Master Job Cache support中的三个函数之外，还需要额外实现下面的四个函数：

get_jid

返回一个指定的job id作业的字典形式的结果数据。

例如：

{
    "local": {
        "master_minion": {
            "fun_args": [],
            "jid": "20150330121011408195",
            "return": "2018.3.4",
            "retcode": 0,
            "success": true,
            "cmd": "_return",
            "_stamp": "2015-03-30T12:10:12.708663",
            "fun": "test.version",
            "id": "master_minion"
        }
    }
}

get_fun

返回一个将给定Salt函数作为最后一个函数调用的minions字典。

Sample:

{
    "local": {
        "minion1": "test.version",
        "minion3": "test.version",
        "minion2": "test.version"
    }
}


**get_jids**

返回一个包含了所有job ids的列表。

Sample:
```json
{
    "local": [
        "20150330121011408195",
        "20150330195922139916"
    ]
}

get_minions

返回一个minions列表。

Sample:

{
     "local": [
         "minion3",
         "minion2",
         "minion1",
         "master_minion"
     ]
}

如果您需要进一步说明，请参考一个或多个已经实现了的returners（例如mysql或cassandra_cql）。

EVENT SUPPORT

必须将event_return函数添加到returner模块，以允许通过returner从master记录事件信息。 Master服务器将事件列表传递给这个函数。

以下示例取自MySQL returner。 在此示例中，每个事件都插入到事件salt_events表中，由于该表是基于event tag作为主键的，标签包含jid，所以可以保证事件记录的唯一性。

import salt.utils.json

def event_return(events):
 '''
 Return event to mysql server

 Requires that configuration be enabled via 'event_return'
 option in master config.
 '''
 with _get_serv(events, commit=True) as cur:
     for event in events:
         tag = event.get('tag', '')
         data = event.get('data', '')
         sql = '''INSERT INTO `salt_events` (`tag`, `data`, `master_id` )
                  VALUES (%s, %s, %s)'''
         cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__['id']))

TESTING THE RETURNER

Returner，prep_jid，save_load，get_load和event_return函数可以通过在master配置文件中配置master_job_cache和Event Returners，然后从master上对每个minion调用test.version来测试。

成功执行了Master Job Cache功能测试后，可以继续使用ret执行模块测试External Job Cache功能。

salt-call ret.get_jids cassandra_cql --output=json
salt-call ret.get_fun cassandra_cql test.version --output=json
salt-call ret.get_minions cassandra_cql --output=json
salt-call ret.get_jid cassandra_cql 20150330121011408195 --output=json

EVENT RETURNERS

为了最大限度地掌握Salt基础设施中的事件历史记录，Salt master获得到的所有事件都可以记录到一个或多个returners。

要启用事件记录功能，请将master配置中的event_return配置选项设置为应该指定为事件返回处理程序的returner(s)。

注意：并非所有returners都支持事件记录。 在使用之前验证该returner是否具有event_return()函数。

注意：在较大的规模的部署中，每秒钟就可以在繁忙的master上生成数百个事件。 确保密切关注给定returner的存储设备，因为Salt可以轻易地通过几千个并发的returns数据压倒一个性能不足的服务器。

RETURNERS插件列表

插件名称	功能描述
carbon_return	Take data from salt and “return” it into a carbon receiver
cassandra_cql_return	Return data to a cassandra server
cassandra_return	Return data to a Cassandra ColumnFamily
couchbase_return	Simple returner for Couchbase.
couchdb_return	Simple returner for CouchDB.
django_return	A returner that will inform a Django system that returns are available using Django’s signal system.
elasticsearch_return	Return data to an elasticsearch server for indexing.
etcd_return	Return data to an etcd server or cluster
highstate_return	Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file.
hipchat_return	Return salt data via hipchat.
influxdb_return	Return data to an influxdb server.
kafka_return	Return data to a Kafka topic
librato_return	Salt returner to return highstate stats to Librato
local	The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly
local_cache	Return data to local job cache
mattermost_returner	Return salt data via mattermost
memcache_return	Return data to a memcache server
mongo_future_return	Return data to a mongodb server
mongo_return	Return data to a mongodb server
multi_returner	Read/Write multiple returners
mysql	Return data to a mysql server
nagios_nrdp_return	Return salt data to Nagios
odbc	Return data to an ODBC compliant server.
pgjsonb	Return data to a PostgreSQL server with json data stored in Pg’s jsonb data type
postgres	Return data to a postgresql server
postgres_local_cache	Use a postgresql server for the master job cache.
pushover_returner	Return salt data via pushover (http://www.pushover.net)
rawfile_json	Take data from salt and “return” it into a raw file containing the json, with one line per event.
redis_return	Return data to a redis server
sentry_return	Salt returner that reports execution results back to sentry.
slack_returner	Return salt data via slack
sms_return	Return data by SMS.
smtp_return	Return salt data via email
splunk	Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar
sqlite3_return	Insert minion return data into a sqlite3 database
syslog_return	Return data to the host operating system’s syslog facility
telegram_return	Return salt data via Telegram.
xmpp_return	Return salt data via xmpp
zabbix_return	Return salt data to Zabbix