salt api开发指南

目录：

1、salt.config.client_config

2、salt.config.minion_config

3、salt模块装载器接口

4、Salt的客户端接口——LocalClient

5、salt的客户端接口——Salt Caller

6、salt的客户端接口—— RunnerClient

7、salt的客户端接口—— WheelClient

8、salt的客户端接口—— CloudClient

9、salt的客户端接口—— SSHClient

1、salt.config.client_config(path, env_var='SALT_CLIENT_CONFIG', defaults=None)

功能：加载salt master配置文件

样例：

import salt.config

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

2、salt.config.minion_config(path, env_var='SALT_MINION_CONFIG', defaults=None, cache_minion_id=False)

功能：加载salt minion端配置文件

样例：

import salt.config

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

3、salt模块装载器接口

功能：将salt 模块加载到内存中。每个salt模块都有一个专用的加载函数。

（1）加载执行模块

功能：通过评估每个模块中的__virtual __（）函数来返回适用于当前系统的执行模块的字典。

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)

样例：

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']()

（2）加载单个模块

并绕过__virtual__函数

salt.loader.raw_mod(opts, name, functions, mod='modules')

样例：

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']()

（3）加载状态模块

返回状态模块。

salt.loader.states(opts, functions, utils, serializers, whitelist=None)

样例：

import salt.config

import salt.loader

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

statemods = salt.loader.states(__opts__, None, None)

（4）加载grains模块

返回动态grains的功能和静态grains的值。

salt.loader.grains(opts, force_refresh=False, proxy=None)

样例：

import salt.config

import salt.loader

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

__grains__ = salt.loader.grains(__opts__)

print __grains__['id']

（5）加载grains功能函数

salt.loader.grain_funcs

样例：

import salt.config

import salt.loader

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

grainfuncs = salt.loader.grain_funcs(__opts__)

4、Salt的客户端接口——LocalClient

class  salt.client.LocalClient(c_path='/etc/salt/master', mopts=None, skip_perm_errors=False, io_loop=None)

在salt master上执行客户端管理命令的接口。

LocalClient用于向Salt minions发送一个命令来执行执行模块并将结果返回给Salt Master。

必须在与Salt Master相同的计算机上完成导入和使用LocalClient，并且必须使用与运行Salt Master的相同用户。

样例：

import salt.client

local = salt.client.LocalClient()

local.cmd('*', 'test.fib', [10])

（1）cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', jid='', kwarg=None, **kwargs)

在目标客户机上以同步的方式执行一个命令。

cmd方法将执行并等待所有客户机的超时时间回复，然后它将一次返回所有的数据。

样例：

>>> import salt.client

>>> local = salt.client.LocalClient()

>>> local.cmd('*', 'cmd.run', ['whoami'])

{'jerry': 'root'}

可以在单个发布中执行复合命令。函数名和函数参数在单独的列表中提供，但索引值必须相关，如果不需要参数，则必须使用空列表。

样例：

>>> local.cmd('*', [

        'grains.items',

        'sys.doc',

        'cmd.run',

    ],

    [

        [],

        [],

        ['uptime'],

    ])

重要参数：

tgt（字符串或列表） - 要执行的目标是哪些子节点。 默认是shell通配符。 可以由expr_form选项修改。

fun（字符串或字符串列表） - 在客户机上执行的模块与函数，例如test.ping或grains.items 。

expr_form -- 设定tgt的参数类型，支持的参数类型有：

    glob - Bash glob completion - Default

    pcre - Perl style regular expression

    list - Python list of hosts

    grain - Match based on a grain comparison

    grain_pcre - Grain comparison with a regex

    pillar - Pillar data comparison

    pillar_pcre - Pillar data comparison with a regex

    nodegroup - Match on nodegroup

    range - Use a Range server for matching

    compound - Pas

（2）cmd_async(tgt, fun, arg=(), expr_form='glob', ret='', jid='', kwarg=None, **kwargs)

在指定的客户机上以异步的形式执行一个命令。

该函数与cmd()的特性基本相同，仅有以下不同。

返回:    A job ID or 0 on failure.

样例：

>>> local.cmd_async('*', 'test.sleep', [300])

'20131219215921857715'

（3）cmd_batch(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, batch='10%', **kwargs)

一次只在符合匹配规则的目标客户机的一个子集中，执行指定的命令。

该函数与cmd()的特性基本相同，仅有以下差别。

参数:    batch -- 要执行的系统的批量标识符

返回:    A generator of minion returns

>>> returns = local.cmd_batch('*', 'state.highstate', bat='10%')

>>> for ret in returns:

...     print(ret)

{'jerry': {...}}

{'dave': {...}}

{'stewart': {...}}

（4）cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

执行命令，然后对有结果返回的客户机收集其执行结果。

