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.

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.

See also

More Orchestrate documentation

salt.states.saltmod.function(name, tgt, ssh=False, tgt_type='glob', expr_form=None, ret='', expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None, batch=None, subset=None)

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
expr_form

Deprecated since version 2017.7.0: Use tgt_type instead

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
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
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.

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', expr_form=None, ret='', highstate=None, sls=None, top=None, saltenv=None, test=False, pillar=None, pillarenv=None, expect_minions=True, fail_minions=None, allow_fail=0, concurrent=False, timeout=None, batch=None, queue=False, subset=None, orchestration_jid=None)

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.

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
expr_form

Deprecated since version 2017.7.0: Use tgt_type instead

ret
Optionally set a single or a list of returners to use
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 through to the state function
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
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.

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 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_id
: id
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.
timeout
: 300
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