salt.modules.state

Control the state system on the minion.

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 with no SLS targets, like so:

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

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.

pillar

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

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

Note

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

exclude

Exclude specific states from execution. Accepts a list of sls names, a comma-separated string of sls names, or a list of dictionaries containing sls or id keys. Glob-patterns may be used to match multiple states.

salt '*' state.apply exclude=bar,baz
salt '*' state.apply exclude=foo*
salt '*' state.apply exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
queueFalse

Instead of failing immediately when another state run is in progress, a value of True will 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.

Changed in version 3006.0: This parameter can also be set via the state_queue configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered.

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
state_events

The state_events option sends progress events as each function in a state run completes execution.

New in version 3006.0.

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://stuff.sls (or salt://stuff/init.sls)
salt '*' state.apply stuff

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

# Run the states configured in a more deeply nested directory such as salt://my/organized/stuff.sls (or salt://my/organized/stuff/init.sls)
salt '*' state.apply my.organized.stuff

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

test

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

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.

pillar

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

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

Note

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

queueFalse

Instead of failing immediately when another state run is in progress, a value of True will 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.

Changed in version 3006.0: This parameter can also be set via the state_queue configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered.

concurrentFalse

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

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 an environment 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. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

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 stuff localconfig=/path/to/minion.yml
sync_mods

If specified, the desired custom module types will be synced prior to running the SLS files:

salt '*' state.apply stuff sync_mods=states,modules
salt '*' state.apply stuff sync_mods=all

Note

This option is ignored when no SLS files are specified, as a highstate automatically syncs all custom module types.

New in version 2017.7.8,2018.3.3,2019.2.0.

state_events

The state_events option sends progress events as each function in a state run completes execution.

New in version 3006.0.

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.event(tagmatch='*', count=-1, quiet=False, sock_dir=None, pretty=False, node='minion')

Watch Salt's event bus and block until the given tag is matched

New in version 2016.3.0.

Changed in version 2019.2.0: tagmatch can now be either a glob or regular expression.

This is useful for utilizing Salt's event bus from shell scripts or for taking simple actions directly from the CLI.

Enable debug logging to see ignored events.

Parameters:

  • tagmatch -- the event is written to stdout for each tag that matches this glob or regular expression.

  • count -- this number is decremented for each event that matches the tagmatch parameter; pass -1 to listen forever.

  • quiet -- do not print to stdout; just block

  • sock_dir -- path to the Salt master's event socket file.

  • pretty -- Output the JSON all on a single line if False (useful for shell tools); pretty-print the JSON output if True.

  • node -- Watch the minion-side or master-side event bus.

CLI Example:

salt-call --local state.event pretty=True
salt.modules.state.get_pauses(jid=None)

Get a report on all of the currently paused state runs and pause run settings. Optionally send in a jid if you only desire to see a single pause data set.

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

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

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

CLI Example:

