14 KiB
Modular Systems
When first working with Salt, it is not always clear where all of the modular components are and what they do. Salt comes loaded with more modular systems than many users are aware of, making Salt very easy to extend in many places.
The most commonly used modular systems are execution modules and states. But the modular systems extend well beyond the more easily exposed components and are often added to Salt to make the complete system more flexible.
developing configuration
Loading Modules
Modules come primarily from several sources:
- The Salt package itself
- The Salt File Server
- The extmods directory
- Secondary packages installed
Using one source to override another is not supported.
The Salt Package
Salt itself ships with a large number of modules. These are part of the Salt package itself and don't require the user to do anything to use them. (Although a number of them have additional dependencies and/or configuration.)
The Salt File Server
The user may add modules by simply placing them in special
directories in their fileserver <file-server>.
The name of the directory inside of the file server is the directory name prepended by underscore, such as:
_grains_modules_states
Modules must be synced before they can be used. This can happen a few ways, discussed below.
Note
Using saltenvs besides base may not work in all
contexts.
Sync Via States
The minion configuration contains an option
autoload_dynamic_modules which defaults to
True. This option makes the state system refresh all
dynamic modules when states are run. To disable this behavior set autoload_dynamic_modules to False
in the minion config.
When dynamic modules are autoloaded via states, only the modules defined in the same saltenvs as the states currently being run.
Sync Via the saltutil Module
The saltutil module has a number of functions that can be used to
sync all or specific dynamic modules. The saltutil.sync_*
execution functions <salt.modules.saltutil>
and runner functions <salt.runners.saltutil> can
be used to sync modules to minions and the master, respectively.
The extmods Directory
Any files places in the directory set by
extension_modules settings (minion <extension_modules>, master <extension_modules>, default
/var/cache/salt/*/extmods) can also be loaded as modules.
Note that these directories are also used by the
saltutil.sync_* functions (mentioned above) and files may
be overwritten.
Secondary Packages
Third-party packages may also add modules to Salt if they are installed in the same system and Python environment as the Salt Minion or Master.
This is done via setuptools entry points:
setup(
# ...
entry_points={"salt.loader": ["module_dirs=spirofs.loader:module"]},
# ...
)Note that these are not synced from the Salt Master to the Minions. They must be installed independently on each Minion.
Module Types
The specific names used by each loading method above are as follows. See sections below for a short summary of each of these systems.
| Module Type | Salt Package Name | FS/Directory Name | Entry Point |
|---|---|---|---|
| Auth | salt.auth (index <external-logging-handlers>) |
auth1 |
auth_dirs |
| Beacon | salt.beacons (index <beacons>) |
beacons |
beacons_dirs |
| Cache | salt.cache (index <all-salt.cache>) |
cache |
cache_dirs |
| Cloud | salt.cloud.clouds (index <all-salt.clouds>) |
clouds |
cloud_dirs |
| Engine | salt.engines (index <engines>) |
engines |
engines_dirs |
| Execution | salt.modules (index <all-salt.modules>) |
modules |
module_dirs |
| Executor | salt.executors (index <all-salt.executors>) |
executors |
executor_dirs |
| File Server | salt.fileserver (index <file-server>) |
fileserver |
fileserver_dirs |
| Grain | salt.grains (index <all-salt.grains>) |
grains |
grains_dirs |
| Log Handler | salt.log_handlers (index <external-logging-handlers>) |
log_handlers |
log_handlers_dirs |
| Matcher | salt.matchers |
matchers |
matchers_dirs |
| Metaproxy | salt.metaproxy |
metaproxy2 |
metaproxy_dirs |
| Net API | salt.netapi (index <all-netapi-modules>) |
netapi3 |
netapi_dirs |
| Outputter | salt.output (index <all-salt.output>) |
output |
outputter_dirs |
| Pillar | salt.pillar (index <all-salt.pillars>) |
pillar |
pillar_dirs |
| Proxy | salt.proxy (index <all-salt.proxy>) |
proxy |
proxy_dirs |
| Queue | salt.queues (index <all-salt.queues>) |
queues |
queue_dirs |
| Renderer | salt.renderers (index <all-salt.renderers>) |
renderers |
render_dirs |
| Returner | salt.returners (index <all-salt.returners>) |
returners |
returner_dirs |
| Roster | salt.roster (index <all-salt.roster>) |
roster |
roster_dirs |
| Runner | salt.runners (index <all-salt.runners>) |
runners |
runner_dirs |
| SDB | salt.sdb (index <all-salt.sdb>) |
sdb |
sdb_dirs |
| Serializer | salt.serializers (index <all-salt.serializers>) |
serializers4 |
serializers_dirs |
| SPM pkgdb | salt.spm.pkgdb |
pkgdb5 |
pkgdb_dirs |
| SPM pkgfiles | salt.spm.pkgfiles |
pkgfiles6 |
pkgfiles_dirs |
| SSH Wrapper | salt.client.ssh.wrapper |
wrapper7 |
wrapper_dirs |
| State | salt.states (index <all-salt.states>) |
states |
states_dirs |
| Thorium | salt.thorium (index <all-salt.thorium>) |
thorium |
thorium_dirs |
| Tokens | salt.tokens |
tokens |
tokens_dirs |
| Top | salt.tops (index <all-salt.tops>) |
tops |
top_dirs |
| Util | salt.utils |
utils |
utils_dirs |
| Wheel | salt.wheels (index <all-salt.wheel>) |
wheel |
wheel_dirs |
Note
While it is possible to import modules directly with the import
statement, it is strongly recommended that the appropriate dunder dictionary <dunder-dictionaries> is used
to access them instead. This is because a number of factors affect
module names, module selection, and module overloading.
Auth
The auth module system allows for external authentication routines to
be easily added into Salt. The auth
function needs to be implemented to satisfy the requirements of an auth
module. Use the pam module as an example.
See External Authentication System <acl-eauth> for
more about authentication in Salt.
Beacon
Writing Beacons <writing-beacons>
Beacons are polled by the Salt event loop to monitor non-salt
processes. See Beacons <beacons> for more information about the
beacon system.
Cache
The minion cache is used by the master to store various information
about minions. See Minion Data Cache <cache> for more
information.
Cloud
Cloud modules are backend implementations used by Salt Cloud <salt-cloud>.
Engine
Engines are open-ended services managed by the Salt daemon (both
master and minion). They may interact with event loop, call other
modules, or a variety of non-salt tasks. See Salt Engines <engines>
for complete details.
Execution
/ref/modules/index
Execution modules make up the core of the functionality used by Salt to interact with client systems. The execution modules create the core system management library used by all Salt systems, including states, which interact with minion systems.
Execution modules are completely open ended in their execution. They can be used to do anything required on a minion, from installing packages to detecting information about the system. The only restraint in execution modules is that the defined functions always return a JSON serializable object.
Executor
/ref/executors/index
Executors control how execution modules get called. The default is to just call them, but this can be customized.
File Server
The file server module system is used to create file server backends
used by the Salt Master. These modules need to implement the functions
used in the fileserver subsystem. Use the gitfs module as
an example.
See File Server Backends <file-server-backends> for
more information.
Grains
writing-grains
Grain modules define extra routines to populate grains data. All defined public functions will be executed and MUST return a Python dict object. The dict keys will be added to the grains made available to the minion.
See Grains <grains> for more.
Log Handler
Log handlers allows the logs from salt (master or minion) to be sent to log aggregation systems.
Matcher
Matcher modules are used to define the minion targeting expressions <targeting>. For
now, it is only possible to override the existing matchers <matchers> (the required CLI
plumbing for custom matchers is not implemented yet).
Metaproxy
Metaproxy is an abstraction layer above the existing proxy minion. It enables adding different types of proxy minions that can still load existing proxymodules.
Net API
Net API modules are the actual server implementation used by Salt API.
Output
The output modules supply the outputter system with routines to
display data in the terminal. These modules are very simple and only
require the output function to execute.
The default system outputter is the nested module.
Pillar
external_pillars
Used to define optional external pillar systems. The pillar generated via the filesystem pillar is passed into external pillars. This is commonly used as a bridge to database data for pillar, but is also the backend to the libvirt state used to generate and sign libvirt certificates on the fly.
Proxy
Proxy Minions <proxy-minion> are a way to manage
devices that cannot run a full minion directly.
Renderers
Renderers are the system used to render sls files into salt highdata
for the state compiler. They can be as simple as the py
renderer and as complex as stateconf and
pydsl.
Returners
Returners are used to send data from minions to external sources,
commonly databases. A full returner will implement all routines to be
supported as an external job cache. Use the redis returner
as an example.
Roster
The Roster system <ssh-roster> is used by Salt SSH
to enumerate devices.
Runners
/ref/runners/index
Runners are purely master-side execution sequences.
SDB
Writing SDB Modules <sdb-writing-modules>
SDB is a way to store data that's not associated with a minion. See
Storing Data in Other Databases <sdb>.
Serializer
Primarily used with file.serialize <salt.states.file.serialize>.
State
/ref/states/index
State modules are used to define the state interfaces used by Salt States. These modules are restrictive in that they must follow a number of rules to function properly.
Note
State modules define the available routines in sls files. If calling an execution module directly is desired, take a look at the module state.
SPM pkgdb
SPM Development Guide: Package Database <spm-development-pkgdb>
pkgdb modules provides storage backends to the package database.
SPM pkgfiles
SPM Development Guide: Package Database <spm-development-pkgfiles>
pkgfiles modules handle the actual installation.
SSH Wrapper
ssh_wrapper
Replacement execution modules for Salt SSH <salt-ssh>.
Thorium
Modules for use in the Thorium <thorium-reactor> event reactor.
Tokens
Token stores for External Authentication <acl-eauth>. See the
salt.tokens
docstring for details.
Note
The runner to load tokens modules is saltutil.sync_eauth_tokens <salt.runners.saltutil.sync_eauth_tokens>.
Tops
Tops modules are used to convert external data sources into top file data for the state system.
Util
Just utility modules to use with other modules via
__utils__ (see Dunder Dictionaries <dunder-dictionaries>).
Wheel
The wheel system is used to manage master side management routines. These routines are primarily intended for the API to enable master configuration.
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎
These modules cannot be loaded from the Salt File Server.↩︎