PYTHON CLIENT API

salt提供了与Python应用程序接口的几个入口点，这些入口点通常被称为* client() API。每个客户端访问的salt的不同部分，无论是从master或minion，每个客户端详细如下：

1、以编程的方式访问salt
2、salt可以用于CLI脚本，也可以通过REST接口使用。
3、盐的 outputter system从salt为JSON检索结构化数据，或为shell友好的文本，或许多其他格式。
4、看state.event，salt的事件系统
5、salt netapi模块提供了访问salt扩展的外部REST接口

---

SALT'S OPTS DICTIONARY

一些客户端需要访问salt opts字典，这个字典包含了master或minion端的配置

salt.config.client_config(path, env_var='SALT_CLIENT_CONFIG', defaults=None)
加载master端的配置
示例

import salt.config
master_opts = salt.config.client_config('/etc/salt/master'

salt.config.minion_config(path, env_var='SALT_MINION_CONFIG', defaults=None, cache_minion_id=False)
加载minion端的配置，在minion端操作
示例：

import salt.client
minion_opts = salt.config.minion_config('/etc/salt/minion')

---

SALT'S LOADER INTERFACE

salt loader 接口
salt生态系统中的模块使用自定义加载系统加载到内存中。这允许模块有条件的（OS、OS版本、已安装的库等）允许salt注入特殊变量，每一个模块类型都应该有相应的加载函数

salt.loader.minion_mods(opts, context=None, utils=None, whitelist=None, include_errors=False, initial_load=False, loaded_base_name=None, notify=False, static_modules=None, proxy=None)
加载执行模块，通过评估每个模块中的__virtual __（）函数来返回适用于当前系统的执行模块的字典。
参数：

　　opts (dict) --salt配置选项的一个字典
　　context (dict) --应该在__context__中生成的模块中存在的salt上下文
　　utils (dict) -- Utility functions which should be made available to Salt modules in __utils__. See utils_dir in salt.config for additional information about configuration.
　　whitelist (list) -- A list of modules which should be whitelisted.
　　include_errors (bool) -- Deprecated flag! Unused.
　　initial_load (bool) -- Deprecated flag! Unused.
　　loaded_base_name (str) -- A string marker for the loaded base name.
　　notify (bool) -- Flag indicating that an event should be fired upon completion of module loading.

示例：

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
__grains__ = salt.loader.grains(__opts__)
__opts__['grains'] = __grains__
__salt__ = salt.loader.minion_mods(__opts__)    #获取执行模块函数的字典
__salt__['test.ping']()

salt.loader.raw_mod(opts, name, functions, mod='modules')
返回单一的模块，绕过__virtual__函数
示例：

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
testmod = salt.loader.raw_mod(__opts__, 'test', None)
testmod['test.ping']()

salt.loader.states(opts, functions, utils, serializers, whitelist=None)
返回states模块
示例：

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
statemods = salt.loader.states(__opts__, None, None, None)

salt.loader.grains(opts, force_refresh=False, proxy=None)
返回动态或静态的grains的值
示例：

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
__grains__ = salt.loader.grains(__opts__)
print __grains__['id']

salt.loader.grain_funcs(opts)
返回grains函数
示例：

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
grainfuncs = salt.loader.grain_funcs(__opts__)

---

SALT'S CLIENT INTERFACES

class salt.client.LocalClient(c_path='/etc/salt/master', mopts=None, skip_perm_errors=False, io_loop=None)
这个接口作为master端salt命令行接口的一个工具
LocalClient被用于发送一个命令到salt minion执行，并返回一个结果到salt master。
进口和使用localclient必须在同一台机器做为salt master，它必须使用与salt master运行的相同用户完成，除非external_auth有相关的配置。
示例：

import salt.client

local = salt.client.LocalClient()
local.cmd('*', 'test.fib', [10])

LocalClient的相关函数的使用方法;

cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', jid='', kwarg=None, **kwargs)
cmd设置的timeout值为等待最后一个minion返回结果后等待的时间

local.cmd('*', 'cmd.run', ['whoami'])
{'jerry': 'root'}

带参数的用法：
local.cmd('*', 'test.arg', ['arg1', 'arg2'], kwarg={'foo': 'bar'})
复合命令可以用于单个发布中的多次执行。函数名和函数参数在单独的列表中提供，但是索引值必须关联，如果不需要参数，则必须使用空列表。
示例：

 local.cmd('*', [
        'grains.items',
        'sys.doc',
        'cmd.run',
    ],
    [
        [],
        [],
        ['uptime'],
    ])

用法介绍：

　　tgt (string or list)： 选择被执行minion的标记，如果是组的话使用expr_form选项
　　fun (string or list of strings) ：指定执行的功能模块，可以使用复合命令
　　arg (list or list-of-lists)： 执行模块使用的参数，复合命令需要执行一个参数列表
　　timeout ： 指定超时时间，在所有minion返回之前等待的超时时间，并不是指命令执行的超时时间
　　expr_form： 指定tgt的类型，可以为以下值：
　　glob - Bash glob completion - Default
　　pcre - Perl 样式的正则表达式
　　list - 指定为主机列表
　　grain - 匹配minion端的grains变量
　　grain_pcre - 基于正则的匹配minion端的grains变量
　　pillar - Pillar data comparison
　　pillar_pcre - Pillar data comparison with a regex
　　nodegroup - 使用nodegroup信息
　　　　range - 指定一个服务器范围
　　compound - Pass a compound match string
　　ret： 不理解，有点像设置返回值的意思
　　kwarg ： 设置函数执行的参数

using external_auth：
For example: local.cmd('*', 'test.ping', username='saltdev', password='saltdev', eauth='pam').
Or: local.cmd('*', 'test.ping', token='5871821ea51754fdcea8153c1c745433')

各函数的使用方法：

cmd_async(tgt, fun, arg=(), expr_form='glob', ret='', jid='', kwarg=None, **kwargs)
异步的执行命令，返回值为作业ID，执行失败返回0

cmd_batch(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, batch='10%', **kwargs)
返回一个执行结果的迭代器

returns = local.cmd_batch('*', 'state.highstate', bat='10%')
{'XX.1.39': 'xd-asp-nginx-1064139'}

cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)
返回一个迭代器，迭代器里面包含结果的状态
{'XX.1.43': {'retcode': 0, 'ret': 'xd-asp-nginx-1064143'}}

