RETURNERS
By default, the command is sent to Salt minions return value will be returned to Salt master, but we also can many other ways to use the results of this data.
By using Salt returner, the resulting data can be redirected to an external data storage service for further analysis and archiving.
Returners their configuration information extracted from Salt minions, and the only support for loading configuration information when a program is started.
Returners interface allows to return data to the system may receive any data. This means that you can return data to the server Redis, MongoDB server, MySQL server, or any system.
More returners See Full list of builtin returners
USING RETURNERS
All Salt command will command the resulting data back to the master. When specifying returners data will be sent to the specified interface to a returner.
Specifies the returners to use when you invoke the command:
salt '*' test.version --return redis_return
This command will put the resulting data to a redis_return returner.
You can specify multiple returners at the same time:
salt '*' test.version --return mongo_return,redis_return,cassandra_return
In this case, all three calls returners, and transmits the command data to test.version thereof.
WRITING A RETURNER
Returners Salt is also a module that supports the redirection result data to the target other than Salt Master.
RETURNERS ARE EASY TO WRITE!
Write a salt returner is simple.
Returner Python is a module comprising at least one returnfeature. Other optional features may be included to support the use master_job_cache , in the external storage system job results and Event Returners functions.
returner
returnerFunction must accept a single parameter. The parameter contains the return data from minion function is invoked. If you call the function minion test.version, the value of the parameter will be the dictionary type. Examples from Salt master Run the following command to get a dictionary type parameter:
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 disposed above a Redis to send data to a server, and writes the data sequence into redis JSON.
USING CUSTOM RETURNER MODULES
Custom returners on the master configuration file specified file_rootsin the _returners/directory.
When you call any of the following function, will trigger distribute custom returners operations:
Any returners been synchronized to a default name Salt minion on the same custom returners, returners are substituted with the same name by default.
NAMING THE RETURNER
Note that the default name of the returner is the file name (ie foo.py become returnees foo), but you can use virtual functions to cover its name. A good example can be redis returner find, and it is named redis_return.py, but simply by redisloading name:
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 results of the job in the external system , and the Event Returners . Salt The master_job_cachefeature allows returners Salt as default data Job CACHE pluggable components used. To support this feature, a returner module must implement the following functions functions:
Note: The following examples use the code fragment is obtained from the cassandra_cql returner.
prep_jid
Unless the pass_jid, otherwise make sure that the job ID (jid) do not conflict.
nocacheIs an optional Boolean value that indicates whether the cache should return data. pass_jidIs a caller-provided jid, should return unconditionally.
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. jidThe prep_jidgeneration, should be seen as a unique identifier for the job. For example, jidit can be used as a database primary / unique key. loadIt is returned to the load by a minion of Salt master. minionsThis is the goal minions node for which job. The following code example will loadconvert the data to the stored string salt.jidstable.
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
Parameter must be a job id (jid), the process returns to use save_loadthe stored operation result data, when the query does not return to an empty dictionary.
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
By using the master_job_cachethis extension modules can Job result data to an external storage system to service. If you want to plug a Returner support External Job Cachefunctions, in addition to the need to achieve the above Master Job Cache supportin the three functions, but also the need for additional implement the following four functions:
get_jid
Returns a job id specified operation result data in the form dictionary.
E.g:
{
"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
Return to a given function as minions dictionary Salt last function call.
Sample:
{
"local": {
"minion1": "test.version",
"minion3": "test.version",
"minion2": "test.version"
}
}
**get_jids**
返回一个包含了所有job ids的列表。
Sample:
```json
{
"local": [
"20150330121011408195",
"20150330195922139916"
]
}
get_minions
Returns a list of minions.
Sample:
{
"local": [
"minion3",
"minion2",
"minion1",
"master_minion"
]
}
If you need further explanation, please refer to one or more has been achieved in the returners (eg mysql or cassandra_cql).
EVENT SUPPORT
You must event_returnadd the function to the returner module, allowing recorded event information from the master by returner. Master server event list passed to this function.
The following example is taken from MySQL returner. In this example, each event is inserted into the event salt_eventstable, since the table is based on event taga primary key, the label comprising JID, it is possible to ensure the uniqueness of the event record.
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_returnFunction can be configured in the master configuration file master_job_cache and Event Returners , and then from the master for each minion call test.versionto test.
After the successful implementation of the Master Job Cache function test, you may continue to be used retto perform module testing External Job Cachefunctions.
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
In order to maximize the grasp Event History Salt infrastructure, Salt master to get all the events can be recorded to one or more of returners.
To enable event logging, set the master configuration event_returnconfiguration option to return to the handler for the event should be designated as a returner (s).
Note: Not all returners support the event record. Before using the returner to verify whether the
event_return()function.
Note: In the large-scale deployment, every second you can generate hundreds of events on a busy master. Make sure to pay close attention given returner storage devices, because Salt can easily overwhelm a lack of performance by thousands of concurrent server returns data.
RETURNERS plug-in list
| Plugin name | Functional Description |
|---|---|
| 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 |