diff --git a/doc/ref/states/master_side.rst b/doc/ref/states/master_side.rst index 616e4065a8..84fabf18e8 100644 --- a/doc/ref/states/master_side.rst +++ b/doc/ref/states/master_side.rst @@ -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 `. - 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 diff --git a/doc/ref/states/overstate.rst b/doc/ref/states/overstate.rst index c2993a0e28..08e6cc53b8 100644 --- a/doc/ref/states/overstate.rst +++ b/doc/ref/states/overstate.rst @@ -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 `. -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. diff --git a/doc/topics/tutorials/states_pt5.rst b/doc/topics/tutorials/states_pt5.rst new file mode 100644 index 0000000000..ff327a5b79 --- /dev/null +++ b/doc/topics/tutorials/states_pt5.rst @@ -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 ` pages. It is recommended to start with + :doc:`Part 1 ` if you are not familiar with how to use states. + + +Orchestration can be accomplished in two distinct ways: + +1. The :ref:`OverState System `. Added in version 0.11.0, + this Salt :doc:`Runner ` 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 `. Added in version 0.17.0, + this Salt :doc:`Runner ` can use the full suite of + :doc:`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: + +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 `, 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 + ` 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 ` on all minions whose + minion IDs start with "web". + +3. Finally, the ``all`` stage will execute, running :mod:`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 `. 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 `, 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 ` 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 `: + +.. code-block:: yaml + + install_nginx: + salt.state: + - tgt: 'web*' + - sls: + - nginx + +To execute a function, use :mod:`salt.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 ` + 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 `, 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 +`, 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``.