salt.modules.state¶

State Caching¶

When a highstate is called, the minion automatically caches a copy of the last high data. If you then run a highstate with cache=True it will use that cached highdata and won't hit the fileserver except for salt:// links in the states themselves.

salt.modules.state.apply(mods=None, **kwargs)¶

New in version 2015.5.0.

This function will call state.highstate or state.sls based on the arguments passed to this function. It exists as a more intuitive way of applying states.

APPLYING ALL STATES CONFIGURED IN TOP.SLS (A.K.A. HIGHSTATE)

To apply all configured states, simply run state.apply:

salt '*' state.apply

The following additional arguments are also accepted when applying all states configured in top.sls:

test

Run states in test-only (dry-run) mode

pillar

Custom Pillar values, passed as a dictionary of key-value pairs

salt '*' state.apply test pillar='{"foo": "bar"}'

Note

Values passed this way will override Pillar values set via pillar_roots or an external Pillar source.

queue

: False

Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this option sparingly.

localconfig

Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc.

salt '*' state.apply localconfig=/path/to/minion.yml

APPLYING INDIVIDUAL SLS FILES (A.K.A. STATE.SLS)

To apply individual SLS files, pass them as a comma-separated list:

# Run the states configured in salt://test.sls (or salt://test/init.sls)
salt '*' state.apply test
# Run the states configured in salt://test.sls (or salt://test/init.sls)
# and salt://pkgs.sls (or salt://pkgs/init.sls).
salt '*' state.apply test,pkgs

The following additional arguments are also accepted when applying individual SLS files:

test

Run states in test-only (dry-run) mode

pillar

Custom Pillar values, passed as a dictionary of key-value pairs

salt '*' state.apply test pillar='{"foo": "bar"}'

Note

Values passed this way will override Pillar values set via pillar_roots or an external Pillar source.

queue

: False

Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this option sparingly.

concurrent

: False

Execute state runs concurrently instead of serially

Warning

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

saltenv

: None

Specify a salt fileserver environment to be used when applying states

Changed in version 0.17.0: Argument name changed from env to saltenv

Changed in version 2014.7.0: If no saltenv is specified, the minion config will be checked for a saltenv parameter and if found, it will be used. If none is found, base will be used. In prior releases, the minion config was not checked and base would always be assumed when the saltenv was not explicitly set.

pillarenv

Specify a Pillar environment to be used when applying states. By default, all Pillar environments will be merged together and used.

localconfig

Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc.

salt '*' state.apply test localconfig=/path/to/minion.yml

salt.modules.state.check_request(name=None)¶

New in version 2015.5.0.

Return the state request information, if any

CLI Example:

salt '*' state.check_request

salt.modules.state.clear_cache()¶

Clear out cached state files, forcing even cache runs to refresh the cache on the next state execution.

Remember that the state cache is completely disabled by default, this execution only applies if cache=True is used in states

CLI Example:

salt '*' state.clear_cache

salt.modules.state.clear_request(name=None)¶

New in version 2015.5.0.

Clear out the state execution request without executing it

CLI Example:

salt '*' state.clear_request

salt.modules.state.disable(states)¶

Disable state runs.

CLI Example:

salt '*' state.disable highstate

salt '*' state.disable highstate,test.succeed_without_changes

Note

To disable a state file from running provide the same name that would be passed in a state.sls call.

salt '*' state.disable bind.config

salt.modules.state.enable(states)¶

Enable state function or sls run

CLI Example:

salt '*' state.enable highstate

salt '*' state.enable test.succeed_without_changes

Note

To enable a state file from running provide the same name that would be passed in a state.sls call.

salt '*' state.disable bind.config

salt.modules.state.high(data, test=None, queue=False, **kwargs)¶

Execute the compound calls stored in a single set of high data

This function is mostly intended for testing the state system andis not likely to be needed in everyday usage.

CLI Example:

salt '*' state.high '{"vim": {"pkg": ["installed"]}}'

salt.modules.state.highstate(test=None, queue=False, **kwargs)¶

Retrieve the state data from the salt master for this minion and execute it

test

Run states in test-only (dry-run) mode

pillar

Custom Pillar values, passed as a dictionary of key-value pairs

salt '*' state.apply test pillar='{"foo": "bar"}'

Note

Values passed this way will override Pillar values set via pillar_roots or an external Pillar source.

queue

: False

Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this option sparingly.

localconfig

Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc.

mock:

The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run.

New in version 2015.8.4.

CLI Examples:

salt '*' state.highstate

salt '*' state.highstate whitelist=sls1_to_run,sls2_to_run
salt '*' state.highstate exclude=sls_to_exclude
salt '*' state.highstate exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

salt '*' state.highstate pillar="{foo: 'Foo!', bar: 'Bar!'}"

salt.modules.state.list_disabled()¶

List the states which are currently disabled

CLI Example:

salt '*' state.list_disabled

salt.modules.state.low(data, queue=False, **kwargs)¶

Execute a single low data call

This function is mostly intended for testing the state system and is not likely to be needed in everyday usage.

CLI Example:

