salt/doc/topics/tutorials/states_pt2.rst

.. _tutorial-states-part-2:

=========================================================
States tutorial, part 2 - More Complex States, Requisites
=========================================================

.. note::

    This tutorial builds on topics covered in :ref:`part 1 <states-tutorial>`. It is
    recommended that you begin there.

In the :ref:`last part <states-tutorial>` of the Salt States tutorial we covered the
basics of installing a package. We will now modify our ``webserver.sls`` file
to have requirements, and use even more Salt States.

Call multiple States
====================

You can specify multiple :ref:`state-declaration` under an
:ref:`id-declaration`. For example, a quick modification to our
``webserver.sls`` to also start Apache if it is not running:

.. code-block:: yaml
    :linenos:
    :emphasize-lines: 4,5

    apache:
      pkg.installed: []
      service.running:
        - require:
          - pkg: apache

Try stopping Apache before running :py:func:`state.apply
<salt.modules.state.apply_>` once again and observe the output.

.. note::

    For those running RedhatOS derivatives (Centos, AWS), you will want to specify the
    service name to be httpd. More on state service here, :mod:`service state
    <salt.states.service>`.  With the example above, just add "- name: httpd"
    above the require line and with the same spacing.


Require other states
====================

We now have a working installation of Apache so let's add an HTML file to
customize our website. It isn't exactly useful to have a website without a
webserver so we don't want Salt to install our HTML file until Apache is
installed and running. Include the following at the bottom of your
``webserver/init.sls`` file:

.. code-block:: yaml
    :linenos:
    :emphasize-lines: 7,11

    apache:
      pkg.installed: []
      service.running:
        - require:
          - pkg: apache

    /var/www/index.html:                        # ID declaration
      file:                                     # state declaration
        - managed                               # function
        - source: salt://webserver/index.html   # function arg
        - require:                              # requisite declaration
          - pkg: apache                         # requisite reference

**line 7** is the :ref:`id-declaration`. In this example it is the location we
want to install our custom HTML file. (**Note:** the default location that
Apache serves may differ from the above on your OS or distro. ``/srv/www``
could also be a likely place to look.)

**Line 8** the :ref:`state-declaration`. This example uses the Salt :mod:`file
state <salt.states.file>`.

**Line 9** is the :ref:`function-declaration`. The :func:`managed function
<salt.states.file.managed>` will download a file from the master and install it
in the location specified.

**Line 10** is a :ref:`function-arg-declaration` which, in this example, passes
the ``source`` argument to the :func:`managed function
<salt.states.file.managed>`.

**Line 11** is a :ref:`requisite-declaration`.

**Line 12** is a :ref:`requisite-reference` which refers to a state and an ID.
In this example, it is referring to the ``ID declaration`` from our example in
:ref:`part 1 <states-tutorial>`. This declaration tells Salt not to install the HTML
file until Apache is installed.

Next, create the ``index.html`` file and save it in the ``webserver``
directory:

.. code-block:: html

    <!DOCTYPE html>
    <html>
        <head><title>Salt rocks</title></head>
        <body>
            <h1>This file brought to you by Salt</h1>
        </body>
    </html>

Last, call :func:`state.apply <salt.modules.state.apply_>` again and the minion
will fetch and execute the :ref:`highstate <running-highstate>` as well as our
HTML file from the master using Salt's File Server:

.. code-block:: bash

    salt '*' state.apply

Verify that Apache is now serving your custom HTML.

.. admonition:: ``require`` vs. ``watch``

    There are two :ref:`requisite-declaration`, “require”, and “watch”. Not
    every state supports “watch”. The :mod:`service state
    <salt.states.service>` does support “watch” and will restart a service
    based on the watch condition.

    For example, if you use Salt to install an Apache virtual host
    configuration file and want to restart Apache whenever that file is changed
    you could modify our Apache example from earlier as follows:

    .. code-block:: yaml
        :emphasize-lines: 1,2,3,4,11,12

        /etc/httpd/extra/httpd-vhosts.conf:
          file.managed:
            - source: salt://webserver/httpd-vhosts.conf

        apache:
          pkg.installed: []
          service.running:
            - watch:
              - file: /etc/httpd/extra/httpd-vhosts.conf
            - require:
              - pkg: apache

    If the pkg and service names differ on your OS or distro of choice you can
    specify each one separately using a :ref:`name-declaration` which explained
    in :ref:`Part 3 <tutorial-states-part-3>`.

