Returners 返回器

Returner

minion端将数据返回给salt master,但是我们可以使用salt Returner将返回的数据重定向到
其他外部组件上，便于以后的分析和归档。

所有内置的Returner支持列表参看链接：http://docs.saltstack.cn/ref/returners/index.html，里面有详细的使用方法

---

USING RETURNERS

可以指定一个returners提供数据接收
salt '*' test.ping --return redis_return

也可以指定多个returners接收器
salt '*' test.ping --return mongo_return,redis_return,cassandra_return

---

WRITING A RETURNER

一个redis的例子：

import redis
import 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, json.dumps(ret['return']))
    serv.sadd('jobs', ret['jid'])
    serv.sadd(ret['jid'], ret['id'])

minion端返回的数据格式可使用如下命令获取：

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

如何写一个returners，介绍一个job cache需要具备的哪些功能要求

一个MASTER JOB CACHE SUPPORT需要提供的基本功能
prep_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的内容，并进行序列化存放在salt.jids表中
示例代码：

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, 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(str(e)))
        raise

get_load
接收一个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需要提供除master的那些功能以外还需要提供额外的一些功能

get_jid
根据任务ID返回一个字典类型的job内容

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

get_fun
返回一组minion和对应执行的函数

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

get_jids
返回job id的列表

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

get_minions
返回minion列表

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

---

EVENT SUPPORT

支持时间返回，但是需要在master中打开相关的配置
event_return
event_return_queue

支持自定义event_return,默认的返回示例如下：

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, json.dumps(data), __opts__['id']))

---

CUSTOM RETURNERS

在file_roots环境里面定义一个_returners目录，使用方法salt://_returners，解释查看：http://docs.saltstack.cn/ref/modules/all/salt.modules.saltutil.html#salt.modules.saltutil.sync_returners里面的释义

---

NAMING THE RETURNER

returners的命名问题，__virtual__ 函数可以用来重写该命名，例如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__

---

TESTING THE RETURNER

测试自己写的returner，可以在minion上通过salt-call测试自己编写的扩展存储组件的基本功能
示例方法如下：

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

可以记录salt master上的所有时间信息，注意主机的性能问题，因为大量的minion会给master带来较大的压力

 思考：

　　（1）为什么extend job cache需要比master端支持更多的功能

　　　　  可能是由于在master进行数据收集重定向的时候，master端已经将数据进行过整理，而在minion端收集返回数据则类似一个分布式的信息上传机制，功能需求相应的会复

　　　　  杂一些。