Executing states or highstate on a minion is perfect when you want to ensure that minion configured and running the way you want. Sometimes however you want to configure a set of minions all at once.
For example, if you want to set up a load balancer in front of a cluster of web servers you can ensure the load balancer is set up first, and then the same matching configuration is applied consistently across the whole cluster.
Orchestration is the way to do this.
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:
The Orchestrate Runner replaced the OverState system in 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.
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.
Orchestrate SLS files are stored in the same location as State SLS files. This
means that both file_roots
and gitfs_remotes
impact what SLS files are
available to the reactor and orchestrator.
It is recommended to keep reactor and orchestrator SLS files in their own
uniquely named subdirectories such as _orch/
, orch/
, _orchestrate/
,
react/
, _reactor/
, etc. This will avoid duplicate naming and will help
prevent confusion.
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.
New in version 2016.11.0.
To support salt orchestration on masterless minions, the Orchestrate Runner is
available as an execution module. The syntax for masterless orchestration is
exactly the same, but it uses the salt-call
command and the minion
configuration must contain the file_mode: local
option. Alternatively,
use salt-call --local
on the command line.
salt-call --local state.orchestrate orch.webserver
Note
Masterless orchestration supports only the salt.state
command in an
sls file; it does not (currently) support the salt.function
command.
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
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
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
To execute another runner, use salt.runner
.
For example to use the cloud.profile
runner in your orchestration state
additional options to replace values in the configured profile, use this:
# /srv/salt/orch/deploy.sls
create_instance:
salt.runner:
- name: cloud.profile
- prof: cloud-centos
- provider: cloud
- instances:
- server1
- opts:
minion:
master: master1
To get a more dynamic state, use jinja variables together with
inline pillar data
.
Using the same example but passing on pillar data, the state would be like
this.
# /srv/salt/orch/deploy.sls
{% set servers = salt['pillar.get']('servers', 'test') %}
{% set master = salt['pillar.get']('master', 'salt') %}
create_instance:
salt.runner:
- name: cloud.profile
- prof: cloud-centos
- provider: cloud
- instances:
- {{ servers }}
- opts:
minion:
master: {{ master }}
To execute with pillar data.
salt-run state.orch orch.deploy pillar='{"servers": "newsystem1",
"master": "mymaster"}'
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:
bootstrap
will be executed on all minions in the
10.0.0.0/24 subnet.storage_setup
state requires it.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.
The orchestrate runner can be used to execute states on the master without
using a minion. For example, assume that salt://foo.sls
contains the
following SLS:
/etc/foo.conf:
file.managed:
- source: salt://files/foo.conf
- mode: 0600
In this case, running salt-run state.orchestrate foo
would be the
equivalent of running a state.sls foo
, but it would execute on the master
only, and would not require a minion daemon to be running on the master.
This is not technically orchestration, but it can be useful in certain use cases.