Next steps
==========

In :ref:`part 3 <tutorial-states-part-3>` we will discuss how to use includes, extends, and
templating to make a more complete State Tree configuration.
Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			`.. _tutorial-states-part-2:`

Add sub-titles to other states tutorial pages 2014-03-14 02:02:33 +00:00			`=========================================================`
			`States tutorial, part 2 - More Complex States, Requisites`
			`=========================================================`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Fix trailing whitespace Conflicts: doc/topics/tutorials/states_pt2.rst 2014-12-11 15:50:14 +00:00			`.. note::`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			This tutorial builds on topics covered in :ref:`part 1 <states-tutorial>`. It is
Fix double-colon and remove redundant section There is a section in part 2 that is already covered in-depth in part 1, this commit removes it. 2014-07-14 17:34:03 +00:00			`recommended that you begin there.`
more documentation cleanup 2012-08-03 06:23:39 +00:00
Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			In the :ref:`last part <states-tutorial>` of the Salt States tutorial we covered the
Fix double-colon and remove redundant section There is a section in part 2 that is already covered in-depth in part 1, this commit removes it. 2014-07-14 17:34:03 +00:00			basics of installing a package. We will now modify our ``webserver.sls`` file
			`to have requirements, and use even more Salt States.`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`Call multiple States`
			`====================`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Updated tutorials, highstate, and PyDSL docs from term links to ref 2014-02-28 01:27:07 +00:00			You can specify multiple :ref:`state-declaration` under an
			:ref:`id-declaration`. For example, a quick modification to our
Fixed mismatched glossary entries/definitions in the highstates docs 2011-11-26 08:52:59 +00:00			``webserver.sls`` to also start Apache if it is not running:
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
			`.. code-block:: yaml`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`:linenos:`
			`:emphasize-lines: 4,5`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`apache:`
Change all state examples to use short-dec format for consistency Closes #12419. The command used to search the docs for state examples is below. This generates a file in Vim's quickfix format that can be loaded with the -q flag. find . -type f \( -name '.rst' -o -name '.py' \) -print0 \| xargs -0 -P10 -n1 awk ' BEGIN { RS=""; FS="\n" } { linenr = linect; linect += (NF + 1) } /^\s+[a-zA-Z0-9'\''_-]+:\n\s+[a-zA-Z0-9'\''_-]+:\n\s+- / { print FILENAME "\|" linenr + 2 "\|", $1 } ' > ./salt-states.quickfix 2014-12-13 06:29:48 +00:00			`pkg.installed: []`
			`service.running:`