salt '*' state.low '{"state": "pkg", "fun": "installed", "name": "vi"}'

salt.modules.state.pkg(pkg_path, pkg_sum, hash_type, test=None, **kwargs)¶

Execute a packaged state run, the packaged state run will exist in a tarball available locally. This packaged state can be generated using salt-ssh.

CLI Example:

salt '*' state.pkg /tmp/state_pkg.tgz

salt.modules.state.request(mods=None, **kwargs)¶

New in version 2015.5.0.

Request that the local admin execute a state run via salt-call state.run_request All arguments match state.apply

CLI Example:

salt '*' state.request
salt '*' state.request test
salt '*' state.request test,pkgs

salt.modules.state.run_request(name='default', **kwargs)¶

New in version 2015.5.0.

Execute the pending state request

CLI Example:

salt '*' state.run_request

salt.modules.state.running(concurrent=False)¶

Return a list of strings that contain state return data if a state function is already running. This function is used to prevent multiple state calls from being run at the same time.

CLI Example:

salt '*' state.running

salt.modules.state.show_highstate(queue=False, **kwargs)¶

Retrieve the highstate data from the salt master and display it

Custom Pillar data can be passed with the pillar kwarg.

CLI Example:

salt '*' state.show_highstate

salt.modules.state.show_low_sls(mods, saltenv='base', test=None, queue=False, env=None, **kwargs)¶

Display the low data from a specific sls. The default environment is base, use saltenv (env in Salt 0.17.x and older) to specify a different environment.

CLI Example:

salt '*' state.show_low_sls foo

salt.modules.state.show_lowstate(queue=False, **kwargs)¶

List out the low data that will be applied to this minion

CLI Example:

salt '*' state.show_lowstate

salt.modules.state.show_sls(mods, saltenv='base', test=None, queue=False, env=None, **kwargs)¶

Display the state data from a specific sls or list of sls files on the master. The default environment is base, use saltenv (env in Salt 0.17.x and older) to specify a different environment.

This function does not support topfiles. For top.sls please use show_top instead.

Custom Pillar data can be passed with the pillar kwarg.

CLI Example:

salt '*' state.show_sls core,edit.vim dev

salt.modules.state.show_top(queue=False, **kwargs)¶

Return the top data that the minion will use for a highstate

CLI Example:

salt '*' state.show_top

salt.modules.state.single(fun, name, test=None, queue=False, **kwargs)¶

Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command

By default, the values of the kwargs will be parsed as YAML. So, you can specify lists values, or lists of single entry key-value maps, as you would in a YAML salt file. Alternatively, JSON format of keyword values is also supported.

CLI Example:

salt '*' state.single pkg.installed name=vim

salt.modules.state.sls(mods, saltenv=None, test=None, exclude=None, queue=False, env=None, pillarenv=None, **kwargs)¶

Execute the states in one or more SLS files

test

Run states in test-only (dry-run) mode

pillar

Custom Pillar values, passed as a dictionary of key-value pairs

salt '*' state.apply test pillar='{"foo": "bar"}'

Note

Values passed this way will override Pillar values set via pillar_roots or an external Pillar source.

queue

: False

Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this option sparingly.

concurrent

: False

Execute state runs concurrently instead of serially

Warning

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

saltenv

: None

Specify a salt fileserver environment to be used when applying states

Changed in version 0.17.0: Argument name changed from env to saltenv

Changed in version 2014.7.0: If no saltenv is specified, the minion config will be checked for a saltenv parameter and if found, it will be used. If none is found, base will be used. In prior releases, the minion config was not checked and base would always be assumed when the saltenv was not explicitly set.

pillarenv

Specify a Pillar environment to be used when applying states. By default, all Pillar environments will be merged together and used.

localconfig

Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc.

mock:

The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run.

New in version 2015.8.4.

CLI Example:

salt '*' state.sls core,edit.vim dev
salt '*' state.sls core exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

salt '*' state.sls myslsfile pillar="{foo: 'Foo!', bar: 'Bar!'}"

salt.modules.state.sls_id(id_, mods, saltenv='base', test=None, queue=False, **kwargs)¶

Call a single ID from the named module(s) and handle all requisites

New in version 2014.7.0.

CLI Example:

salt '*' state.sls_id apache http

salt.modules.state.template(tem, queue=False, **kwargs)¶

Execute the information stored in a template file on the minion.

This function does not ask a master for a SLS file to render but instead directly processes the file at the provided path on the minion.

CLI Example:

salt '*' state.template '<Path to template on the minion>'

salt.modules.state.template_str(tem, queue=False, **kwargs)¶

Execute the information stored in a string from an sls template

CLI Example:

salt '*' state.template_str '<Template String>'

salt.modules.state.top(topfn, test=None, queue=False, saltenv=None, **kwargs)¶

Execute a specific top file instead of the default. This is useful to apply configurations from a different environment (for example, dev or prod), without modifying the default top file.

CLI Example:

salt '*' state.top reverse_top.sls
salt '*' state.top prod_top.sls exclude=sls_to_exclude
salt '*' state.top dev_top.sls exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"