mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +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.
This commit is contained in:
Seth House
parent
6bbe0cb46c
commit
7e5f8be530
@ -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 </ref/states/index>`.
|
||||
|
||||
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 <state_top>` 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
|
||||
<ref/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
|
||||
<salt.states.pkg>` to ensure that a given package is installed.
|
||||
|
||||
The third line, called the :term:`function` defines which function in the
|
||||
:mod:`pkg state <salt.states.pkg>` module to call.
|
||||
The third line, called the :term:`function declaration` defines which function
|
||||
in the :mod:`pkg state <salt.states.pkg>` 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 </ref/renderers/index>`.
|
||||
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
|
||||
</ref/renderers/index>` 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 <salt.modules.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
|
||||
<salt.modules.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 <salt-minion
|
||||
-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 <states_pt2>` 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 <states_pt2>` will build on this example to cover more advanced
|
||||
:term:`sls` syntax and will explore more of the states that ship with Salt.
|
||||
|
||||
@ -5,105 +5,85 @@ States tutorial, part 2
|
||||
This tutorial builds on the topic covered in :doc:`part 1 <states_pt1>`. 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
|
||||
<master>` and transfer configuration and files to the :term:`Salt minions
|
||||
<minion>`.
|
||||
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 <state_top>` 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 <states_pt3>`.
|
||||
|
||||
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 <salt.states.file>`.
|
||||
@ -123,11 +103,8 @@ In this example, it is referring to the ``ID declaration`` from our example in
|
||||
:doc:`part 1 <states_pt1>`. 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``:
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Last, call :func:`state.highstate <salt.modules.state.highstate>` which
|
||||
instructs the minion to fetch and execute the highstate from the Salt master::
|
||||
Last, call :func:`state.highstate <salt.modules.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 <states_pt3>` we will discuss how to use templating in the
|
||||
``sls`` files.
|
||||
.. admonition:: ``require`` vs. ``watch``
|
||||
|
||||
There are two :term:`requisite declarations <requisite declaration>`,
|
||||
“require” and “watch”. Not every state supports “watch”. In the :mod:`file
|
||||
state <salt.states.file>`, 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 <states_pt3>` we will discuss how to use includes, extends and
|
||||
templating to make hugely complicated State Tree configurations dead-simple.
|
||||
|
||||
@ -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 </ref/states/index>`. If you have any questions,
|
||||
suggestions, or just want to chat with other people who are using Salt we have
|
||||
an :doc:`active community </topics/community>`.
|
||||
:doc:`reference documentation </ref/states/index>` and to look through examples
|
||||
of existing :term:`state trees <state tree>`. 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 </topics/community>`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user