mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 17:09:03 +00:00
388 lines
9.6 KiB
ReStructuredText
388 lines
9.6 KiB
ReStructuredText
.. _states-highstate:
|
|
|
|
====================================
|
|
Highstate data structure definitions
|
|
====================================
|
|
|
|
The Salt State Tree
|
|
===================
|
|
|
|
A state tree is a collection of ``SLS`` files that live under the directory
|
|
specified in :conf_master:`file_roots`. A state tree can be organized into
|
|
``SLS modules``.
|
|
|
|
.. _states-highstate-top-file:
|
|
|
|
Top file
|
|
--------
|
|
|
|
The main state file that instructs minions what environment and modules to use
|
|
during state execution.
|
|
|
|
Configurable via :conf_master:`state_top`.
|
|
|
|
.. seealso:: :doc:`A detailed description of the top file </ref/states/top>`
|
|
|
|
.. _include-declaration:
|
|
|
|
Include declaration
|
|
-------------------
|
|
|
|
Defines a list of :ref:`module-reference` strings to include in this ``SLS``.
|
|
|
|
Occurs only in the top level of the highstate structure.
|
|
|
|
Example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
include:
|
|
- edit.vim
|
|
- http.server
|
|
|
|
.. _module-reference:
|
|
|
|
Module reference
|
|
----------------
|
|
|
|
The name of a SLS module defined by a separate SLS file and residing on
|
|
the Salt Master. A module named ``edit.vim`` is a reference to the SLS
|
|
file ``salt://edit/vim.sls``.
|
|
|
|
.. _id-declaration:
|
|
|
|
ID declaration
|
|
--------------
|
|
|
|
Defines an individual highstate component. Always references a value of a
|
|
dictionary containing keys referencing :ref:`state-declaration` and
|
|
:ref:`requisite-declaration`. Can be overridden by a :ref:`name-declaration` or
|
|
a :ref:`names-declaration`.
|
|
|
|
Occurs on the top level or under the :ref:`extend-declaration`.
|
|
|
|
Must be unique across entire state tree. If the same ID declaration is
|
|
used twice, only the first one matched will be used. All subsequent
|
|
ID declarations with the same name will be ignored.
|
|
|
|
.. note:: Naming gotchas
|
|
|
|
Until 0.9.6, IDs could **not** contain a dot, otherwise highstate
|
|
summary output was unpredictable. (It was fixed in versions 0.9.7 and
|
|
above)
|
|
|
|
.. _extend-declaration:
|
|
|
|
Extend declaration
|
|
------------------
|
|
|
|
Extends a :ref:`name-declaration` from an included ``SLS module``. The
|
|
keys of the extend declaration always define existing :ref`ID declaration`
|
|
which have been defined in included
|
|
``SLS modules``.
|
|
|
|
Occurs only in the top level and defines a dictionary.
|
|
|
|
States cannot be extended more than once in a single state run.
|
|
|
|
Extend declarations are useful for adding-to or overriding parts of a
|
|
:ref:`state-declaration` that is defined in another ``SLS`` file. In the
|
|
following contrived example, the shown ``mywebsite.sls`` file is ``include``
|
|
-ing and ``extend`` -ing the ``apache.sls`` module in order to add a ``watch``
|
|
declaration that will restart Apache whenever the Apache configuration file,
|
|
``mywebsite`` changes.
|
|
|
|
.. code-block:: yaml
|
|
|
|
include:
|
|
- apache
|
|
|
|
extend:
|
|
apache:
|
|
service:
|
|
- watch:
|
|
- file: mywebsite
|
|
|
|
mywebsite:
|
|
file:
|
|
- managed
|
|
|
|
.. seealso:: watch_in and require_in
|
|
|
|
Sometimes it is more convenient to use the :ref:`watch_in
|
|
<requisites-watch-in>` or :ref:`require_in <requisites-require-in>` syntax
|
|
instead of extending another ``SLS`` file.
|
|
|
|
:doc:`State Requisites </ref/states/requisites>`
|
|
|
|
.. _state-declaration:
|
|
|
|
State declaration
|
|
-----------------
|
|
|
|
A list which contains one string defining the :ref:`function-declaration` and
|
|
any number of :ref:`function-arg-declaration` dictionaries.
|
|
|
|
Can, optionally, contain a number of additional components like the
|
|
name override components — :ref:`name <name-declaration>` and
|
|
:ref:`names <names-declaration>`. Can also contain :ref:`requisite
|
|
declarations <requisite-declaration>`.
|
|
|
|
Occurs under an :ref:`ID-declaration`.
|
|
|
|
.. _requisite-declaration:
|
|
|
|
Requisite declaration
|
|
---------------------
|
|
|
|
A list containing :ref:`requisite references <requisite-reference>`.
|
|
|
|
Used to build the action dependency tree. While Salt states are made to
|
|
execute in a deterministic order, this order is managed by requiring
|
|
and watching other Salt states.
|
|
|
|
Occurs as a list component under a :ref:`state-declaration` or as a
|
|
key under an :ref:`ID-declaration`.
|
|
|
|
.. _requisite-reference:
|
|
|
|
Requisite reference
|
|
-------------------
|
|
|
|
A single key dictionary. The key is the name of the referenced
|
|
:ref:`state-declaration` and the value is the ID of the referenced
|
|
:ref:`ID-declaration`.
|
|
|
|
Occurs as a single index in a :ref:`requisite-declaration` list.
|
|
|
|
.. _function-declaration:
|
|
|
|
Function declaration
|
|
--------------------
|
|
|
|
The name of the function to call within the state. A state declaration
|
|
can contain only a single function declaration.
|
|
|
|
For example, the following state declaration calls the :mod:`installed
|
|
<salt.states.pkg.installed>` function in the ``pkg`` state module:
|
|
|
|
.. code-block:: yaml
|
|
|
|
httpd:
|
|
pkg.installed
|
|
|
|
The function can be declared inline with the state as a shortcut, but
|
|
the actual data structure is better referenced in this form:
|
|
|
|
.. code-block:: yaml
|
|
|
|
httpd:
|
|
pkg:
|
|
- installed
|
|
|
|
Where the function is a string in the body of the state declaration.
|
|
Technically when the function is declared in dot notation the compiler
|
|
converts it to be a string in the state declaration list. Note that the
|
|
use of the first example more than once in an ID declaration is invalid
|
|
yaml.
|
|
|
|
INVALID:
|
|
|
|
.. code-block:: yaml
|
|
|
|
httpd:
|
|
pkg.installed
|
|
service.running
|
|
|
|
When passing a function without arguments and another state declaration
|
|
within a single ID declaration, then the long or "standard" format
|
|
needs to be used since otherwise it does not represent a valid data
|
|
structure.
|
|
|
|
VALID:
|
|
|
|
.. code-block:: yaml
|
|
|
|
httpd:
|
|
pkg:
|
|
- installed
|
|
service:
|
|
- running
|
|
|
|
Occurs as the only index in the :ref:`state-declaration` list.
|
|
|
|
.. _function-arg-declaration:
|
|
|
|
Function arg declaration
|
|
------------------------
|
|
|
|
A single key dictionary referencing a Python type which is to be passed
|
|
to the named :ref:`function-declaration` as a parameter. The type must
|
|
be the data type expected by the function.
|
|
|
|
Occurs under a :ref:`function-declaration`.
|
|
|
|
For example in the following state declaration ``user``, ``group``, and
|
|
``mode`` are passed as arguments to the :mod:`managed
|
|
<salt.states.file.managed>` function in the ``file`` state module:
|
|
|
|
.. code-block:: yaml
|
|
|
|
/etc/http/conf/http.conf:
|
|
file.managed:
|
|
- user: root
|
|
- group: root
|
|
- mode: 644
|
|
|
|
.. _name-declaration:
|
|
|
|
Name declaration
|
|
----------------
|
|
|
|
Overrides the ``name`` argument of a :ref:`state-declaration`. If
|
|
``name`` is not specified the :ref:`ID-declaration` satisfies the
|
|
``name`` argument.
|
|
|
|
The name is always a single key dictionary referencing a string.
|
|
|
|
Overriding ``name`` is useful for a variety of scenarios.
|
|
|
|
For example, avoiding clashing ID declarations. The following two state
|
|
declarations cannot both have ``/etc/motd`` as the ID declaration:
|
|
|
|
.. code-block:: yaml
|
|
|
|
motd_perms:
|
|
file.managed:
|
|
- name: /etc/motd
|
|
- mode: 644
|
|
|
|
motd_quote:
|
|
file.append:
|
|
- name: /etc/motd
|
|
- text: "Of all smells, bread; of all tastes, salt."
|
|
|
|
Another common reason to override ``name`` is if the ID declaration is long and
|
|
needs to be referenced in multiple places. In the example below it is much
|
|
easier to specify ``mywebsite`` than to specify
|
|
``/etc/apache2/sites-available/mywebsite.com`` multiple times:
|
|
|
|
.. code-block:: yaml
|
|
|
|
mywebsite:
|
|
file.managed:
|
|
- name: /etc/apache2/sites-available/mywebsite.com
|
|
- source: salt://mywebsite.com
|
|
|
|
a2ensite mywebsite.com:
|
|
cmd.wait:
|
|
- unless: test -L /etc/apache2/sites-enabled/mywebsite.com
|
|
- watch:
|
|
- file: mywebsite
|
|
|
|
apache2:
|
|
service:
|
|
- running
|
|
- watch:
|
|
- file: mywebsite
|
|
|
|
.. _names-declaration:
|
|
|
|
Names declaration
|
|
-----------------
|
|
|
|
Expands the contents of the containing :ref:`state-declaration` into
|
|
multiple state declarations, each with its own name.
|
|
|
|
For example, given the following state declaration:
|
|
|
|
.. code-block:: yaml
|
|
|
|
python-pkgs:
|
|
pkg.installed:
|
|
- names:
|
|
- python-django
|
|
- python-crypto
|
|
- python-yaml
|
|
|
|
Once converted into the lowstate data structure the above state
|
|
declaration will be expanded into the following three state declarations:
|
|
|
|
.. code-block:: yaml
|
|
|
|
python-django:
|
|
pkg.installed
|
|
|
|
python-crypto:
|
|
pkg.installed
|
|
|
|
python-yaml:
|
|
pkg.installed
|
|
|
|
.. _states-highstate-example:
|
|
|
|
Large example
|
|
=============
|
|
|
|
Here is the layout in yaml using the names of the highdata structure
|
|
components.
|
|
|
|
.. code-block:: yaml
|
|
|
|
<Include Declaration>:
|
|
- <Module Reference>
|
|
- <Module Reference>
|
|
|
|
<Extend Declaration>:
|
|
<ID Declaration>:
|
|
[<overrides>]
|
|
|
|
|
|
# standard declaration
|
|
|
|
<ID Declaration>:
|
|
<State Declaration>:
|
|
- <Function>
|
|
- <Function Arg>
|
|
- <Function Arg>
|
|
- <Function Arg>
|
|
- <Name>: <name>
|
|
- <Requisite Declaration>:
|
|
- <Requisite Reference>
|
|
- <Requisite Reference>
|
|
|
|
|
|
# inline function and names
|
|
|
|
<ID Declaration>:
|
|
<State Declaration>.<Function>:
|
|
- <Function Arg>
|
|
- <Function Arg>
|
|
- <Function Arg>
|
|
- <Names>:
|
|
- <name>
|
|
- <name>
|
|
- <name>
|
|
- <Requisite Declaration>:
|
|
- <Requisite Reference>
|
|
- <Requisite Reference>
|
|
|
|
|
|
# multiple states for single id
|
|
|
|
<ID Declaration>:
|
|
<State Declaration>:
|
|
- <Function>
|
|
- <Function Arg>
|
|
- <Name>: <name>
|
|
- <Requisite Declaration>:
|
|
- <Requisite Reference>
|
|
<State Declaration>:
|
|
- <Function>
|
|
- <Function Arg>
|
|
- <Names>:
|
|
- <name>
|
|
- <name>
|
|
- <Requisite Declaration>:
|
|
- <Requisite Reference>
|