States Tutorial, Part 5 - Orchestration with Salt¶

Configuration Syntax¶

The configuration differs slightly from that of the OverState, and more closely resembles the configuration schema used for states.

To execute a state, use salt.state:

install_nginx:
  salt.state:
    - tgt: 'web*'
    - sls:
      - nginx

To execute a function, use salt.function:

cmd.run:
  salt.function:
    - tgt: '*'
    - arg:
      - rm -rf /tmp/foo

Triggering a Highstate¶

Whereas with the OverState, a Highstate is run by simply omitting an sls or function argument, with the Orchestrate Runner the Highstate must explicitly be requested by using highstate: True:

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

Executing the Orchestrate Runner¶

The Orchestrate Runner can be executed using the state.orchestrate runner function. state.orch also works, for those that would like to type less.

Assuming that your base environment is located at /srv/salt, and you have placed a configuration file in /srv/salt/orchestration/webserver.sls, then the following could both be used:

salt-run state.orchestrate orchestration.webserver
salt-run state.orch orchestration.webserver

salt-run state.sls orchestration.webserver

More Complex Orchestration¶

Many states/functions can be configured in a single file, which when combined with the full suite of requisites, 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, as is the default in SLS files since 0.17.0.

cmd.run:
  salt.function:
    - 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:

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

The OverState SLS¶

The OverState system is managed by an SLS file named overstate.sls, located in the root of a Salt fileserver environment.

The overstate.sls configures an unordered list of stages, each stage defines the minions on which to execute the state, and can define what sls files to run, execute a state.highstate, or execute a function. Here's a sample overstate.sls:

mysql:
  match: 'db*'
  sls:
    - mysql.server
    - drbd
webservers:
  match: 'web*'
  require:
    - mysql
all:
  match: '*'
  require:
    - mysql
    - webservers

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

1. The mysql stage will be executed first because it is required by the webservers and all stages. It will execute state.sls once for each of the two listed SLS targets (mysql.server and drbd). These states will be executed on all minions whose minion ID starts with "db".
2. The webservers stage will then be executed, but only if the mysql stage executes without any failures. The webservers stage will execute a state.highstate on all minions whose minion IDs start with "web".
3. Finally, the all stage will execute, running state.highstate on all systems, if and only if the mysql and webservers stages completed without any failures.

Any failure in the above steps would cause the requires to fail, preventing the dependent stages from executing.

Using Functions with OverState¶

In the above example, you'll notice that the stages lacking an sls entry run a state.highstate. As mentioned earlier, it is also possible to execute other functions in a stage. This functionality was added in version 0.15.0.

Running a function is easy:

http:
  function:
    pkg.install:
      - httpd

The list of function arguments are defined after the declared function. So, the above stage would run pkg.install http. Requisites only function properly if the given function supports returning a custom return code.

Executing an OverState¶

Since the OverState is a Runner, it is executed using the salt-run command. The runner function for the OverState is state.over.

salt-run state.over

The function will by default look in the root of the base environment (as defined in file_roots) for a file called overstate.sls, and then execute the stages defined within that file.

Different environments and paths can be used as well, by adding them as positional arguments:

salt-run state.over dev /root/other-overstate.sls

The above would run an OverState using the dev fileserver environment, with the stages defined in /root/other-overstate.sls.