From 7e5f8be5307340ce9e8be6496180563ed92a4d42 Mon Sep 17 00:00:00 2001 From: Seth House Date: Wed, 16 Nov 2011 09:20:59 -0700 Subject: [PATCH] Fixed and improved the States tutorials Got rid of the references to state.template and jumped straight into state.highstate use and configuration. --- doc/topics/tutorials/states_pt1.rst | 141 ++++++++++++++----- doc/topics/tutorials/states_pt2.rst | 201 ++++++++++++++-------------- doc/topics/tutorials/states_pt3.rst | 16 ++- 3 files changed, 219 insertions(+), 139 deletions(-) diff --git a/doc/topics/tutorials/states_pt1.rst b/doc/topics/tutorials/states_pt1.rst index a2d368f120..e1aeadaceb 100644 --- a/doc/topics/tutorials/states_pt1.rst +++ b/doc/topics/tutorials/states_pt1.rst @@ -6,81 +6,152 @@ The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state system please refer to the full :doc:`states reference `. -This tutorial will walk you through using Salt to configure a single system to -run the Apache HTTP server and to ensure the server is running. +This tutorial will walk you through using Salt to configure a minion to run the +Apache HTTP server and to ensure the server is running. .. include:: requisite_incl.rst -Create an ``sls`` file +Setting up the Salt State Tree +============================== + +States are stored in text files on the master and transfered to the minions on +demand via the master's File Server. The collection of state files make up the +:term:`State Tree`. + +To start using a central state system in Salt you must first set up the Salt +File Server. Edit your master config file (:conf_master:`file_roots`) and +uncomment the following lines: + +.. code-block:: yaml + + file_roots: + base: + - /srv/salt + +Restart the Salt master in order to pick up this change: + +.. code-block:: bash + + % pkill salt-master + % salt-master -d + +Preparing the Top File ====================== -Start by creating an empty :term:`sls file` named ``webserver.sls``. Type the -following and save the file: +On the master in the directory you specified in the previous step, create a new +file called :conf_master:`top.sls ` and add the following: + +.. code-block:: yaml + + base: + '*': + - webserver + +The :term:`top file` is separated into environments (discussed later). The +default environment is ``base``. Under the ``base`` environment a collection of +minion matches is defined; for now simply specify all hosts (``*``). + +.. admonition:: Targeting minions + + The expressions can use any of the targeting mechanisms used by Salt — + minions can be matched by glob, pcre regular expression, or by :doc:`grains + `. For example:: + + base: + 'os:Fedora': + - match: grain + - webserver + +Create an ``sls`` module +======================== + +In the same directory as your :term:`top file`, create an empty file, called an +:term:`sls module`, named ``webserver.sls``. Type the following and save the +file: .. code-block:: yaml :linenos: - apache2: # ID declaration + apache: # ID declaration pkg: # state declaration - - installed # function + - installed # function declaration The first line, called the :term:`ID declaration`, is an arbitrary identifier. -In this case it defines the name of the package to be installed. (The exact -package name for the Apache httpd web server may differ on your OS or distro.) +In this case it defines the name of the package to be installed. **NOTE:** the +package name for the Apache httpd web server may differ on your OS or distro — +for example, on Fedora it is ``httpd`` but on Debian/Ubuntu it is ``apache2``. The second line, called the :term:`state declaration`, defines which of the Salt States we are using. In this example, we are using the :mod:`pkg state ` to ensure that a given package is installed. -The third line, called the :term:`function` defines which function in the -:mod:`pkg state ` module to call. +The third line, called the :term:`function declaration` defines which function +in the :mod:`pkg state ` module to call. .. admonition:: Renderers States :term:`sls` files can be written in many formats. Salt requires only a simple data structure and is not concerned with how that data structure - is built. Building the expected structure is the job of Salt - :doc:`renderers `. + is built. Templating languages and `DSLs`_ are a dime-a-dozen and everyone + has a favorite. - In this tutorial we will be using yaml in Jinja2 templates which is the + Building the expected data structure is the job of Salt :doc:`renderers + ` and they are dead-simple to write. + + In this tutorial we will be using YAML in Jinja2 templates which is the default format. You can change the default by changing :conf_master:`renderer` in the master configuration file. +.. _`DSLs`: http://en.wikipedia.org/wiki/Domain-specific_language + Install the package =================== -Next, let's run that state. Open a terminal and run: +Next, let's run the state we created. Open a terminal on the master and run: .. code-block:: bash - % salt '*' state.template /path/to/your/helloworld.sls + % salt '*' state.highstate -:func:`state.template ` is the simplest way to use -Salt states. It takes the path to a template as an argument and executes it on -the minion. +Our master is instructing all targeted minions to run :func:`state.highstate +`. When a minion executes a highstate call it +will download the :term:`top file` and attempt to match the expressions. When +it does match an expression the modules listed for it will be downloaded, +compiled, and executed. -You should see a bunch of output as Salt installs Apache. +Once completed, the minion will report back with a summary of all actions taken +and all changes made. -Ensure a service is running -=========================== +.. admonition:: Troubleshooting Salt -Let's make a quick modification to also start Apache if it is not running: + In case you don't see the expected output, the following tips can help you + narrow down the problem. -.. code-block:: yaml - :linenos: - :emphasize-lines: 4,5 + Turn up logging + Salt can be quite chatty when you change the logging setting to + ``debug``:: - apache2: - pkg: - - installed - service: - - running + salt-minion -l debug -Run ``state.template`` once again and observe the output. + Run the minion in the foreground + By not starting the minion in daemon mode (:option:`-d `) you can view any output from the minion as it works:: + + salt-minion & + + Increase the default timeout value when running :command:`salt`. For + example, to change the default timeout to 60 seconds:: + + salt -t 60 + + For best results, combine all three:: + + salt-minion -l debug & # On the minion + salt '*' state.highstate -t 60 # On the master Next steps ========== -This tutorial focused on using Salt States only on the local system. :doc:`Part -2 ` of the will build on this example to cover using Salt States on -a remote host. +This tutorial focused on getting a simple Salt States configuration working. +:doc:`Part 2 ` will build on this example to cover more advanced +:term:`sls` syntax and will explore more of the states that ship with Salt. diff --git a/doc/topics/tutorials/states_pt2.rst b/doc/topics/tutorials/states_pt2.rst index a476fdc5cc..1b1d4ea1ea 100644 --- a/doc/topics/tutorials/states_pt2.rst +++ b/doc/topics/tutorials/states_pt2.rst @@ -5,105 +5,85 @@ States tutorial, part 2 This tutorial builds on the topic covered in :doc:`part 1 `. It is recommended that you begin there. -In the last Salt States tutorial we ran everything locally and did not take -advantage of Salt's tremendous ability to run on multiple hosts. In this -tutorial, we will modify ``webserver.sls`` to run from the :term:`Salt master -` and transfer configuration and files to the :term:`Salt minions -`. +In the last Salt States tutorial we covered the basics of installing a package. +In this tutorial we will modify our ``webserver.sls`` file to be more +complicated, have requirements, and use even more Salt States. -Setting up the Salt State Tree -============================== - -Groups of states are defined on the Salt master inside of the master's file -server and are expressed in a :term:`State Tree`. To start using a central -state system in Salt you must first set up the Salt File Server. Edit your -master config file (``/etc/salt/master``) and uncomment the following lines: - -.. code-block:: yaml - - file_roots: - base: - - /srv/salt - -Restart the Salt master in order to pick up this change: - -.. code-block:: bash - - % pkill salt-master - % salt-master -d - -Preparing the Top File -====================== - -On the master in the directory you specified in the previous step, create a new -file called :conf_master:`top.sls ` and add the following: - -.. code-block:: yaml - - base: - '*': - - webserver - -The :term:`top file` is separated into environments (discussed later). The -default environment is ``base``. Under the ``base`` environment a collection of -minion matches is defined; for now simply specify all hosts (``*``). - -.. admonition:: Matching minions - - The expressions can use any or the matching mechanisms used by Salt, so - minions can be matched by glob, pcre regular expression, or by grains. When - a minion executes a state call it will download the :term:`top file` and - attempt to match the expressions, when it does match an expression the - modules listed for it will be downloaded, compiled, and executed. - -Define an SLS module +Call multiple States ==================== -Move your ``webserver.sls`` file into the same directory as ``top.sls``. This -defines the "webserver sls module". - -SLS modules are appended with the file extension ``.sls`` and are referenced by -name starting at the root of the state tree. - -.. admonition:: Directories and SLS modules - - An SLS module can be also defined as a directory. If the directory - ``python`` exists, and a module named ``python`` is desired, than a file - called ``init.sls`` in the ``python`` directory can be used to define the - ``python`` module. For example:: - - |- top.sls - |- python - | |- init.sls - | `- django.sls - |- haproxy - | `- init.sls - `- core.sls - - In the example above the ``django.sls`` module would be referenced as - ``python.django``. - -Add a dependency -================ - -We now have a working installation of Apache so let's add an HTML file to -customize our website. Include the following at the bottom of your -``webserver.sls`` file: +You can specify multiple :term:`state declarations` under an :term:`ID +delcaration`. 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 - /var/www/index.html: # ID declaration - file: # state declaration - - managed # function - - source: salt://index.html # function arg - - require: # requisite declaration - - pkg: apache2 # requisite reference + apache: + pkg: + - installed + service: + - running + +Try stopping Apache before running ``state.highstate`` once again and observe +the output. + +Expand the SLS module +===================== + +As you have seen, sls modules are appended with the file extension ``.sls`` and +are referenced by name starting at the root of the state tree. An SLS module +can be also defined as a directory. Demonstrate that now by creating a +directory named ``webserver`` and moving and renaming ``webserver.sls`` to +``webserver/init.sls``. Your state directory should now resemble: + +:: + + |- top.sls + `- webserver/ + `- init.sls + +.. admonition:: Organizing SLS modules + + You can place additional ``.sls`` files in a state file directory. This + affords much cleaner organization of your state tree on the filesystem. For + example, if we created a ``webserver/django.sls`` file that module would be + referenced as ``webserver.django``. + + In addition, States provide powerful includes and extending functionality + which we will cover in :doc:`Part 3 `. + +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: 6,11 + + apache: + pkg: + - installed + service: + - running + + /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 Again in **line 1** is the :term:`ID declaration`. In this example it is the -location we want to install our custom HTML file. (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.) +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 2** the :term:`state declaration`. This example uses the Salt :mod:`file state `. @@ -123,11 +103,8 @@ In this example, it is referring to the ``ID declaration`` from our example in :doc:`part 1 `. This declaration tells Salt not to install the HTML file until Apache is installed. -Call the highstate -================== - -Create the ``index.html`` file and save it in the same directory as ``top.sls`` -and ``webserver.sls``: +Next, create the ``index.html`` file and save it in the ``webserver`` +directory: .. code-block:: html @@ -138,12 +115,38 @@ and ``webserver.sls``: -Last, call :func:`state.highstate ` which -instructs the minion to fetch and execute the highstate from the Salt master:: +Last, call :func:`state.highstate ` again and the +minion will fetch and execute the highstate as well as our HTML file from the +master using Salt's File Server:: salt '*' salt.highstate Verify that Apache is now serving your custom HTML. -In :doc:`part 3 ` we will discuss how to use templating in the -``sls`` files. +.. admonition:: ``require`` vs. ``watch`` + + There are two :term:`requisite declarations `, + “require” and “watch”. Not every state supports “watch”. In the :mod:`file + state `, for example, Salt will watch a file for changes + then take action if it does change. + + For example, if you use Salt to install an Apache virtual host + configuration file and want to restart Apache when that file is changed you + could modify our Apache example from earlier as follows: + + .. code-block:: yaml + :emphasize-lines: 6,7 + + apache: + pkg: + - installed + service: + - running + - watch: + - file: /etc/httpd/extra/httpd-vhosts.conf + +Next steps +========== + +In :doc:`part 3 ` we will discuss how to use includes, extends and +templating to make hugely complicated State Tree configurations dead-simple. diff --git a/doc/topics/tutorials/states_pt3.rst b/doc/topics/tutorials/states_pt3.rst index b0141d835e..c996bea635 100644 --- a/doc/topics/tutorials/states_pt3.rst +++ b/doc/topics/tutorials/states_pt3.rst @@ -205,10 +205,16 @@ can be rewritten without the loop: - larry - curly -Continue reading -================ +Continue learning +================= The best way to continue learing about Salt States is to read through the -:doc:`reference documentation `. If you have any questions, -suggestions, or just want to chat with other people who are using Salt we have -an :doc:`active community `. +:doc:`reference documentation ` and to look through examples +of existing :term:`state trees `. You can find examples in the +`salt-states repository`_ and please send a pull-request on GitHub with any +state trees that you build and want to share! + +.. _`salt-states repository`: https://github.com/saltstack/salt-states + +If you have any questions, suggestions, or just want to chat with other people +who are using Salt we have an :doc:`active community `.