Note
This tutorial builds on some of the topics covered in the earlier States Walkthrough pages. It is recommended to start with Part 1 if you are not familiar with how to use states.
Orchestration can be accomplished in two distinct ways:
Often servers need to be set up and configured in a specific order, and systems should only be set up if systems earlier in the sequence has been set up without any issues.
The OverState system can be used to orchestrate deployment in a smooth and reliable way across multiple systems in small to large environments.
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:
Any failure in the above steps would cause the requires to fail, preventing the dependent stages from executing.
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.
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.
Warning
Since these are positional arguments, when defining the path to the overstate file the environment must also be specified, even if it is the base environment.
Note
Remember, salt-run is always executed on the master.
New in version 0.17.0.
As noted above in the introduction, the Orchestrate Runner (originally called the state.sls runner) offers all the functionality of the OverState, but with a couple advantages:
The Orchestrate Runner was added with the intent to eventually deprecate the OverState system, however the OverState will still be maintained for the foreseeable future.
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
Wheras 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
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
Changed in version 2014.1.1.
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:
Current Salt release: 2014.1.6
Docs for previous releases on salt.rtfd.org.