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.

See also

There are many ways to access Salt programmatically.

Salt can be used from CLI scripts as well as via a REST interface.

See Salt's outputter system to retrieve structured data from Salt as JSON, or as shell-friendly text, or many other formats.

See the state.event runner to utilize Salt's event bus from shell scripts.

Salt's netapi module provides access to Salt externally via a REST interface. Review the netapi module documentation for more information.

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)

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.client
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, include_errors=False, initial_load=False, loaded_base_name=None, notify=False, static_modules=None, proxy=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_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__
__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')

Returns a single module loaded raw and bypassing the __virtual__ function

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)

Returns the state modules

Parameters:
  • opts (dict) -- The Salt options dictionary
  • functions (dict) -- A dictionary of minion modules, with module names as keys and funcs as values.
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)

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

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)

Returns the grain functions

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

Salt Caller

RunnerClient

WheelClient

CloudClient

SSHClient

Docs for previous releases are available on readthedocs.org.

Latest Salt release: 2016.3.2

Table Of Contents

Previous topic

APIs

Next topic

netapi modules