该函数与cmd()的特性基本相同，仅有以下差别。

返回:    A generator yielding the individual minion returns

注：A generator object in python is something like a lazy list. The elements are only evaluated as soon as you iterate over them.

样例：

>>> ret = local.cmd_iter('*', 'test.ping')

>>> for i in ret:

...     print(i)

{'jerry': {'ret': True}}

{'dave': {'ret': True}}

{'stewart': {'ret': True}}

（5）cmd_iter_no_block(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

执行命令，然后对有结果返回的客户机收集其执行结果，如果客户机没有返回结果则标记为None 。

该函数与cmd()的特性基本相同，仅有以下差别。

返回：返回一个生成器，对有结果返回的客户机收集其执行结果，如果客户机没有返回结果则标记为None 。这里允许在两个客户机返回结果之间注入特定的actions。

样例：

>>> ret = local.cmd_iter_no_block('*', 'test.ping')

>>> for i in ret:

...     print(i)

None

{'jerry': {'ret': True}}

{'dave': {'ret': True}}

None

{'stewart': {'ret': True}}

（6）cmd_subset(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, sub=3, cli=False, progress=False, **kwargs)

在目标系统的随机子集上执行命令

该函数与cmd()的特性基本相同，仅有以下差别。

参数:    sub -- The number of systems to execute on

样例：

>>> SLC.cmd_subset('*', 'test.ping', sub=1)

{'jerry': True}

（7）get_cli_returns(jid, minions, timeout=None, tgt='*', tgt_type='glob', verbose=False, show_jid=False, **kwargs)

启动观察者以查看指定JID的返回数据。

返回:    all of the information for the JID

（8）get_event_iter_returns(jid, minions, timeout=None)

从事件系统收集返回数据，达到超时时会强制中断。

（9）run_job(tgt, fun, arg=(), expr_form='glob', ret='', timeout=None, jid='', kwarg=None, **kwargs)

异步发送一个命令给连接着的客户机。准备作业目录并向任何目标客户机都发布一个命令。

返回：

一个可验证的pub_data字典或失败的空字典。 pub_data包含作业ID和预期返回数据的所有客户机列表。

样例：

>>> local.run_job('*', 'test.sleep', [300])

{'jid': '20131219215650131543', 'minions': ['jerry']}

5、salt的客户端接口——Salt Caller

class salt.client.Caller(c_path='/etc/salt/minion', mopts=None)

Caller与Salt Minion上使用的salt-call命令行工具使用的是相同的接口。

导入和使用Caller必须在与Salt Minion相同的机器上完成，并且必须使用与运行 Salt Minion一样的用户。

注：salt-call命令用于在本地运行模块功能，而不是从master执行它们。 Salt-call用于运行独立的Minion，最初创建用于故障排除。 如果未指定--local选项，则它会在执行期间联系Salt Master检索状态文件和其他资源。

使用方法：

import salt.client

caller = salt.client.Caller()

caller.cmd('test.ping')

请注意，运行的master或minion守护程序不需要使用此类。 运行salt-call --local只需将file_client设置为'local'即可。 通过将该设置包含在配置文件中，可以在Python级别上实现。

import salt.client

import salt.config

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

__opts__['file_client'] = 'local'

caller = salt.client.Caller(mopts=__opts__)

（1）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)

6、salt的客户端接口—— RunnerClient

class salt.runner.RunnerClient(opts)

Salt Master上的salt-run CLI工具使用的接口。

它执行在Salt Master上运行的runner模块。

导入和使用RunnerClient必须在与Salt Master相同的计算机上完成，并且必须使用Salt Master运行的相同用户来完成。

注：salt-run是执行Salt Runners的前端命令。 Salt runners是用于在master上执行功能函数的简单模块。

（1）async(fun, low, user='UNKNOWN')

以多进程并发的方式执行指定的函数，并且返回事件标记用于监视返回结果。

（2）cmd(fun, arg=None, pub_data=None, kwarg=None)

样例：

Execute a function

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

    },

}

（3）cmd_async(low)

异步执行runner功能; 需要使用eauth。

此功能需要配置external_auth，并且用户有权执行runner功能（@runner）。

runner.eauth_async({

    'fun': 'jobs.list_jobs',

    'username': 'saltdev',

    'password': 'saltdev',

    'eauth': 'pam',

})

（4）cmd_sync(low, timeout=None)

同步执行runner功能; 需要使用eauth。

此功能需要配置external_auth，并且用户有权执行runner功能（@runner）。

runner.eauth_sync({

    'fun': 'jobs.list_jobs',

    'username': 'saltdev',

    'password': 'saltdev',

    'eauth': 'pam',

})

7、salt的客户端接口—— WheelClient

saltstack的内置wheel模块功能如下：