add require for service state in examples 2013-05-03 02:49:23 +00:00			`- require:`
			`- pkg: apache`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Improve state module docs, replace references to state.highstate/state.sls with state.apply Resolves #32037. 2016-03-22 03:56:17 +00:00			Try stopping Apache before running :py:func:`state.apply
			<salt.modules.state.apply_>` once again and observe the output.
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
added a note to the tutorial for those that redhat so they can use the state file too. 2015-10-30 16:47:46 +00:00			`.. note::`

			`For those running RedhatOS derivatives (Centos, AWS), you will want to specify the`
			service name to be httpd. More on state service here, :mod:`service state
			<salt.states.service>`. With the example above, just add "- name: httpd"
			`above the require line and with the same spacing.`


Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`Require other states`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00			`====================`

Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`We now have a working installation of Apache so let's add an HTML file to`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`customize our website. It isn't exactly useful to have a website without a`
			`webserver so we don't want Salt to install our HTML file until Apache is`
			`installed and running. Include the following at the bottom of your`
			``webserver/init.sls`` file:
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
			`.. code-block:: yaml`
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`:linenos:`
formatting and clarification cleanup in docs 2012-02-28 04:19:29 +00:00			`:emphasize-lines: 7,11`
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			`apache:`
Change all state examples to use short-dec format for consistency Closes #12419. The command used to search the docs for state examples is below. This generates a file in Vim's quickfix format that can be loaded with the -q flag. find . -type f \( -name '.rst' -o -name '.py' \) -print0 \| xargs -0 -P10 -n1 awk ' BEGIN { RS=""; FS="\n" } { linenr = linect; linect += (NF + 1) } /^\s+[a-zA-Z0-9'\''_-]+:\n\s+[a-zA-Z0-9'\''_-]+:\n\s+- / { print FILENAME "\|" linenr + 2 "\|", $1 } ' > ./salt-states.quickfix 2014-12-13 06:29:48 +00:00			`pkg.installed: []`
			`service.running:`
add require for service state in examples 2013-05-03 02:49:23 +00:00			`- require:`
			`- pkg: apache`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00
			`/var/www/index.html: # ID declaration`
			`file: # state declaration`
			`- managed # function`
			`- source: salt://webserver/index.html # function arg`
			`- require: # requisite declaration`
			`- pkg: apache # requisite reference`
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00
update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			line 7 is the :ref:`id-declaration`. In this example it is the location we
Updated tutorials, highstate, and PyDSL docs from term links to ref 2014-02-28 01:27:07 +00:00			`want to install our custom HTML file. (Note: the default location that`
			Apache serves may differ from the above on your OS or distro. ``/srv/www``
			`could also be a likely place to look.)`
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00
update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			Line 8 the :ref:`state-declaration`. This example uses the Salt :mod:`file
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			state <salt.states.file>`.

update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			Line 9 is the :ref:`function-declaration`. The :func:`managed function
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			<salt.states.file.managed>` will download a file from the master and install it
			`in the location specified.`

update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			Line 10 is a :ref:`function-arg-declaration` which, in this example, passes
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			the ``source`` argument to the :func:`managed function
formatting and clarification cleanup in docs 2012-02-28 04:19:29 +00:00			<salt.states.file.managed>`.
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00
update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			Line 11 is a :ref:`requisite-declaration`.
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00
update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			Line 12 is a :ref:`requisite-reference` which refers to a state and an ID.
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			In this example, it is referring to the ``ID declaration`` from our example in
Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			:ref:`part 1 <states-tutorial>`. This declaration tells Salt not to install the HTML
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`file until Apache is installed.`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			Next, create the ``index.html`` file and save it in the ``webserver``
			`directory:`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`.. code-block:: html`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
update States Tutorial part 2 Explanation of yaml file with matching line numbers 2014-12-24 00:20:42 +00:00			`<!DOCTYPE html>`
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`<html>`
			`<head><title>Salt rocks</title></head>`
			`<body>`
			`<h1>This file brought to you by Salt</h1>`
			`</body>`
			`</html>`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Improve state module docs, replace references to state.highstate/state.sls with state.apply Resolves #32037. 2016-03-22 03:56:17 +00:00			Last, call :func:`state.apply <salt.modules.state.apply_>` again and the minion
			will fetch and execute the :ref:`highstate <running-highstate>` as well as our
			`HTML file from the master using Salt's File Server:`
Formatting fixes This completes the documentation audit begun in cf365f7, using proper backticks and :strong: tags to emphasize text, converting groups of shell commands to bash code-block sections, etc. This also replaces the use of \* with the easier-to-grok '*', which will hopefully reduce confusion among new users. 2013-08-12 03:17:47 +00:00
			`.. code-block:: bash`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Improve state module docs, replace references to state.highstate/state.sls with state.apply Resolves #32037. 2016-03-22 03:56:17 +00:00			`salt '*' state.apply`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Finished the States tutorials They still need quite a bit of polish. 2011-10-31 01:23:12 +00:00			`Verify that Apache is now serving your custom HTML.`
