Python client API#

Salt provides several entry points for interfacing with Python applications. These entry points are often referred to as *Client() APIs. Each client accesses different parts of Salt, either from the master or from a minion. Each client is detailed below.

Note

For Tiamat-bundled Salt distribution, you need to use the bundled Python runtime as the system Python won't be able to access Salt internals.

To execute scripts via bundled Python runtime, either run the script with /path/to/salt python script.py or use #!/path/to/salt python shebang

Salt's `opts` dictionary#

Some clients require access to Salt's opts dictionary. (The dictionary representation of the master or minion config files.)

A common pattern for fetching the opts dictionary is to defer to environment variables if they exist or otherwise fetch the config from the default location.

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

Load Master configuration data

Usage:

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

Returns a dictionary of the Salt Master configuration file with necessary options needed to communicate with a locally-running Salt Master daemon. This function searches for client specific configurations and adds them to the data from the master configuration.

This is useful for master-side operations like LocalClient.

salt.config.minion_config(path, env_var='SALT_MINION_CONFIG', defaults=None, cache_minion_id=False, ignore_config_errors=True, minion_id=None, role='minion')#

Reads in the minion configuration file and sets up special options

This is useful for Minion-side operations, such as the Caller class, and manually running the loader interface.

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

Salt's Loader Interface#

Modules in the Salt ecosystem are loaded into memory using a custom loader system. This allows modules to have conditional requirements (OS, OS version, installed libraries, etc) and allows Salt to inject special variables (__salt__, __opts__, etc).

Most modules can be manually loaded. This is often useful in third-party Python apps or when writing tests. However some modules require and expect a full, running Salt system underneath. Notably modules that facilitate master-to-minion communication such as the mine, publish, and peer execution modules. The error KeyError: 'master_uri' is a likely indicator for this situation. In those instances use the Caller class to execute those modules instead.

Each module type has a corresponding loader function.

salt.loader.minion_mods(opts, context=None, utils=None, whitelist=None, initial_load=False, loaded_base_name=None, notify=False, static_modules=None, proxy=None, pillar=None, file_client=None)#

Load execution modules

Returns a dictionary of execution modules appropriate for the current system by evaluating the __virtual__() function in each module.

Parameters:

opts (dict) -- The Salt options dictionary
context (dict) -- A Salt context that should be made present inside generated modules in __context__
utils (dict) -- Utility functions which should be made available to Salt modules in __utils__. See utils_dirs in salt.config for additional information about configuration.
whitelist (list) -- A list of modules which should be whitelisted.
initial_load (bool) -- Deprecated flag! Unused.
loaded_base_name (str) -- The imported modules namespace when imported by the salt loader.
notify (bool) -- Flag indicating that an event should be fired upon completion of module loading.

Example:

import salt.config
import salt.loader

__opts__ = salt.config.minion_config('/etc/salt/minion')
__grains__ = salt.loader.grains(__opts__)
__opts__['grains'] = __grains__
__utils__ = salt.loader.utils(__opts__)
__salt__ = salt.loader.minion_mods(__opts__, utils=__utils__)
__salt__['test.ping']()

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

Returns a single module loaded raw and bypassing the __virtual__ function

Parameters:

opts (dict) -- The Salt options dictionary
name (str) -- The name of the module to load
functions (LazyLoader) -- A LazyLoader instance returned from minion_mods.
mod (str) -- The extension type.
loaded_base_name (str) -- The imported modules namespace when imported by the salt loader.

Example:

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, proxy=None, context=None, loaded_base_name=None, file_client=None, minion_mods=None)#

Returns the state modules

Parameters:

opts (dict) -- The Salt options dictionary
functions (LazyLoader) -- A LazyLoader instance returned from minion_mods (or, in a resource context, from resource_modules). This becomes __salt__ for state modules.
runners (LazyLoader) -- A LazyLoader instance returned from runner.
utils (LazyLoader) -- A LazyLoader instance returned from utils.
serializers (LazyLoader) -- An optional LazyLoader instance returned from serializers.
proxy (LazyLoader) -- An optional LazyLoader instance returned from proxy.
whitelist (list) -- A list of modules which should be whitelisted.
context (dict) -- A Salt context that should be made present inside generated modules in __context__
loaded_base_name (str) -- The imported modules namespace when imported by the salt loader.
minion_mods (LazyLoader) -- Optional escape-hatch loader for the managing minion's modules. Packed as __minion__ so state modules running in a resource context can call back into the managing minion explicitly. Typically the result of salt.loader.minion_mods(opts).

import salt.config
import salt.loader

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

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

Return the functions for the dynamic grains and the values for the static grains.

Parameters:

opts (dict) -- The Salt options dictionary
force_refresh (bool) -- Force the refresh of grains
context (dict) -- A Salt context that should be made present inside generated modules in __context__
proxy (LazyLoader) -- An optional LazyLoader instance returned from proxy.
loaded_base_name (str) -- The imported modules namespace when imported by the salt loader.

Since grains are computed early in the startup process, grains functions do not have __salt__ or __proxy__ available. At proxy-minion startup, this function is called with the proxymodule LazyLoader object so grains functions can communicate with their controlled device.

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, proxy=None, context=None, loaded_base_name=None)#

Returns the grain functions

Parameters:

opts (dict) -- The Salt options dictionary
context (dict) -- A Salt context that should be made present inside generated modules in __context__
proxy (LazyLoader) -- An optional LazyLoader instance returned from proxy.

loaded_base_name (str) --

The imported modules namespace when imported: by the salt loader.

import salt.config
import salt.loader

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

Salt's Client Interfaces#

LocalClient#

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

The interface used by the salt CLI 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. (Unless external_auth is configured and authentication credentials are included in the execution).

Note

The LocalClient uses a Tornado IOLoop, this can create issues when using the LocalClient inside an existing IOLoop. If creating the LocalClient in partnership with another IOLoop either create the IOLoop before creating the LocalClient, or when creating the IOLoop use ioloop.current() which will return the ioloop created by LocalClient.

import salt.client

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

cmd(tgt, fun, arg=(), timeout=None, tgt_type='glob', ret='', jid='', full_return=False, kwarg=None, **kwargs)#

Synchronously execute a command on targeted minions

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.

>>> import salt.client
>>> local = salt.client.LocalClient()
>>> local.cmd('*', 'cmd.run', ['whoami'])
{'jerry': 'root'}

With extra keyword arguments for the command function to be run:

local.cmd('*', 'test.arg', ['arg1', 'arg2'], kwarg={'foo': 'bar'})

Compound commands can be used for multiple executions in a single publish. Function names and function arguments are provided in separate lists but the index values must correlate and an empty list must be used if no arguments are required.

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

Parameters:

tgt (string or list) -- Which minions to target for the execution. Default is shell glob. Modified by the tgt_type option.
fun (string or list of strings) --
The module and function to call on the specified minions of the form module.function. For example test.ping or grains.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. The fun list and the arg 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.
tgt_type --
The type of tgt. Allowed values:
- 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 - Pass a compound match string
- ipcidr - Match based on Subnet (CIDR notation) or IPv4 address.
Changed in version 2017.7.0: Renamed from expr_form to tgt_type
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
kwarg -- A dictionary with keyword arguments for the function.
full_return -- Output the job return only (default) or the full return including exit code and other job metadata.
kwargs --
Optional keyword arguments. Authentication credentials may be passed when using external_auth.

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

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.

cmd_async(tgt, fun, arg=(), tgt_type='glob', ret='', jid='', kwarg=None, **kwargs)#

Asynchronously send a command to connected minions