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.
A number of client command methods are available depending on the exact behavior desired.
LocalClient¶
-
class
salt.client.
LocalClient
(c_path='/etc/salt/master', mopts=None)¶ LocalClient
is the same interface used by the salt command-line tool on the Salt Master.LocalClient
is used to send a command to Salt minions to execute execution modules and return the results to the Salt Master.Importing and using
LocalClient
must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as (unlessexternal_auth
is configured and authentication credentials are included in the execution.-
cmd
(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)¶ The cmd method will execute and wait for the timeout period for all minions to reply, then it will return all minion data at once.
Usage:
import salt.client client = salt.client.LocalClient() ret = client.cmd('*', 'cmd.run', ['whoami'])
With authentication:
# Master config ... external_auth: pam: fred: - test.* ...
ret = client.cmd('*', 'test.ping', [], username='fred', password='pw', eauth='pam')
Compound command usage:
ret = client.cmd('*', ['grains.items', 'cmd.run'], [[], ['whoami']])
Parameters: - tgt (string or list) -- Which minions to target for the execution. Default is shell
glob. Modified by the
expr_form
option. - fun (string or list of strings) --
The module and function to call on the specified minions of the form
module.function
. For exampletest.ping
orgrains.items
.- Compound commands
- Multiple functions may be called in a single publish by
passing a list of commands. This can dramatically lower
overhead and speed up the application communicating with Salt.
This requires that the
arg
param is a list of lists. Thefun
list and thearg
list must correlate by index meaning a function that does not take arguments must still have a corresponding empty list at the expected index.
- arg (list or list-of-lists) -- A list of arguments to pass to the remote function. If the
function takes no arguments
arg
may be omitted except when executing a compound command. - timeout -- Seconds to wait after the last minion returns but before all minions return.
- expr_form --
The type of
tgt
. Allowed values:glob
- Bash glob completion - Defaultpcre
- Perl style regular expressionlist
- Python list of hostsgrain
- Match based on a grain comparisongrain_pcre
- Grain comparison with a regexpillar
- Pillar data comparisonnodegroup
- Match on nodegrouprange
- Use a Range server for matchingcompound
- Pass a compound match string
- ret -- The returner to use. The value passed can be single returner, or a comma delimited list of returners to call in order on the minions
- kwargs --
Optional keyword arguments.
Authentication credentials may be passed when using
external_auth
.eauth
- the external_auth backendusername
andpassword
token
Returns: A dictionary with the result of the execution, keyed by minion ID. A compound command will return a sub-dictionary keyed by function name.
- tgt (string or list) -- Which minions to target for the execution. Default is shell
glob. Modified by the
-
cmd_async
(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, **kwargs)¶ Execute a command and get back the jid, don't wait for anything
The function signature is the same as
cmd()
with the following exceptions.Returns: A job ID
-
cmd_cli
(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', verbose=False, kwarg=None, **kwargs)¶ Used by the salt CLI. This method returns minion returns as the come back and attempts to block until all minions return.
The function signature is the same as
cmd()
with the following exceptions.Parameters: verbose -- Print extra information about the running command Returns: A generator
-
cmd_iter
(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)¶ Yields the individual minion returns as they come in
The function signature is the same as
cmd()
with the following exceptions.
-
cmd_iter_no_block
(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)¶ Blocks while waiting for individual minions to return.
The function signature is the same as
cmd()
with the following exceptions.Returns: None until the next minion returns. This allows for actions to be injected in between minion returns.
-
Salt Caller¶
-
class
salt.client.
Caller
(c_path='/etc/salt/minion')¶ Caller
is the same interface used by the salt-call command-line tool on the Salt Minion.Importing and using
LocalClient
must be done on the same machine as a Salt Minion and it must be done using the same user that the Salt Minion is running as.Usage:
import salt.client caller = salt.client.Caller() caller.function('test.ping') # Or call objects directly caller.sminion.functions['cmd.run']('ls -l')
-
function
(fun, *args, **kwargs)¶ Call a single salt function
-
RunnerClient¶
-
class
salt.runner.
RunnerClient
(opts)¶ RunnerClient
is the same interface used by the salt-run command-line tool on the Salt Master. It executes runner modules which run on the Salt Master.Importing and using
RunnerClient
must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as.-
cmd
(fun, arg, kwarg=None)¶ Execute a runner with the given arguments
-
low
(fun, low)¶ Pass in the runner function name and the low data structure
-
WheelClient¶
-
class
salt.wheel.
Wheel
(opts)¶ WheelClient
is an interface to Salt's wheel modules. Wheel modules interact with various parts of the Salt Master.Importing and using
WheelClient
must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as.-
call_func
(fun, **kwargs)¶ Execute a master control function
-
master_call
(**kwargs)¶ Send a function call to a wheel module through the master network interface Expects that one of the kwargs is key 'fun' whose value is the namestring of the function to call
-