wip: Split States tutorial into separate steps 2011-10-30 16:21:11 +00:00
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00			.. admonition:: ``require`` vs. ``watch``

Comma cleanup 2014-12-12 19:32:58 +00:00			There are two :ref:`requisite-declaration`, “require”, and “watch”. Not
Updated tutorials, highstate, and PyDSL docs from term links to ref 2014-02-28 01:27:07 +00:00			every state supports “watch”. The :mod:`service state
			<salt.states.service>` does support “watch” and will restart a service
			`based on the watch condition.`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00
			`For example, if you use Salt to install an Apache virtual host`
Fixed bad ``watch`` example; added a note about name declarations 2011-11-16 21:16:39 +00:00			`configuration file and want to restart Apache whenever that file is changed`
			`you could modify our Apache example from earlier as follows:`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00
			`.. code-block:: yaml`
Fixed bad ``watch`` example; added a note about name declarations 2011-11-16 21:16:39 +00:00			`:emphasize-lines: 1,2,3,4,11,12`

			`/etc/httpd/extra/httpd-vhosts.conf:`
Change all state examples to use short-dec format for consistency Closes #12419. The command used to search the docs for state examples is below. This generates a file in Vim's quickfix format that can be loaded with the -q flag. find . -type f \( -name '.rst' -o -name '.py' \) -print0 \| xargs -0 -P10 -n1 awk ' BEGIN { RS=""; FS="\n" } { linenr = linect; linect += (NF + 1) } /^\s+[a-zA-Z0-9'\''_-]+:\n\s+[a-zA-Z0-9'\''_-]+:\n\s+- / { print FILENAME "\|" linenr + 2 "\|", $1 } ' > ./salt-states.quickfix 2014-12-13 06:29:48 +00:00			`file.managed:`
Fixed bad ``watch`` example; added a note about name declarations 2011-11-16 21:16:39 +00:00			`- source: salt://webserver/httpd-vhosts.conf`
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00
			`apache:`
Change all state examples to use short-dec format for consistency Closes #12419. The command used to search the docs for state examples is below. This generates a file in Vim's quickfix format that can be loaded with the -q flag. find . -type f \( -name '.rst' -o -name '.py' \) -print0 \| xargs -0 -P10 -n1 awk ' BEGIN { RS=""; FS="\n" } { linenr = linect; linect += (NF + 1) } /^\s+[a-zA-Z0-9'\''_-]+:\n\s+[a-zA-Z0-9'\''_-]+:\n\s+- / { print FILENAME "\|" linenr + 2 "\|", $1 } ' > ./salt-states.quickfix 2014-12-13 06:29:48 +00:00			`pkg.installed: []`
			`service.running:`
Fixed bad ``watch`` example; added a note about name declarations 2011-11-16 21:16:39 +00:00			`- watch:`
			`- file: /etc/httpd/extra/httpd-vhosts.conf`
add require for service state in examples 2013-05-03 02:49:23 +00:00			`- require:`
			`- pkg: apache`
Fixed bad ``watch`` example; added a note about name declarations 2011-11-16 21:16:39 +00:00
			`If the pkg and service names differ on your OS or distro of choice you can`
Updated tutorials, highstate, and PyDSL docs from term links to ref 2014-02-28 01:27:07 +00:00			specify each one separately using a :ref:`name-declaration` which explained
Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			in :ref:`Part 3 <tutorial-states-part-3>`.
Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. 2011-11-16 16:20:59 +00:00
			`Next steps`
			`==========`

Remove more ":doc:" references from doc/* files 2016-12-15 22:36:44 +00:00			In :ref:`part 3 <tutorial-states-part-3>` we will discuss how to use includes, extends, and
more documentation cleanup 2012-08-03 06:23:39 +00:00			`templating to make a more complete State Tree configuration.`