configManage the master configuration fileerrorError generator to enable integration testing of salt wheel error handlingfile_rootsRead in files from the file_root and save files to the file rootkeyWheel system wrapper for key systemminionsWheel system wrapper for connected minionspillar_rootsThe pillar_roots wheel module is used to manage files under the pillar roots directories on the master server.

class salt.wheel.WheelClient(opts=None)

Salt wheel模块的接口

导入和使用WheelClient必须在与Salt Master相同的机器上完成，并且必须使用Salt Master运行的相同用户。 需要配置external_auth，并且用户被授权执行wheel功能（@wheel）。

Usage:

import salt.config

import salt.wheel

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

wheel = salt.wheel.WheelClient(opts)

（1）async(fun, low, user='UNKNOWN')

以多进程并发的方式执行指定的函数，并且返回事件标记用于监视返回结果。

（2）cmd(fun, arg=None, pub_data=None, kwarg=None)

Execute a function

    >>> wheel.cmd('key.finger', ['jerry'])

    {'minions': {'jerry': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

（3）cmd_async(low)

异步执行一个函数，需要配置eauth。

该函数需要配置external_auth，并且用户被授权执行(@wheel)。

>>> wheel.cmd_async({

    'fun': 'key.finger',

    'match': 'jerry',

    'eauth': 'auto',

    'username': 'saltdev',

    'password': 'saltdev',

})

{'jid': '20131219224744416681', 'tag': 'salt/wheel/20131219224744416681'}

（4）cmd_sync(low, timeout=None)

同步执行一个函数，需要配置eauth。

该函数需要配置external_auth，并且用户被授权执行(@wheel)。

>>> 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'}}

8、salt的客户端接口—— CloudClient

class salt.cloud.CloudClient(path=None, opts=None, config_dir=None, pillars=None)

一个负责包装云交互功能的客户端类。

（1）action(fun=None, cloudmap=None, names=None, provider=None, instance=None, kwargs=None)

通过云插件后端执行单个操作。

样例：

client.action(fun='show_instance', names=['myinstance'])

client.action(fun='show_image', provider='my-ec2-config',

    kwargs={'image': 'ami-10314d79'}

)

（2）create(provider, names, **kwargs)

创建命名的虚拟机，而不使用配置文件。

范例:

client.create(names=['myinstance'], provider='my-ec2-config',

    kwargs={'image': 'ami-1624987f', 'size': 't1.micro',

            'ssh_username': 'ec2-user', 'securitygroup': 'default',

            'delvol_on_destroy': True})

（3）destroy(names)

销毁命名的虚机。

（4）extra_action(names, provider, action, **kwargs)

使用块存储设备执行操作。

范例:

client.extra_action(names=['myblock'], action='volume_create',

    provider='my-nova', kwargs={'voltype': 'SSD', 'size': 1000}

)

client.extra_action(names=['salt-net'], action='network_create',

    provider='my-nova', kwargs={'cidr': '192.168.100.0/24'}

)

（5）其它函数

full_query(query_type='list_nodes_full')：Query all instance information

list_images(provider=None)：List all available images in configured cloud systems

list_locations(provider=None)：List all available locations in configured cloud systems

list_sizes(provider=None)：List all available sizes in configured cloud systems

low(fun, low)：Pass the cloud function and low data structure to run

map_run(path, **kwargs)：Pass in a location for a map to execute

min_query(query_type='list_nodes_min')：Query select instance information

profile(profile, names, vm_overrides=None, **kwargs)：Pass in a profile to create, names is a list of vm names to allocate

vm_overrides是一个特殊的dict，它将被每个节点的选项覆盖。

范例:

>>> client= salt.cloud.CloudClient(path='/etc/salt/cloud')>>> client.profile('do_512_git', names=['minion01',]){'minion01': {u'backups_active': 'False', u'created_at': '2014-09-04T18:10:15Z', u'droplet': {u'event_id': 31000502, u'id': 2530006, u'image_id': 5140006, u'name': u'minion01', u'size_id': 66}, u'id': '2530006', u'image_id': '5140006', u'ip_address': '107.XXX.XXX.XXX', u'locked': 'True', u'name': 'minion01', u'private_ip_address': None, u'region_id': '4', u'size_id': '66', u'status': 'new'}}

query(query_type='list_nodes')：Query basic instance information

select_query(query_type='list_nodes_select')：Query select instance information

9、salt的客户端接口—— SSHClient

class salt.client.ssh.client.SSHClient(c_path='/etc/salt/master', mopts=None)

通过salt-ssh后端创建一个用于执行例行工作任务的客户端对象。

（1）cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', kwarg=None, **kwargs)

通过salt-ssh子系统执行单个命令，并一次返回所有任务结果。

（2）cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

通过salt-ssh子系统执行单个命令并返回一个生成器。