================================================= 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 is accomplished in salt primarily through 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 replaces the :ref:`OverState `. .. _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 ~~~~~~~~~~~~~~~~~~~~~~ Whereas 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``. .. _states-overstate: The OverState System -------------------- .. warning:: The OverState runner is deprecated, and will be removed in the feature release of Salt codenamed Boron. (Three 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 `, 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 ` 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.