1.. _states-highstate:
2
3====================================
4Highstate data structure definitions
5====================================
6
7The Salt State Tree
8===================
9
10A state tree is a collection of ``SLS`` files and directories that live under the directory
11specified in :conf_master:`file_roots`.
12
13.. note::
14
15   Directory names or filenames in the state tree cannot contain a period, with the
16   exception of the period in the .sls file suffix.
17
18.. _states-highstate-top-file:
19
20Top file
21--------
22
23The main state file that instructs minions what environment and modules to use
24during state execution.
25
26Configurable via :conf_master:`state_top`.
27
28.. seealso:: :ref:`A detailed description of the top file <states-top>`
29
30.. _include-declaration:
31
32Include declaration
33-------------------
34
35Defines a list of :ref:`module-reference` strings to include in this ``SLS``.
36
37Occurs only in the top level of the SLS data structure.
38
39Example:
40
41.. code-block:: yaml
42
43    include:
44      - edit.vim
45      - http.server
46
47.. _module-reference:
48
49Module reference
50----------------
51
52The name of a SLS module defined by a separate SLS file and residing on
53the Salt Master. A module named ``edit.vim`` is a reference to the SLS
54file ``salt://edit/vim.sls``.
55
56.. _id-declaration:
57
58ID declaration
59--------------
60
61Defines an individual :ref:`highstate <running-highstate>` component. Always
62references a value of a dictionary containing keys referencing
63:ref:`state-declaration` and :ref:`requisite-declaration`. Can be overridden by
64a :ref:`name-declaration` or a :ref:`names-declaration`.
65
66Occurs on the top level or under the :ref:`extend-declaration`.
67
68Must be unique across entire state tree. If the same ID declaration is
69used twice, only the first one matched will be used. All subsequent
70ID declarations with the same name will be ignored.
71
72.. note:: Naming gotchas
73
74    In Salt versions earlier than 0.9.7, ID declarations containing dots would
75    result in unpredictable output.
76
77.. _extend-declaration:
78
79Extend declaration
80------------------
81
82Extends a :ref:`name-declaration` from an included ``SLS module``. The
83keys of the extend declaration always refer to an existing
84:ref:`id-declaration` which have been defined in included ``SLS modules``.
85
86Occurs only in the top level and defines a dictionary.
87
88States cannot be extended more than once in a single state run.
89
90Extend declarations are useful for adding-to or overriding parts of a
91:ref:`state-declaration` that is defined in another ``SLS`` file. In the
92following contrived example, the shown ``mywebsite.sls`` file is ``include``
93-ing and ``extend`` -ing the ``apache.sls`` module in order to add a ``watch``
94declaration that will restart Apache whenever the Apache configuration file,
95``mywebsite`` changes.
96
97.. code-block:: yaml
98
99    include:
100      - apache
101
102    extend:
103      apache:
104        service:
105          - watch:
106            - file: mywebsite
107
108    mywebsite:
109      file.managed:
110        - name: /var/www/mysite
111
112.. seealso:: watch_in and require_in
113
114    Sometimes it is more convenient to use the :ref:`watch_in
115    <requisites-watch-in>` or :ref:`require_in <requisites-require-in>` syntax
116    instead of extending another ``SLS`` file.
117
118    :ref:`State Requisites <requisites>`
119
120.. _state-declaration:
121
122State declaration
123-----------------
124
125A list which contains one string defining the :ref:`function-declaration` and
126any number of :ref:`function-arg-declaration` dictionaries.
127
128Can, optionally, contain a number of additional components like the
129name override components — :ref:`name <name-declaration>` and
130:ref:`names <names-declaration>`. Can also contain :ref:`requisite
131declarations <requisite-declaration>`.
132
133Occurs under an :ref:`ID-declaration`.
134
135.. _requisite-declaration:
136
137Requisite declaration
138---------------------
139
140A list containing :ref:`requisite references <requisite-reference>`.
141
142Used to build the action dependency tree. While Salt states are made to
143execute in a deterministic order, this order is managed by requiring
144and watching other Salt states.
145
146Occurs as a list component under a :ref:`state-declaration` or as a
147key under an :ref:`ID-declaration`.
148
149.. _requisite-reference:
150
151Requisite reference
152-------------------
153
154A single key dictionary. The key is the name of the referenced
155:ref:`state-declaration` and the value is the ID of the referenced
156:ref:`ID-declaration`.
157
158Occurs as a single index in a :ref:`requisite-declaration` list.
159
160.. _function-declaration:
161
162Function declaration
163--------------------
164
165The name of the function to call within the state. A state declaration
166can contain only a single function declaration.
167
168For example, the following state declaration calls the :mod:`installed
169<salt.states.pkg.installed>` function in the ``pkg`` state module:
170
171.. code-block:: yaml
172
173    httpd:
174      pkg.installed: []
175
176The function can be declared inline with the state as a shortcut.
177The actual data structure is compiled to this form:
178
179.. code-block:: yaml
180
181    httpd:
182      pkg:
183        - installed
184
185Where the function is a string in the body of the state declaration.
186Technically when the function is declared in dot notation the compiler
187converts it to be a string in the state declaration list. Note that the
188use of the first example more than once in an ID declaration is invalid
189yaml.
190
191INVALID:
192
193.. code-block:: yaml
194
195    httpd:
196      pkg.installed
197      service.running
198
199When passing a function without arguments and another state declaration
200within a single ID declaration, then the long or "standard" format
201needs to be used since otherwise it does not represent a valid data
202structure.
203
204VALID:
205
206.. code-block:: yaml
207
208    httpd:
209      pkg.installed: []
210      service.running: []
211
212Occurs as the only index in the :ref:`state-declaration` list.
213
214.. _function-arg-declaration:
215
216Function arg declaration
217------------------------
218
219A single key dictionary referencing a Python type which is to be passed
220to the named :ref:`function-declaration` as a parameter. The type must
221be the data type expected by the function.
222
223Occurs under a :ref:`function-declaration`.
224
225For example in the following state declaration ``user``, ``group``, and
226``mode`` are passed as arguments to the :mod:`managed
227<salt.states.file.managed>` function in the ``file`` state module:
228
229.. code-block:: yaml
230
231    /etc/http/conf/http.conf:
232      file.managed:
233        - user: root
234        - group: root
235        - mode: 644
236
237.. _name-declaration:
238
239Name declaration
240----------------
241
242Overrides the ``name`` argument of a :ref:`state-declaration`. If
243``name`` is not specified the :ref:`ID-declaration` satisfies the
244``name`` argument.
245
246The name is always a single key dictionary referencing a string.
247
248Overriding ``name`` is useful for a variety of scenarios.
249
250For example, avoiding clashing ID declarations. The following two state
251declarations cannot both have ``/etc/motd`` as the ID declaration:
252
253.. code-block:: yaml
254
255    motd_perms:
256      file.managed:
257        - name: /etc/motd
258        - mode: 644
259
260    motd_quote:
261      file.append:
262        - name: /etc/motd
263        - text: "Of all smells, bread; of all tastes, salt."
264
265Another common reason to override ``name`` is if the ID declaration is long and
266needs to be referenced in multiple places. In the example below it is much
267easier to specify ``mywebsite`` than to specify
268``/etc/apache2/sites-available/mywebsite.com`` multiple times:
269
270.. code-block:: yaml
271
272    mywebsite:
273      file.managed:
274        - name: /etc/apache2/sites-available/mywebsite.com
275        - source: salt://mywebsite.com
276
277    a2ensite mywebsite.com:
278      cmd.wait:
279        - unless: test -L /etc/apache2/sites-enabled/mywebsite.com
280        - watch:
281          - file: mywebsite
282
283    apache2:
284      service.running:
285        - watch:
286          - file: mywebsite
287
288.. _names-declaration:
289
290Names declaration
291-----------------
292
293Expands the contents of the containing :ref:`state-declaration` into
294multiple state declarations, each with its own name.
295
296For example, given the following state declaration:
297
298.. code-block:: yaml
299
300    python-pkgs:
301      pkg.installed:
302        - names:
303          - python-django
304          - python-crypto
305          - python-yaml
306
307Once converted into the lowstate data structure the above state
308declaration will be expanded into the following three state declarations:
309
310.. code-block:: yaml
311
312      python-django:
313        pkg.installed
314
315      python-crypto:
316        pkg.installed
317
318      python-yaml:
319        pkg.installed
320
321Other values can be overridden during the expansion by providing an additional
322dictionary level.
323
324.. versionadded:: 2014.7.0
325
326.. code-block:: yaml
327
328  ius:
329    pkgrepo.managed:
330      - humanname: IUS Community Packages for Enterprise Linux 6 - $basearch
331      - gpgcheck: 1
332      - baseurl: http://mirror.rackspace.com/ius/stable/CentOS/6/$basearch
333      - gpgkey: http://dl.iuscommunity.org/pub/ius/IUS-COMMUNITY-GPG-KEY
334      - names:
335          - ius
336          - ius-devel:
337              - baseurl: http://mirror.rackspace.com/ius/development/CentOS/6/$basearch
338
339.. _states-highstate-example:
340
341Large example
342=============
343
344Here is the layout in yaml using the names of the highdata structure
345components.
346
347.. code-block:: yaml
348
349    <Include Declaration>:
350      - <Module Reference>
351      - <Module Reference>
352
353    <Extend Declaration>:
354      <ID Declaration>:
355        [<overrides>]
356
357
358    # standard declaration
359
360    <ID Declaration>:
361      <State Module>:
362        - <Function>
363        - <Function Arg>
364        - <Function Arg>
365        - <Function Arg>
366        - <Name>: <name>
367        - <Requisite Declaration>:
368          - <Requisite Reference>
369          - <Requisite Reference>
370
371
372    # inline function and names
373
374    <ID Declaration>:
375      <State Module>.<Function>:
376        - <Function Arg>
377        - <Function Arg>
378        - <Function Arg>
379        - <Names>:
380          - <name>
381          - <name>
382          - <name>
383        - <Requisite Declaration>:
384          - <Requisite Reference>
385          - <Requisite Reference>
386
387
388    # multiple states for single id
389
390    <ID Declaration>:
391      <State Module>:
392        - <Function>
393        - <Function Arg>
394        - <Name>: <name>
395        - <Requisite Declaration>:
396          - <Requisite Reference>
397      <State Module>:
398        - <Function>
399        - <Function Arg>
400        - <Names>:
401          - <name>
402          - <name>
403        - <Requisite Declaration>:
404          - <Requisite Reference>
405