cmd_iter_no_block(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)
返回一个生成器，没有返回的minion结果会被置None

cmd_subset(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, sub=3, cli=False, progress=False,
在执行目标里面随机挑选一个目标执行

get_cli_returns(jid, minions, timeout=None, tgt='*', tgt_type='glob', verbose=False, show_jid=False, **kwargs)
暂时不太明白，应该是返回一个任务ID执行的结果，但是格式好奇怪，里面有好多

local.cmd_async('XX.1.35', 'cmd.run', ['ls /'])
a = local.get_cli_returns('20170817145623282510', 'XX.1.35')

get_event_iter_returns(jid, minions, timeout=None)
支持任务中断，返回的信息还比较好处理

run_job(tgt, fun, arg=(), expr_form='glob', ret='', timeout=None, jid='', kwarg=None, **kwargs)
异步的发送命令到minion端执行，返回jid和相应的minion，这样利于异步发送命令之后再进行结果收集

a = local.get_event_iter_returns('20170817150543850815', 'BJ-sn-XX')
#但是返回了一些并不匹配minion的响应信息

---

SALT CALLER

class salt.client.Caller(c_path='/etc/salt/minion', mopts=None)
Caller在salt-minion端和salt-call命令行一样的接口，增加了和其他salt clients一样的cmd方法，导入和使用必须是在同一台salt minion上执行。
示例：

import salt.client
caller = salt.client.Caller()
caller.cmd('test.ping')
运行salt-call --local等同于在minion端的配置文件中设置file_client的值，默认为remote。

cmd(fun, *args, **kwargs)
调用一个执行模块需要提供一些参数
示例：

caller.cmd('test.arg', 'Foo', 'Bar', baz='Baz')

caller.cmd('event.send', 'myco/myevent/something',
    data={'foo': 'Foo'}, with_env=['GIT_COMMIT'], with_grains=True)

---

RUNNERCLIENT

class salt.runner.RunnerClient(opts)
被用于在salt master端使用salt-run的命令行接口。
它执行运行在salt master主机上的执行模块，RunnerClient导入和使用需要在salt master机器上。

async(fun, low, user='UNKNOWN')
执行多进程中的函数并返回事件标记以用于监视返回

cmd(fun, arg=None, pub_data=None, kwarg=None)
执行一个函数
示例：

>>> opts = salt.config.master_config('/etc/salt/master')
>>> runner = salt.runner.RunnerClient(opts)
>>> runner.cmd('jobs.list_jobs', [])
{
    '20131219215650131543': {
        'Arguments': [300],
        'Function': 'test.sleep',
        'StartTime': '2013, Dec 19 21:56:50.131543',
        'Target': '*',
        'Target-type': 'glob',
        'User': 'saltdev'
    },
    '20131219215921857715': {
        'Arguments': [300],
        'Function': 'test.sleep',
        'StartTime': '2013, Dec 19 21:59:21.857715',
        'Target': '*',
        'Target-type': 'glob',
        'User': 'saltdev'
    },
}

cmd_async(low)
以异步的方式执行函数
示例：

runner.eauth_async({
    'fun': 'jobs.list_jobs',
    'username': 'saltdev',
    'password': 'saltdev',
    'eauth': 'pam',
})

cmd_sync(low, timeout=None)
以同步的方式执行函数
示例：

runner.eauth_sync({
    'fun': 'jobs.list_jobs',
    'username': 'saltdev',
    'password': 'saltdev',
    'eauth': 'pam',
})

---

WHEELCLIENT

class salt.wheel.WheelClient(opts=None)
Salt's wheel 模块的接口
使用示例：

import salt.config
import salt.wheel
opts = salt.config.master_config('/etc/salt/master')
wheel = salt.wheel.WheelClient(opts)

async(fun, low, user='UNKNOWN')

cmd(fun, arg=None, pub_data=None, kwarg=None)
示例：

>>> wheel.cmd('key.finger', ['jerry'])
{'minions': {'jerry': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

cmd_async(low)
异步执行函数
示例：

>>> wheel.cmd_async({
    'fun': 'key.finger',
    'match': 'jerry',
    'eauth': 'auto',
    'username': 'saltdev',
    'password': 'saltdev',
})
{'jid': '20131219224744416681', 'tag': 'salt/wheel/20131219224744416681'}

cmd_sync(low, timeout=None)
同步执行函数命令

>>> wheel.cmd_sync({
'fun': 'key.finger',
'match': 'jerry',
'eauth': 'auto',
'username': 'saltdev',
'password': 'saltdev',
})
{'minions': {'jerry': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

---

SSHCLIENT

class salt.client.ssh.client.SSHClient(c_path='/etc/salt/master', mopts=None)
创建一个客户端对象，用于通过salt-ssh后端执行

cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', kwarg=None, **kwargs)
通过盐SSH子系统执行单个命令，并立即返回所有结果

cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)
通过盐SSH子系统执行单个命令，并以生成器的方式返回结果