salt '*' state.high '{"vim": {"pkg": ["installed"]}}'
salt.modules.state.highstate(test=None, queue=None, state_events=None, **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.highstate stuff pillar='{"foo": "bar"}'

Note

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

Changed in version 2016.3.0: GPG-encrypted CLI Pillar data is now supported via the GPG renderer. See here for details.

pillar_enc

Specify which renderer to use to decrypt encrypted data located within the pillar value. Currently, only gpg is supported.

New in version 2016.3.0.

exclude

Exclude specific states from execution. Accepts a list of sls names, a comma-separated string of sls names, or a list of dictionaries containing sls or id keys. Glob-patterns may be used to match multiple states.

salt '*' state.highstate exclude=bar,baz
salt '*' state.highstate exclude=foo*
salt '*' state.highstate exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
saltenv

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. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

queueFalse

Instead of failing immediately when another state run is in progress, a value of True will 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.

Changed in version 3006.0: This parameter can also be set via the state_queue configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered.

concurrentFalse

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.

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.

state_events

The state_events option sends progress events as each function in a state run completes execution.

New in version 3006.0.

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.id_exists(ids, mods, test=None, queue=None, **kwargs)

Tests for the existence of a specific ID or list of IDs within the specified SLS file(s). Similar to state.sls_exists, returns True or False. The default environment is base``, use saltenv to specify a different environment.

New in version 2019.2.0.

saltenv

Specify a salt fileserver environment from which to look for the SLS files specified in the mods argument

CLI Example:

salt '*' state.id_exists create_myfile,update_template filestate saltenv=dev
salt.modules.state.list_disabled()

List the states which are currently disabled

CLI Example:

salt '*' state.list_disabled
salt.modules.state.low(data, queue=None, **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.orchestrate(mods, saltenv='base', test=None, exclude=None, pillar=None, pillarenv=None)

New in version 2016.11.0.

Execute the orchestrate runner from a masterless minion.

See also

More Orchestrate documentation

CLI Examples:

salt-call --local state.orchestrate webserver
salt-call --local state.orchestrate webserver saltenv=dev test=True
salt-call --local state.orchestrate webserver saltenv=dev pillarenv=aws
salt.modules.state.pause(jid, state_id=None, duration=None)

Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds. If a state_id is not passed then the jid referenced will be paused at the beginning of the next state run.

The given state id is the id got a given state execution, so given a state that looks like this:

vim:
  pkg.installed: []

The state_id to pass to pause is vim

CLI Examples:

salt '*' state.pause 20171130110407769519
salt '*' state.pause 20171130110407769519 vim
salt '*' state.pause 20171130110407769519 vim 20
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/salt_state.tgz 760a9353810e36f6d81416366fc426dc md5
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 those of state.apply.

CLI Example:

salt '*' state.request
salt '*' state.request stuff
salt '*' state.request stuff,pkgs
salt.modules.state.resume(jid, state_id=None)

Remove a pause from a jid, allowing it to continue. If the state_id is not specified then the a general pause will be resumed.

The given state_id is the id got a given state execution, so given a state that looks like this:

vim:
  pkg.installed: []

The state_id to pass to rm_pause is vim

CLI Examples:

salt '*' state.resume 20171130110407769519
salt '*' state.resume 20171130110407769519 vim
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=None, **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, test=None, queue=None, **kwargs)

Display the low data from a specific sls. The default environment is base, use saltenv to specify a different environment.

saltenv

Specify a salt fileserver environment to be used when applying states

pillar

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

salt '*' state.show_low_sls stuff pillar='{"foo": "bar"}'

Note

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

pillarenv

Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

CLI Example:

salt '*' state.show_low_sls foo
salt '*' state.show_low_sls foo saltenv=dev
salt.modules.state.show_lowstate(queue=None, **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, test=None, queue=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 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.

saltenv

Specify a salt fileserver environment to be used when applying states

pillarenv

Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

CLI Example:

salt '*' state.show_sls core,edit.vim saltenv=dev
salt.modules.state.show_state_usage(queue=None, **kwargs)

Retrieve the highstate data from the salt master to analyse used and unused states

Custom Pillar data can be passed with the pillar kwarg.

CLI Example:

salt '*' state.show_state_usage
salt.modules.state.show_states(queue=None, **kwargs)

Returns the list of states that will be applied on highstate.

CLI Example:

salt '*' state.show_states

New in version 2019.2.0.

salt.modules.state.show_top(queue=None, **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=None, **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, test=None, exclude=None, queue=None, sync_mods=None, state_events=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.sls stuff pillar='{"foo": "bar"}'

Note

Values passed this way will override existing Pillar values set via pillar_roots or an external Pillar source. Pillar values that are not included in the kwarg will not be overwritten.

Changed in version 2016.3.0: GPG-encrypted CLI Pillar data is now supported via the GPG renderer. See here for details.

pillar_enc

Specify which renderer to use to decrypt encrypted data located within the pillar value. Currently, only gpg is supported.

New in version 2016.3.0.

exclude

Exclude specific states from execution. Accepts a list of sls names, a comma-separated string of sls names, or a list of dictionaries containing sls or id keys. Glob-patterns may be used to match multiple states.

salt '*' state.sls foo,bar,baz exclude=bar,baz
salt '*' state.sls foo,bar,baz exclude=ba*
salt '*' state.sls foo,bar,baz exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
queueFalse

Instead of failing immediately when another state run is in progress, a value of True will 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.

Changed in version 3006.0: This parameter can also be set via the state_queue configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered.

concurrentFalse

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

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 an environment 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. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

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.

sync_mods

If specified, the desired custom module types will be synced prior to running the SLS files:

salt '*' state.sls stuff sync_mods=states,modules
salt '*' state.sls stuff sync_mods=all

New in version 2017.7.8,2018.3.3,2019.2.0.

state_events

The state_events option sends progress events as each function in a state run completes execution.

New in version 3006.0.

CLI Example:

# Run the states configured in salt://example.sls (or salt://example/init.sls)
salt '*' state.apply example

# Run the states configured in salt://core.sls (or salt://core/init.sls)
# and salt://edit/vim.sls (or salt://edit/vim/init.sls)
salt '*' state.sls core,edit.vim

# Run the states configured in a more deeply nested directory such as salt://my/nested/state.sls (or salt://my/nested/state/init.sls)
salt '*' state.sls my.nested.state

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_exists(mods, test=None, queue=None, **kwargs)

Tests for the existence the of a specific SLS or list of SLS files on the master. Similar to state.show_sls, rather than returning state details, returns True or False. The default environment is base, use saltenv to specify a different environment.

New in version 2019.2.0.

saltenv

Specify a salt fileserver environment from which to look for the SLS files specified in the mods argument

CLI Example:

salt '*' state.sls_exists core,edit.vim saltenv=dev
salt.modules.state.sls_id(id_, mods, test=None, queue=None, state_events=None, **kwargs)

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

The state ID comes before the module ID(s) on the command line.

id

ID to call

mods

Comma-delimited list of modules to search for given id and its requisites

New in version 2014.7.0.

saltenvbase

Specify a salt fileserver environment to be used when applying states

pillarenv

Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

pillar

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

salt '*' state.sls_id my_state my_module pillar='{"foo": "bar"}'

Note

Values passed this way will override existing Pillar values set via pillar_roots or an external Pillar source. Pillar values that are not included in the kwarg will not be overwritten.

New in version 2018.3.0.

CLI Example:

salt '*' state.sls_id my_state my_module

salt '*' state.sls_id my_state my_module,a_common_module
salt.modules.state.soft_kill(jid, state_id=None)

Set up a state run to die before executing the given state id, this instructs a running state to safely exit at a given state id. This needs to pass in the jid of the running state. If a state_id is not passed then the jid referenced will be safely exited at the beginning of the next state run.

The given state id is the id got a given state execution, so given a state that looks like this:

vim:
  pkg.installed: []

The state_id to pass to soft_kill is vim

CLI Examples:

salt '*' state.soft_kill 20171130110407769519
salt '*' state.soft_kill 20171130110407769519 vim
salt.modules.state.template(tem, queue=None, **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=None, **kwargs)

Execute the information stored in a string from an sls template

CLI Example:

salt '*' state.template_str '<Template String>'
salt.modules.state.test(*args, **kwargs)

New in version 3001.

Alias for state.apply with the kwarg test forced to True.

This is a nicety to avoid the need to type out test=True and the possibility of a typo causing changes you do not intend.

salt.modules.state.top(topfn, test=None, queue=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.

queueFalse

Instead of failing immediately when another state run is in progress, a value of True will 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.

Changed in version 3006.0: This parameter can also be set via the state_queue configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered.

saltenv

Specify a salt fileserver environment to be used when applying states

pillarenv

Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

New in version 2017.7.0.

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'}]"

Generated on October 23, 2024 at 09:02:06 UTC.

You are viewing docs for the latest stable release, 3007.1. Switch to docs for the previous stable release, 3006.9, or to a recent doc build from the master branch.


saltproject.io

© 2024 VMware, Inc. | Privacy Policy