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