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

Move OverState and state.sls docs to new location

Browse Source
This commit is contained in:
Erik Johnson 2014-03-13 20:59:28 -05:00
parent dafda30944
commit fc062e5d27
3 changed files with 279 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
doc/ref/states/master_side.rst
View File

@ -1,81 +1,8 @@
===================== ======================
Remote Control States The Orchestrate Runner
===================== ======================
.. 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.
.. note:: .. note::
Remote Control States was added in 0.17.0 with the intent to eventually This documentation has been moved :ref:`here <orchestrate-runner>`.
deprecate the overstate system in favor of this new, substantially more
powerful system.
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

90
doc/ref/states/overstate.rst
View File

@ -1,94 +1,8 @@
.. _states-overstate:
================ ================
OverState System OverState System
================ ================
Often servers need to be set up and configured in a specific order, and systems .. note::
should only be set up if systems earlier in the sequence has been set up
without any issues.
The 0.11.0 release of Salt addresses this problem with a new layer in the state This documentation has been moved :ref:`here <states-overstate>`.
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.
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
View 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``.