【SaltStack官方版】—— returners——返回器

ETURNERS 返回器

By default the return values of the commands sent to the Salt minions are returned to the Salt master, however anything at all can be done with the results data.

默认情况下，发送给Salt minions的命令的返回值将会返回给Salt master，但是可以使用结果数据完成任何操作。

By using a Salt returner, results data can be redirected to external data-stores for analysis and archival.

通过使用Salt返回者，可以将结果数据重定向到外部数据存储以进行分析和存档。

Returners pull their configuration values from the Salt minions. Returners are only configured once, which is generally at load time.

Returners 从Salt minions拉取得他们的配置值。Returners只配置一次，通常在加载时。

The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system.

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

RETURNER MODULES

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
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_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
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

using returners

All Salt commands will return the command data back to the master. Specifying returners will ensure that the data is _also_ sent to the specified returner interfaces.

所有的Salt命令都会将命令数据返回给master。指定返回者将确保数据被_also_发送到指定的返回者接口。

Specifying what returners to use is done when the command is invoked:

在调用命令时指定要使用的返回者：

salt '*' test.ping --return redis_return

This command will ensure that the redis_return returner is used.

该命令将确保使用redis_return返回者。

It is also possible to specify multiple returners:

指定多个返回者也是可能的：

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

In this scenario all three returners will be called and the data from the test.ping command will be sent out to the three named returners.

在这种情况下，所有三个返回者将被调用，并且来自test.ping命令的数据将被发送给三名返回者。

writing a returner

Returners are Salt modules that allow the redirection of results data to targets other than the Salt Master.

Returners是Salt模块，可以将结果数据重定向到Salt Master以外的目标。

returners are easy to write!

Writing a Salt returner is straightforward.

写一个Salt返回者很简单。

A returner is a Python module containing at minimum a returner function. Other optional functions can be included to add support for master_job_cache, Storing Job Results in an External System, and Event Returners.

返回者是一个至少包含返回函数的Python模块。可以包含其他可选功能，以添加对master_job_cache的支持，在外部系统中存储作业结果以及事件返回者。

returner

The returner function must accept a single argument. The argument contains return data from the called minion function. If the minion function test.ping is called, the value of the argument will be a dictionary. Run the following command from a Salt master to get a sample of the dictionary:

返回者函数必须接受一个参数。该参数包含来自被调用的minion函数的返回数据。如果调用minion函数test.ping，则参数的值将是一个字典。从Salt master中运行以下命令以获取字典的样本：

salt-call --local --metadata test.ping --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='')
     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'])

The above example of a returner set to send the data to a Redis server serializes the data as JSON and sets it in redis.

上述返回器的示例，设置成将数据发送到Redis服务器，将数据序列化为JSON并将其设置为redis。

using custom returner modules

Place custom returners in a _returners/ directory within the file_roots specified by the master config file.

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

Custom returners are distributed when any of the following are called:

自定义返回器在下列任何一种情况下被分配：

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

Any custom returners which have been synced to a minion that are named the same as one of Salt's default set of returners will take the place of the default returner with the same name.

任何已被同步到一个名为Salt的默认返回器集合的同名的自定义返回器将取代具有相同名称的默认返回器。(自定义返回器的将取代具有相同名称的默认返回器)

naming the returner

Note that a returner's default name is its filename (i.e. foo.py becomes returner foo), but that its name can be overridden by using a __virtual__ function. A good example of this can be found in the redis returner, which is named redis_return.py but is loaded as simply redis:

请注意，返回者的默认名称是其文件名（即foo.py成为返回者foo），但其名称可以使用__virtual__函数覆盖。一个很好的例子可以在Redis返回者中找到，它被命名为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, Storing Job Results in an External System, and Event Returners. Salt's master_job_cache allows returners to be used as a pluggable replacement for the Default Job Cache. In order to do so, a returner must implement the following functions:

master_job_cache，在外部系统中存储作业结果以及事件返回者。Salt的master_job_cache允许返回者用作默认作业缓存的可插拔替换。 为此，返回者必须执行以下功能：

注意：
The code samples contained in this section were taken from the cassandra_cql returner.
本节中包含的代码示例取自cassandra_cql返回者。

prep_jid

　　Ensures that job ids (jid) don't collide, unless passed_jid is provided.

　　确保job ids(jid)不会相互冲突，除非提供了passed_jid。

　　nochache is an optional boolean that indicates if return data should be cached. passed_jid is a caller provided jid which should be returned unconditionally.

　　nochache 是一个可选的布尔值，用于指示是否应该缓存返回数据。passed_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

　　Save job information. The jid is generated by prep_jid and should be considered a unique identifier for the job. The jid, for example, could be used as the primary/unique key in a database.

　　The load is what is returned to a Salt master by a minion. The following code example stores the load as a JSON string in the salt.jids table.

　　保存工作信息。jid由prep_jid生成，应被视为该job的唯一标识符。例如，jid可以用作数据库中的主键/唯一键。

