valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 17:09:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

States index re-write for clarity.

Browse Source
This commit is contained in:
Mike Place 2014-02-19 15:36:14 -07:00
parent 9e56b16ab2
commit 362931561d
1 changed files with 70 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
doc/ref/states/index.rst
View File

@ -6,20 +6,17 @@ Salt offers an optional interface to manage the configuration or "state" of the
Salt minions. This interface is a fully capable mechanism used to enforce the
state of systems from a central manager.
The Salt state system is made to be accurate, simple, and fast. And like the
rest of the Salt system, Salt states are highly modular.
State management
================
State management, also frequently called software configuration management
State management, also frequently called Software Configuration Management
(SCM), is a program that puts and keeps a system into a predetermined state. It
installs software packages, starts or restarts services, or puts configuration
installs software packages, starts or restarts services or puts configuration
files in place and watches them for changes.
Having a state management system in place allows you to easily and reliably
configure and manage a few servers or a few thousand servers. It allows you to
keep that configuration under version control.
Having a state management system in place allows one to easily and reliably
configure and manage a few servers or a few thousand servers. It allows
configurations to be kept under version control.
Salt States is an extension of the Salt Modules that we discussed in the
previous :doc:`remote execution </topics/tutorials/modules>` tutorial. Instead
@ -36,7 +33,7 @@ an understanding of Salt states and how to write the states is needed as well.
.. note::
States are compiled and executed only on minions that have been targeted.
To execute things on masters, see `runners`_.
To execute functions directly on masters, see `runners`_.
Salt SLS System
---------------
@ -59,8 +56,9 @@ Salt SLS System
SLS File Layout
```````````````
SLS files are laid out in the Salt file server. A simple layout can look like
this:
SLS files are laid out in the Salt file server.
A simple layout can look like this:
.. code-block:: yaml
@ -69,39 +67,43 @@ this:
sshd_config
users/init.sls
users/admin.sls
salt/init.sls
salt/master.sls
web/init.sls
This example shows the core concepts of file layout. The top file is a key
component and is used with Salt matchers to match SLS states with minions.
The ``.sls`` files are states. The rest of the files are seen by the Salt
master as just files that can be downloaded.
The ``top.sls`` file is a key component. The ``top.sls`` files
is used to determine which SLS files should be applied to which minions.
The states are translated into dot notation, so the ``ssh.sls`` file is
seen as the ssh state, the ``users/admin.sls`` file is seen as the
users.admin states.
The rest of the files with the ``.sls`` extension in the above example are
state files.
The init.sls files are translated to be the state name of the parent
directory, so the ``salt/init.sls`` file translates to the Salt state.
Files without a ``.sls`` extensions are seen by the Salt master as
files that can be downloaded to a Salt minion.
The plain files are visible to the minions, as well as the state files. In
Salt, everything is a file; there is no "magic translation" of files and file
States are translated into dot notation. For example, the ``ssh.sls`` file is
seen as the ssh state and the ``users/admin.sls`` file is seen as the
users.admin state.
Files named ``init.sls`` are translated to be the state name of the parent
directory, so the ``web/init.sls`` file translates to the ``web`` state.
In Salt, everything is a file; there is no "magic translation" of files and file
types. This means that a state file can be distributed to minions just like a
plain text or binary file.
SLS Files
`````````
The Salt state files are simple sets of data. Since the SLS files are just data
they can be represented in a number of different ways. The default format is
yaml generated from a Jinja template. This allows for the states files to have
all the language constructs of Python and the simplicity of yaml. State files
can then be complicated Jinja templates that translate down to yaml, or just
plain and simple yaml files!
The Salt state files are simple sets of data. Since SLS files are just data
they can be represented in a number of different ways.
The State files are constructed data structures in a simple format. The format
allows for many real activates to be expressed in very little text, while
maintaining the utmost in readability and usability.
The default format is YAML generated from a Jinja template. This allows for the
states files to have all the language constructs of Python and the simplicity of YAML.
State files can then be complicated Jinja templates that translate down to YAML, or just
plain and simple YAML files.
The State files are simply common data structures such as dictionaries and lists, constructed
using a templating language such as YAML.
Here is an example of a Salt State:
@ -142,12 +144,16 @@ watched file updated.
The Top File
````````````
The top file is the mapping for the state system. The top file specifies which
minions should have which modules applied and which environments they should
draw the states from.
The top file controls the mapping between minions and the states which should be
applied to them.
The top file works by specifying the environment, containing matchers with
lists of Salt states sent to the matching minions:
The top file specifies which minions should have which SLS files applied and which
environments they should draw those SLS files from.
The top file works by specifying environments on the top-level.
Each environment contains globs to match minions. Finally, each glob contains a list of
lists of Salt states to apply to matching minions:
.. code-block:: yaml
@ -160,46 +166,28 @@ lists of Salt states sent to the matching minions:
- match: pcre
- salt.master
This simple example uses the base environment, which is built into the default
Salt setup, and then all minions will have the modules salt, users and
users.admin since '*' will match all minions. Then the regular expression
matcher will match all minions' with an id matching saltmaster.* and add the
salt.master state.
This above example uses the base environment which is built into the default
Salt setup.
Renderer System
---------------
The Renderer system is a key component to the state system. SLS files are
representations of Salt "high data" structures. All Salt cares about when
reading an SLS file is the data structure that is produced from the file.
This allows Salt states to be represented by multiple types of files. The
Renderer system can be used to allow different formats to be used for SLS
files.
The available renderers can be found in the renderers directory in the Salt
source code:
:blob:`salt/renderers`
By default SLS files are rendered using Jinja as a templating engine, and yaml
as the serialization format. Since the rendering system can be extended simply
by adding a new renderer to the renderers directory, it is possible that any
structured file could be used to represent the SLS files.
In the future XML will be added, as well as many other formats.
The base environment has two globs. First, the '*' glob contains a list of
SLS files to apply to all minions.
The second glob contains a regular expression that will match all minions with
an ID matching saltmaster.* and specifies that for those minions, the salt.master
state should be applied.
Reloading Modules
-----------------
Some salt states require specific packages to be installed in order for the
module to load, as an example the :mod:`pip <salt.states.pip_state>` state
module requires the `pip`_ package for proper name and version parsing. On
most of the common cases, salt is clever enough to transparently reload the
modules, for example, if you install a package, salt reloads modules because
Some Salt states require that specific packages be installed in order for the
module to load. As an example the :mod:`pip <salt.states.pip_state>` state
module requires the `pip`_ package for proper name and version parsing.
In most of the common cases, Salt is clever enough to transparently reload the
modules. For example, if you install a package, Salt reloads modules because
some other module or state might require just that package which was installed.
On some edge-cases salt might need to be told to reload the modules. Consider
On some edge-cases salt might need to be told to reload the modules. Consider
the following state file which we'll call ``pep8.sls``:
.. code-block:: yaml
@ -265,19 +253,22 @@ If we executed the state again the output would be:
Total: 2
Since we installed `pip`_ using :mod:`cmd <salt.states.cmd>`, salt has no way
to know that a system-wide package was installed. On the second execution,
since the required `pip`_ package was installed, the state executed perfectly.
Since we installed `pip`_ using :mod:`cmd <salt.states.cmd>`, Salt has no way
to know that a system-wide package was installed.
To those thinking, could not salt reload modules on every state step since it
already does for some cases? It could, but it should not since it would
greatly slow down state execution.
On the second execution, since the required `pip`_ package was installed, the
state executed correctly.
.. note::
Salt does not reload modules on every state run because doing so would greatly
slow down state execution.
So how do we solve this *edge-case*? ``reload_modules``!
``reload_modules`` is a boolean option recognized by salt on **all** available
states which, does exactly what it tells use, forces salt to reload it's
modules once that specific state finishes. The fixed state file would now be:
states which forces salt to reload its modules once a given state finishes.
The modified state file would now be:
.. code-block:: yaml
@ -300,7 +291,7 @@ Let's run it, once:
salt-call state.sls pep8
And it's output now is:
The output is:
.. code-block:: text