salt.states.saltmod#

Control the Salt command interface#

This state is intended for use from the Salt Master. It provides access to sending commands down to minions as well as access to executing master-side modules. These state functions wrap Salt's Python API.

New in version 2016.11.0.

Support for masterless minions was added to the salt.state function, so they can run orchestration sls files. This is particularly useful when the rendering of a state is dependent on the execution of another state. Orchestration will render and execute each orchestration block independently, while honoring requisites to ensure the states are applied in the correct order.

More Orchestrate documentation

salt.states.saltmod.function(name, tgt, ssh=False, tgt_type='glob', ret='', ret_config=None, ret_kwargs=None, expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None, batch=None, subset=None, failhard=None, **kwargs)#

Execute a single module function on a remote minion via salt or salt-ssh

name: The name of the function to run, aka cmd.run or pkg.install
tgt: The target specification, aka '*' for all minions
tgt_type: The target type, defaults to glob
arg: The list of arguments to pass into the function
kwarg: The dict (not a list) of keyword arguments to pass into the function
ret: Optionally set a single or a list of returners to use
ret_config: Use an alternative returner configuration
ret_kwargs: Override individual returner configuration items
expect_minions: An optional boolean for failing if some minions do not respond
fail_minions: An optional list of targeted minions where failure is an option
fail_function: An optional string that points to a salt module that returns True or False based on the returned data dict for individual minions
ssh: Set to True to use the ssh client instead of the standard salt client
roster: In the event of using salt-ssh, a roster system can be set

New in version 3005.
batch: Execute the command in batches. E.g.: 10%.
subset: Number of minions from the targeted set to randomly use

New in version 2017.7.0.
failhard: pass failhard down to the executing state

New in version 2019.2.2.

salt.states.saltmod.parallel_runners(name, runners, **kwargs)#

Executes multiple runner modules on the master in parallel.

New in version 2018.3.0.

A separate thread is spawned for each runner. This state is intended to be used with the orchestrate runner in place of the saltmod.runner state when different tasks should be run in parallel. In general, Salt states are not safe when used concurrently, so ensure that they are used in a safe way (e.g. by only targeting separate minions in parallel tasks).

name:: name identifying this state. The name is provided as part of the output, but not used for anything else.
runners:: list of runners that should be run in parallel. Each element of the list has to be a dictionary. This dictionary's name entry stores the name of the runner function that shall be invoked. The optional kwarg entry stores a dictionary of named arguments that are passed to the runner function.

parallel-state:
   salt.parallel_runners:
     - runners:
         my_runner_1:
           - name: state.orchestrate
           - kwarg:
               mods: orchestrate_state_1
         my_runner_2:
           - name: state.orchestrate
           - kwarg:
               mods: orchestrate_state_2

salt.states.saltmod.runner(name, **kwargs)#

Execute a runner module on the master

New in version 2014.7.0.

name: The name of the function to run
kwargs: Any keyword arguments to pass to the runner function

run-manage-up:
 salt.runner:
   - name: manage.up

salt.states.saltmod.state(name, tgt, ssh=False, tgt_type='glob', ret='', ret_config=None, ret_kwargs=None, highstate=None, sls=None, top=None, saltenv=None, test=None, pillar=None, pillarenv=None, expect_minions=True, exclude=None, fail_minions=None, allow_fail=0, concurrent=False, timeout=None, batch=None, queue=False, subset=None, orchestration_jid=None, failhard=None, **kwargs)#

Invoke a state run on a given target

name

An arbitrary name used to track the state execution

tgt

The target specification for the state run.

New in version 2016.11.0.

Masterless support: When running on a masterless minion, the tgt is ignored and will always be the local minion.

tgt_type

The target type to resolve, defaults to glob

ret

Optionally set a single or a list of returners to use

ret_config

Use an alternative returner configuration

ret_kwargs

Override individual returner configuration items

highstate

Defaults to None, if set to True the target systems will ignore any sls references specified in the sls option and call state.highstate on the targeted minions

top

Should be the name of a top file. If set state.top is called with this top file instead of state.sls.

sls

A group of sls files to execute. This can be defined as a single string containing a single sls file, or a list of sls files

test

Pass test=true or test=false through to the state function. This can be used to override a test mode set in the minion's config file. If left as the default of None and the 'test' mode is supplied on the command line, that value is passed instead.

pillar

Pass the pillar kwarg through to the state function

pillarenv

The pillar environment to grab pillars from

New in version 2017.7.0.

saltenv

The default salt environment to pull sls files from

ssh

Set to True to use the ssh client instead of the standard salt client

roster

In the event of using salt-ssh, a roster system can be set

expect_minions

An optional boolean for failing if some minions do not respond

fail_minions

An optional list of targeted minions where failure is an option

allow_fail

Pass in the number of minions to allow for failure before setting the result of the execution to False

exclude

Pass exclude kwarg to state

concurrent

Allow multiple state runs to occur at once.

WARNING: This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same Do not use this flag for performance optimization.

queue

Pass queue=true through to the state function

batch

Execute the command in batches. E.g.: 10%.

New in version 2016.3.0.

subset

Number of minions from the targeted set to randomly use

New in version 2017.7.0.

failhard

pass failhard down to the executing state

New in version 2019.2.2.

Examples:

Run a list of sls files via state.sls on target minions:

webservers:
  salt.state:
    - tgt: 'web*'
    - sls:
      - apache
      - django
      - core
    - saltenv: prod

Run sls file via state.sls on target minions with exclude:

docker:
  salt.state:
    - tgt: 'docker*'
    - sls: docker
    - exclude: docker.swarm
    - saltenv: prod

Run a full state.highstate on target mininons.

databases:
  salt.state:
    - tgt: role:database
    - tgt_type: grain
    - highstate: True

salt.states.saltmod.wait_for_event(name, id_list, event_id='id', timeout=300, node='master')#

Watch Salt's event bus and block until a condition is met

New in version 2014.7.0.

name: An event tag to watch for; supports Reactor-style globbing.
id_list: A list of event identifiers to watch for -- usually the minion ID. Each time an event tag is matched the event data is inspected for event_id, if found it is removed from id_list. When id_list is empty this function returns success.
event_idid: The name of a key in the event data. Default is id for the minion ID, another common value is name for use with orchestrating salt-cloud events.
timeout300: The maximum time in seconds to wait before failing.

The following example blocks until all the listed minions complete a restart and reconnect to the Salt master:

reboot_all_minions:
  salt.function:
    - name: system.reboot
    - tgt: '*'

wait_for_reboots:
  salt.wait_for_event:
    - name: salt/minion/*/start
    - id_list:
      - jerry
      - stuart
      - dave
      - phil
      - kevin
      - mike
    - require:
      - salt: reboot_all_minions

salt.states.saltmod.wheel(name, **kwargs)#

Execute a wheel module on the master

New in version 2014.7.0.

name: The name of the function to run
kwargs: Any keyword arguments to pass to the wheel function

accept_minion_key:
  salt.wheel:
    - name: key.accept
    - match: frank

Table of Contents

salt.states.saltmod#

Control the Salt command interface#