　　load 是由一个minion返回Salt master的东西。以下代码示例将load作为JSON字符串存储在salt.jids表中。

 import salt.utils.json

 def save_load(jid, load):
     '''
     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)  # 一种NoSQL数据库，使用cql语句
     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

　　must accept a job id (jid) and return the job load stored by save_load, or an empty dictionary when not found.

　　必须接受job id（jid）并返回save_load存储的job 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

　　Salt's Storing Job Results in an External System extends the master_job_cache. External Job Cache support requires the following functions in addition to what is required for Master Job Cache support:

　　Salt的Storing Job Results in an External System扩展了master_job_cache。除了master job Cache支持所需的功能之外，外部作业缓存支持还需要以下功能：

get_jid

　　Return a dictionary containing the information (load) returned by each minion when the specified job id was executed.

　　返回一个字典，其中包含执行指定job id 时由每个小工具返回的信息（load）。

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

get_fun

　　Return a dictionary of minions that called a given Salt function as their last function call.

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

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

get_jids

　　Return a list of all job ids.

　　以列表形式返回所有job ids。

{
    "local": [
        "",
        ""
    ]
}

get_minions

　　Returns a list of minions

　　以列表返回minions。

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

Please refer to one or more of the existing returners (i.e. mysql, cassandra_cql) if you need further clarification.

如果您需要进一步的解释，请参考一个或多个现有返回器（即mysql，cassandra_cql）。

EVENT SUPPORT(支持事件)

An event_return function must be added to the returner module to allow events to be logged from a master via the returner. A list of events are passed to the function by the master.

一个event_return函数必须被添加到返回模块中，以允许事件通过返回者从master被记录。 master将事件列表传递给该功能。

The following example was taken from the MySQL returner. In this example, each event is inserted into the salt_events table keyed on the event tag. The tag contains the jid and therefore is guaranteed to be unique.

以下示例来自MySQL返回器。 在这个例子中，每个事件都被插入到事件标签上键入的salt_events表中。标签包含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

The returner, prep_jid, save_load, get_load, and event_return functions can be tested by configuring the master_job_cache and Event Returners in the master config file and submitting a job to test.ping each minion from the master.

返回器，prep_jid，save_load，get_load和event_return函数可以通过在主配置文件中配置master_job_cache和Event Returners并提交一个作业来测试master.jsp中的每个minion来测试。

Once you have successfully exercised the Master Job Cache functions, test the External Job Cache functions using the ret execution module.

成功执行Master job Cache功能后，使用ret执行模块测试External Job Cache功能。

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

event returners

For maximum visibility into the history of events across a Salt infrastructure, all events seen by a salt master may be logged to one or more returners.

为了最大限度地查看Salt基础设施中事件的历史记录，可以将Salt master看到的所有事件记录到一个或多个返回器。

To enable event logging, set the event_return configuration option in the master config to the returner(s) which should be designated as the handler for event returns.

要启用事件日志记录，请将主配置中的event_return配置选项设置为应指定为事件返回处理程序的返回者。

注意：

Not all returners support event returns. Verify a returner has an event_return() function before using.
并非所有的返回者都支持事件回报。 使用前验证返回者是否有event_return（）函数。

On larger installations, many hundreds of events may be generated on a busy master every second. Be certain to closely monitor the storage of a given returner as Salt can easily overwhelm an underpowered server with thousands of returns.
在较大的设施中，可以在繁忙的master上每秒产生数百个事件。一定要密切监视给定的回送器的存储，因为salt可以很容易地压倒一个动力不足的服务器，并有数千的回报。

full list of returners

returner modules

• salt.returners.carbon_return
• salt.returners.cassandra_cql_return
• salt.returners.cassandra_return
• salt.returners.couchbase_return
  • JID
  • JID/MINION_ID
• salt.returners.couchdb_return
  • On concurrent database access
• salt.returners.django_return
• salt.returners.elasticsearch_return
• salt.returners.etcd_return
• salt.returners.highstate_return module
• salt.returners.hipchat_return
• salt.returners.influxdb_return
• salt.returners.kafka_return
• salt.returners.librato_return
• salt.returners.local
• salt.returners.local_cache
• salt.returners.mattermost_returner module
• salt.returners.memcache_return
• salt.returners.mongo_future_return
• salt.returners.mongo_return
• salt.returners.multi_returner
• salt.returners.mysql
• salt.returners.nagios_return
• salt.returners.odbc
• salt.returners.pgjsonb
• salt.returners.postgres
• salt.returners.postgres_local_cache
• salt.returners.pushover_returner
• salt.returners.rawfile_json
• salt.returners.redis_return
• salt.returners.sentry_return
• salt.returners.slack_returner
• salt.returners.sms_return
• salt.returners.smtp_return
• salt.returners.splunk module
• salt.returners.sqlite3
• salt.returners.syslog_return
• salt.returners.telegram_return
• salt.returners.xmpp_return
• salt.returners.zabbix_return module