valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 00:55:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Reorganize orchestration doc and deprecate overstate runner

Browse Source
This commit is contained in:
Colton Myers 2014-11-18 16:31:36 -07:00
parent 4e6f7d6880
commit c0f7756153
1 changed files with 139 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

273
doc/topics/tutorials/states_pt5.rst
View File

@ -9,140 +9,12 @@ States Tutorial, Part 5 - Orchestration with Salt
: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 have 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
.. note::
The ``match`` argument uses :ref:`compound matching <targeting-compound>`
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.
Orchestration is accomplished in salt primarily through 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 replaces the :ref:`OverState
<states-overstate>`.
.. _orchestrate-runner:
@ -274,3 +146,136 @@ Given the above setup, the orchestration will be carried out as follows:
3. Finally, the ``ceph`` SLS target will be executed on all minions which have
a grain called ``role`` with a value of ``storage``.
.. _states-overstate:
The OverState System
--------------------
.. warning::
The OverState runner is deprecated, and will be removed in the feature
release of Salt codenamed Beryllium. (Two feature releases after 2014.7.0,
which is codenamed Helium)
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 have 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
.. note::
The ``match`` argument uses :ref:`compound matching <targeting-compound>`
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.