SLS file trees

There are a few subsystems in Salt that use an SLS file tree. The most common one of course is /srv/salt/, which is used for Salt states. Right after states are pillars (/srv/pillar/), which use a different file format but the same directory structure. Let's take a moment to talk about how these directories are put together.

SLS files

SLS stands for Salt State, which was the first type of file inside Salt to use this kind of file structure. While SLS files can be rendered in a number of different formats, by far the widest use is the default, YAML. Various templating engines are also available to help form the YAML (or other data structure) and again, the most popular is the default, Jinja.

Keep in mind that Salt is all about data. YAML is a serialization format that in Python, represents a data structure in a dictionary format. When thinking about how SLS files are designed, remember that they are a key/value pair: each item has a unique key, which is used to refer to a value. The value can in turn contain a single item, a list of items, or another set of key/value pairs.

The key to a stanza in an SLS file is called an ID. If no name inside the stanza is explicitly declared, the ID is copied to the name. Remember that IDs must be globally unique; duplicate IDs will cause errors.

Tying things together with top files

Both the state and the pillar system use a file called top.sls to pull the SLS files together and serve them to the appropriate minions, in the appropriate environments.

Each key in a top.sls file defines an environment. Typically, a base environment is defined, which includes all the minions in the infrastructure. Then other environments are defined that contain only a subset of the minions. Each environment includes a list of the SLS files that are to be included. Take the following top.sls file:

base: 
  '*': 
    - common 
    - vim 
qa: 
  '*_qa': 
    - jenkins 
web: 
  'web_*': 
    - apache2 

With this top.sls, three environments have been declared: base, qa, and web. The base environment will execute the common and vim states across all minions. The qa environment will execute the jenkins state across all the minions whose ID ends with _qa. The web environment will execute the apache2 state across all the minions whose ID starts with web_.

Organizing the SLS directories

SLS files may be named either as an SLS file themselves (that is, apache2.sls) or as an init.sls file inside a directory with the SLS name (that is, apache2/init.sls).

Note

Note that apache2.sls will be searched for first; if it is not there, then apache2/init.sls will be used.

SLS files may be hierarchical, and there is no imposed limit on how deep directories may go. When defining deeper directory structures, each level is appended to the SLS name with a period (that is, apache2/ssl/init.sls becomes apache2.ssl). It is considered best practice by developers to keep a directory more shallow; don't make your users search through your SLS tree to find things.