A state tree is a collection of
SLS files that live under the directory
file_roots. A state tree can be organized into
The main state file that instructs minions what environment and modules to use during state execution.
Defines a list of Module reference strings to include in this
Occurs only in the top level of the highstate structure.
include: - edit.vim - http.server
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
Defines an individual highstate component. Always references a value of a dictionary containing keys referencing State declaration and Requisite declaration. Can be overridden by a Name declaration or a Names declaration.
Occurs on the top level or under the 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.
In Salt versions earlier than 0.9.7, ID declarations containing dots would result in unpredictable highstate output.
Extends a 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
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
State declaration that is defined in another
SLS file. In the
following contrived example, the shown
mywebsite.sls file is
extend -ing the
apache.sls module in order to add a
declaration that will restart Apache whenever the Apache configuration file,
include: - apache extend: apache: service: - watch: - file: mywebsite mywebsite: file.managed: - name: /var/www/mysite
Occurs under an ID declaration.
A list containing requisite references.
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 single index in a Requisite declaration list.
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
installed function in the
pkg state module:
httpd: pkg.installed: 
The function can be declared inline with the state as a shortcut. The actual data structure is compiled to this form:
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.
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.
httpd: pkg.installed:  service.running: 
Occurs as the only index in the State declaration list.
A single key dictionary referencing a Python type which is to be passed to the named Function declaration as a parameter. The type must be the data type expected by the function.
Occurs under a Function declaration.
For example in the following state declaration
mode are passed as arguments to the
managed function in the
file state module:
/etc/http/conf/http.conf: file.managed: - user: root - group: root - mode: 644
The name is always a single key dictionary referencing a string.
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:
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:
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
Expands the contents of the containing State declaration into multiple state declarations, each with its own name.
For example, given the following state declaration:
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:
python-django: pkg.installed python-crypto: pkg.installed python-yaml: pkg.installed
Other values can be overridden during the expansion by providing an additional dictionary level.
New in version 2014.7.0.
ius: pkgrepo.managed: - humanname: IUS Community Packages for Enterprise Linux 6 - $basearch - gpgcheck: 1 - baseurl: http://mirror.rackspace.com/ius/stable/CentOS/6/$basearch - gpgkey: http://dl.iuscommunity.org/pub/ius/IUS-COMMUNITY-GPG-KEY - names: - ius - ius-devel: - baseurl: http://mirror.rackspace.com/ius/development/CentOS/6/$basearch
Here is the layout in yaml using the names of the highdata structure components.
<Include Declaration>: - <Module Reference> - <Module Reference> <Extend Declaration>: <ID Declaration>: [<overrides>] # standard declaration <ID Declaration>: <State Module>: - <Function> - <Function Arg> - <Function Arg> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> - <Requisite Reference> # inline function and names <ID Declaration>: <State Module>.<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 Module>: - <Function> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> <State Module>: - <Function> - <Function Arg> - <Names>: - <name> - <name> - <Requisite Declaration>: - <Requisite Reference>
These docs are for Salt's development version: fa4c1d7.
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2014.7.2