Orchestrate Runner¶

Orchestration is accomplished in salt primarily through the Orchestrate Runner. Added in version 0.17.0, this Salt Runner can use the full suite of Requisites and Other Global State Arguments available in states, and can also execute states/functions using salt-ssh.

The Orchestrate Runner¶

New in version 0.17.0.

Note

Orchestrate Deprecates OverState

The Orchestrate Runner (originally called the state.sls runner) offers all the functionality of the OverState, but with some advantages:

All Requisites and Other Global State Arguments available in states can be used.
The states/functions will also work on salt-ssh minions.

The Orchestrate Runner was added with the intent to eventually deprecate the OverState system, however the OverState will still be maintained until Salt 2015.8.0.

The orchestrate runner generalizes the Salt state system to a Salt master context. Whereas the state.sls, state.highstate, et al functions are concurrently and independently executed on each Salt minion, the state.orchestrate runner is executed on the master, giving it a master-level view and control over requisites, such as state ordering and conditionals. This allows for inter minion requisites, like ordering the application of states on different minions that must not happen simultaneously, or for halting the state run on all minions if a minion fails one of its states.

If you want to setup a load balancer in front of a cluster of web servers, for example, you can ensure the load balancer is setup before the web servers or stop the state run altogether if one of the minions does not set up correctly.

The state.sls, state.highstate, et al functions allow you to statefully manage each minion and the state.orchestrate runner allows you to statefully manage your entire infrastructure.

Executing the Orchestrate Runner¶

The Orchestrate Runner command format is the same as for the state.sls function, except that since it is a runner, it is executed with salt-run rather than salt. Assuming you have a state.sls file called /srv/salt/orch/webserver.sls the following command run on the master will apply the states defined in that file.

salt-run state.orchestrate orch.webserver

Note

state.orch is a synonym for state.orchestrate

Changed in version 2014.1.1: The runner function was renamed to state.orchestrate to avoid confusion with the state.sls execution function. In versions 0.17.0 through 2014.1.0, state.sls must be used.

Examples¶

Function¶

To execute a function, use salt.function:

# /srv/salt/orch/cleanfoo.sls
cmd.run:
  salt.function:
    - tgt: '*'
    - arg:
      - rm -rf /tmp/foo

salt-run state.orchestrate orch.cleanfoo

If you omit the "name" argument, the ID of the state will be the default name, or in the case of salt.function, the execution module function to run. You can specify the "name" argument to avoid conflicting IDs:

copy_some_file:
  salt.function:
    - name: file.copy
    - tgt: '*'
    - arg:
      - /path/to/file
      - /tmp/copy_of_file
    - kwarg:
        remove_existing: true

State¶

To execute a state, use salt.state.

# /srv/salt/orch/webserver.sls
install_nginx:
  salt.state:
    - tgt: 'web*'
    - sls:
      - nginx

salt-run state.orchestrate orch.webserver

Highstate¶

To run a highstate, set highstate: True in your state config:

# /srv/salt/orch/web_setup.sls
webserver_setup:
  salt.state:
    - tgt: 'web*'
    - highstate: True

salt-run state.orchestrate orch.web_setup

More Complex Orchestration¶

Many states/functions can be configured in a single file, which when combined with the full suite of Requisites and Other Global State Arguments, can be used to easily configure complex orchestration tasks. Additionally, the states/functions will be executed in the order in which they are defined, unless prevented from doing so by any Requisites and Other Global State Arguments, as is the default in SLS files since 0.17.0.

bootstrap_servers:
  salt.function:
    - name: cmd.run
    - tgt: 10.0.0.0/24
    - tgt_type: ipcidr
    - arg:
      - bootstrap

storage_setup:
  salt.state:
    - tgt: 'role:storage'
    - tgt_type: grain
    - sls: ceph
    - require:
      - salt: webserver_setup

webserver_setup:
  salt.state:
    - tgt: 'web*'
    - highstate: True

Given the above setup, the orchestration will be carried out as follows:

The shell command bootstrap will be executed on all minions in the 10.0.0.0/24 subnet.
A Highstate will be run on all minions whose ID starts with "web", since the storage_setup state requires it.
Finally, the ceph SLS target will be executed on all minions which have a grain called role with a value of storage.

Note

Remember, salt-run is always executed on the master.