mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
Move OverState and state.sls docs to new location
This commit is contained in:
Erik Johnson
parent
dafda30944
commit
fc062e5d27
@ -1,81 +1,8 @@
|
||||
=====================
|
||||
Remote Control States
|
||||
=====================
|
||||
|
||||
.. versionadded:: 0.17.0
|
||||
|
||||
Remote Control States is the capability to organize routines on minions from the
|
||||
master, using state files.
|
||||
|
||||
This allows for the use of the Salt state system to execute state runs and
|
||||
function runs in a way more powerful than the overstate, will full command of
|
||||
the requisite and ordering systems inside of states.
|
||||
======================
|
||||
The Orchestrate Runner
|
||||
======================
|
||||
|
||||
.. note::
|
||||
|
||||
Remote Control States was added in 0.17.0 with the intent to eventually
|
||||
deprecate the overstate system in favor of this new, substantially more
|
||||
powerful system.
|
||||
This documentation has been moved :ref:`here <orchestrate-runner>`.
|
||||
|
||||
The Overstate will still be maintained for the foreseeable future.
|
||||
|
||||
Creating States Trigger Remote Executions
|
||||
=========================================
|
||||
|
||||
The new `salt` state module allows for these new states to be defined in
|
||||
such a way to call out to the `salt` and/or the `salt-ssh` remote execution
|
||||
systems, this also supports the addition of states to connect to remote
|
||||
embedded devices.
|
||||
|
||||
To create a state that calls out to minions simple specify the `salt.state`
|
||||
or `salt.function` states:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
This sls file can now be referenced by the `state.sls` runner the same way
|
||||
an sls is normally referenced, assuming the default configuration with /srv/salt
|
||||
as the root of the state tree and the above file being saved as
|
||||
/srv/salt/webserver.sls, the state can be run from the master with the salt-run
|
||||
command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.sls webserver
|
||||
|
||||
This will execute the defined state to fire up the webserver routine.
|
||||
|
||||
Calling Multiple State Runs
|
||||
===========================
|
||||
|
||||
All of the concepts of states exist so building something more complex is
|
||||
easy:
|
||||
|
||||
.. note::
|
||||
|
||||
As of Salt 0.17.0 states are run in the order in which they are defined,
|
||||
so the cmd.run defined below will always execute first
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- roster: scan
|
||||
- tgt: 10.0.0.0/24
|
||||
- arg:
|
||||
- 'bootstrap'
|
||||
|
||||
storage_setup:
|
||||
salt.state:
|
||||
- tgt: 'role:storage'
|
||||
- tgt_type: grain
|
||||
- sls: ceph
|
||||
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
@ -1,94 +1,8 @@
|
||||
.. _states-overstate:
|
||||
|
||||
================
|
||||
OverState System
|
||||
================
|
||||
|
||||
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.
|
||||
.. note::
|
||||
|
||||
The 0.11.0 release of Salt addresses this problem with a new layer in the state
|
||||
system called the `Over State`. The concept of the `Over State` is managed on
|
||||
the master, a series of state executions is controlled from the master and
|
||||
executed in order. If an execution requires that another execution first run
|
||||
without problems then the state executions will stop.
|
||||
This documentation has been moved :ref:`here <states-overstate>`.
|
||||
|
||||
The `Over State` system is used to orchestrate deployment in a smooth and
|
||||
reliable way across multiple systems in small to large environments.
|
||||
|
||||
The Over State SLS
|
||||
==================
|
||||
|
||||
The overstate system is managed by an sls file located in the root of an
|
||||
environment. This file uses a data structure like all sls files.
|
||||
|
||||
The overstate sls file configures an unordered list of stages, each stage
|
||||
defines the minions to execute on and can define what sls files to run
|
||||
or to execute a state.highstate.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
mysql:
|
||||
match: 'db*'
|
||||
sls:
|
||||
- mysql.server
|
||||
- drbd
|
||||
webservers:
|
||||
match: 'web*'
|
||||
require:
|
||||
- mysql
|
||||
all:
|
||||
match: '*'
|
||||
require:
|
||||
- mysql
|
||||
- webservers
|
||||
|
||||
The above defined over state will execute the mysql stage first because it is
|
||||
required by the webservers stage. The webservers stage will then be executed
|
||||
only if the mysql stage executes without any issues. The webservers stage
|
||||
will execute state.highstate on the matched minions, while the mysql stage
|
||||
will execute state.sls with the named sls files.
|
||||
|
||||
Finally the all stage will execute state.highstate on all systems only if the
|
||||
mysql and webservers stages complete without failures. The overstate system
|
||||
checks for any states that return a result of `False`, if the run has any
|
||||
`False` returns then the overstate will quit.
|
||||
|
||||
Adding Functions To Overstate
|
||||
=============================
|
||||
|
||||
In 0.15.0 the ability to execute module functions directly in the overstate
|
||||
was added. Functions are called as a stage with the function key:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
http:
|
||||
function:
|
||||
pkg.install:
|
||||
- http
|
||||
|
||||
|
||||
The list of function arguments are passed after the declared function.
|
||||
Requisites only functions properly if the given function supports returning
|
||||
a custom return code.
|
||||
|
||||
Executing the Over State
|
||||
========================
|
||||
|
||||
The over state can be executed from the salt-run command, calling the
|
||||
state.over runner function. The function will by default look in the base
|
||||
environment for the `overstate.sls` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.over
|
||||
|
||||
To specify the location of the overstate file and the environment to pull from
|
||||
pass the arguments to the salt-run command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.over base /root/overstate.sls
|
||||
|
||||
Remember, that these calls are made on the master.
|
||||
|
||||
273
doc/topics/tutorials/states_pt5.rst
Normal file
273
doc/topics/tutorials/states_pt5.rst
Normal file
@ -0,0 +1,273 @@
|
||||
=================================================
|
||||
States Tutorial, Part 5 - Orchestration with Salt
|
||||
=================================================
|
||||
|
||||
.. note::
|
||||
|
||||
This tutorial builds on some of the topics covered in the earlier
|
||||
:doc:`States Walkthrough <states_pt1>` pages. It is recommended to start with
|
||||
:doc:`Part 1 <states_pt1>` if you are not familiar with how to use states.
|
||||
|
||||
|
||||
Orchestration can be accomplished in two distinct ways:
|
||||
|
||||
1. The :ref:`OverState System <states-overstate>`. Added in version 0.11.0,
|
||||
this Salt :doc:`Runner </ref/runners/index>` allows for SLS files to be
|
||||
organized into stages, and to require that one or more stages successfully
|
||||
execute before another stage will run.
|
||||
|
||||
2. The :ref:`Orchestrate Runner <orchestrate-runner>`. Added in version 0.17.0,
|
||||
this Salt :doc:`Runner </ref/runners/index>` can use the full suite of
|
||||
:doc:`requisites </ref/states/requisites>` available in states, and can also
|
||||
execute states/functions using salt-ssh. This runner was designed with the
|
||||
eventual goal of replacing the :ref:`OverState <states-overstate>`.
|
||||
|
||||
|
||||
.. _states-overstate:
|
||||
|
||||
The OverState System
|
||||
--------------------
|
||||
|
||||
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 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 :mod:`state.highstate <salt.modules.state.highstate>`, or
|
||||
execute a function. Here's a sample overstate.sls:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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 :mod:`state.sls
|
||||
<salt.modules.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
|
||||
:mod:`state.highstate <salt.modules.state.highstate>` on all minions whose
|
||||
minion IDs start with "web".
|
||||
|
||||
3. Finally, the ``all`` stage will execute, running :mod:`state.highstate
|
||||
<salt.modules.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 :mod:`state.highstate <salt.modules.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:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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 :doc:`Runner </ref/runners/index>`, it is executed
|
||||
using the ``salt-run`` command. The runner function for the OverState is
|
||||
``state.over``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.over
|
||||
|
||||
The function will by default look in the root of the ``base`` environment (as
|
||||
defined in :conf_master:`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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _orchestrate-runner:
|
||||
|
||||
The Orchestrate Runner
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 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:
|
||||
|
||||
* All :doc:`requisites </ref/states/requisites>` available in states can be
|
||||
used.
|
||||
* The states/functions can be executed using salt-ssh.
|
||||
|
||||
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.
|
||||
|
||||
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 :mod:`salt.state <salt.states.saltmod.state>`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
install_nginx:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- sls:
|
||||
- nginx
|
||||
|
||||
To execute a function, use :mod:`salt.function <salt.states.saltmod.function>`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- tgt: '*'
|
||||
- arg:
|
||||
- rm -rf /tmp/foo
|
||||
|
||||
|
||||
Triggering a Highstate
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orchestration.webserver
|
||||
salt-run state.orch orchestration.webserver
|
||||
|
||||
.. versionchanged:: 2014.1.1
|
||||
|
||||
The runner function was renamed to ``state.orchestrate``. In versions
|
||||
0.17.0 through 2014.1.0, ``state.sls`` must be used. This was renamed to
|
||||
avoid confusion with the :mod:`state.sls <salt.modules.state.sls>`
|
||||
execution function.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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 :doc:`requisites </ref/states/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 :doc:`requisites
|
||||
</ref/states/requisites>`, as is the default in SLS files since 0.17.0.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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``.
|
||||
Loading…
Reference in New Issue
Block a user