mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 17:09:03 +00:00
99 lines
3.3 KiB
ReStructuredText
99 lines
3.3 KiB
ReStructuredText
=================
|
|
Python client API
|
|
=================
|
|
|
|
Salt is written to be completely API centric, Salt minions and master can be
|
|
built directly into third party applications as a communication layer. The Salt
|
|
client API is very straightforward.
|
|
|
|
Using the LocalClient API
|
|
=========================
|
|
|
|
Sending information through the client is simple:
|
|
|
|
.. code-block:: python
|
|
|
|
# Import the salt client library
|
|
import salt.client
|
|
# create a local client object
|
|
client = salt.client.LocalClient()
|
|
# make calls with the cmd method
|
|
ret = client.cmd('*', 'cmd.run', ['ls -l'])
|
|
|
|
The cmd call is the only one needed for the local client, the arguments are as
|
|
follows:
|
|
|
|
.. function:: LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form='glob')
|
|
|
|
The LocalClient object only works running as root on the salt-master, it is the
|
|
same interface used by the salt command line tool. The arguments are as
|
|
follows.
|
|
|
|
.. cmdoption:: tgt
|
|
|
|
The tgt option is the target specification, by default a target is passed
|
|
in as a bash shell glob. The expr_form option allows the tgt to be passed
|
|
as either a pcre regular expression or as a python list.
|
|
|
|
.. cmdoption:: fun
|
|
|
|
The name of the function to call on the specified minions. The
|
|
documentation for these functions can be seen by running on the
|
|
salt-master: salt '*' sys.doc
|
|
|
|
.. cmdoption:: arg
|
|
|
|
The optional arg parameter is used to pass a list of options on to the
|
|
remote function
|
|
|
|
.. cmdoption:: timeout
|
|
|
|
The number of seconds to wait after the last minion returns but before all
|
|
minions return.
|
|
|
|
.. cmdoption:: expr_form
|
|
|
|
The type of tgt that is passed in, the allowed values are:
|
|
|
|
* 'glob' - Bash glob completion - Default
|
|
* 'pcre' - Perl style regular expression
|
|
* 'list' - Python list of hosts
|
|
|
|
Compound Command Execution With the Salt API
|
|
============================================
|
|
|
|
The Salt client API can also send what is called a compound command. Often
|
|
a collection of commands need to be executed on the targeted minions, rather
|
|
than send the commands one after another, they can be send in a single publish
|
|
containing a series of commands. This can dramatically lower overhead and
|
|
speed up the application communicating with Salt.
|
|
|
|
When commands are executed with compound execution the minion functions called
|
|
are executed in serial on the minion and the return value is sent back in a
|
|
different fashion. The return value is a dict, with the function names as keys
|
|
to the function returns as values.
|
|
|
|
Using the compound command execution system via the API requires that the fun
|
|
value and the arg value are lists matching by index. This ensures that the
|
|
order of the executions can be controlled. Any function that has no arguments
|
|
MUST have an empty array in the corresponding arg index.
|
|
|
|
.. code-block:: python
|
|
|
|
# Import the salt client library
|
|
import salt.client
|
|
# create a local client object
|
|
client = salt.client.LocalClient()
|
|
# make compound execution calls with the cmd method
|
|
ret = client.cmd('*', ['cmd.run', 'test.ping', 'test.echo'], [['ls -l'], [], ['foo']])
|
|
|
|
This will execute ``cmd.run ls -l`` then ``test.ping`` and finally
|
|
``test.echo foo``.
|
|
The return data from the minion will look like this:
|
|
|
|
.. code-block:: python
|
|
|
|
{'cmd.run': '<output from ls -l>',
|
|
'test.ping': True,
|
|
'test.echo': 'foo'}
|