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.

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_.

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).

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.

In a large SLS tree, it often becomes reasonable to have SLS files include other SLS files. This is done using an include block, which usually appears at the top of an SLS file:

include: 
  - base 
  - emacs 

In this example, the SLS file in question will replace the include block with the contents of base.sls (or base/init.sls) and emacs.sls (or emacs/init.sls). This imposes some important restrictions on the user. Most importantly, the SLS files that are included may not contain IDs that already exist in the SLS file that includes them.

It is also important to remember that include itself, being a top-level declaration, cannot exist twice in the same file. The following is invalid:

include: 
  - base 
include: 
  - emacs 

State SLS files are unique among configuration management formats in that they are both declarative and imperative. They are imperative, as each state will be evaluated in the order in which it appears in the SLS file. They are also declarative because states may include requisites that change the order in which they are actually executed. For instance:

web_service: 
  service.running: 
    - name: apache2 
    - require: 
      - pkg: web_package 
web_package: 
  pkg.installed: 
    - name: apache2 

If a service is declared, which requires a package that appears after it in the SLS file, the pkg states will be executed first. However, if no requirements are declared, Salt will attempt to start the service before installing the package, because its codeblock appears before the pkg codeblock. The following will require two executions to complete properly:

web_service: 
  service.running: 
    - name: apache2 
web_package: 
  pkg.installed: 
    - name: apache2 

Requisites point to a list of items elsewhere in the SLS file that affect the behavior of the state. Each item in the list contains two components: the name of the module and the ID of the state being referenced.

The following requisites are available inside Salt states and other areas of Salt that use the state compiler.

apache2: 
  pkg: 
    - installed 
    - require 
      - file: apache2 
  service: 
    - running 
    - require: 
      - pkg: apache2 
  file: 
    - managed 
    - name: /etc/apache2/apache2.conf 
    - source: salt://apache2/apache2.conf 

apache2: 
  ...SNIP... 
  service: 
    - running 
    - require: 
      - pkg: apache2 
    - watch: 
      - file: apache2 
  ...SNIP... 

apache2: 
  service: 
    - running 
    - onfail 
      - pagerduty: apache_failure 

apache2_conf: 
  file: 
    - managed 
    - name: /etc/apache2/apache2.conf 
    - user: root 
    - group: root 
    - mode: 755 
    - watch_in: 
      - service: apache2 
mysql_conf: 
file: 
  - managed 
    - name: /etc/mysql/my.cnf 
    - use: 
      - file: apache2_conf 
    - watch_in: 
      - service: mysql 

There are some situations in which a state does not need to run, unless another state is expected to make changes. For example, consider a web application that makes use of Apache. When the codebase on a production server changes, Apache should be turned off, so as to avoid errors with the code that has not yet finished being installed.

The prereq requisite was designed exactly for this kind of use. When a state makes use of prereq, Salt will first perform a test run of the state to see if the items referred to in the prereq are expected to make changes. If so, then Salt will flag the state with the prereq as needing to execute.

apache2: 
  service: 
    - running 
    - watch: 
      - file: codebase 
codebase: 
  file: 
    - recurse 
...SNIP... 
shutdown_apache: 
  service: 
    - dead 
    - name: apache2 
    - prereq: 
      - file: codebase 

In the preceding example, the shutdown_apache state will only make changes if the codebase state reports that changes need to be made. If they do, then Apache will shutdown, and then the codebase state will execute. Once it is finished, it will trigger the apache2 service state, which will start up Apache again.

Each of the aforementioned requisites can be used inversely, by adding _in at the end. For instance, rather than state X requiring state Y, an SLS can be written so that state X declares that it is required by state Y, as follows:

apache2: 
  pkg: 
    - installed 
    - require_in: 
      - service: apache2 
  service: 
    - running 

It may seem silly to add inverses of each of the states but there is in fact a very good use case for doing so: include blocks.

SLS files cannot use requisites that point to a code that does not exist inside them. However, using an include block will cause the contents of other SLS files to appear inside the SLS file. Therefore, generic (but valid) configuration can be defined in one SLS file, included in another, and modified to be more specific with a use_in requisite.

In addition to an include block, state SLS files can also contain an extend block that modifies SLS files that appear in the include block. Using an extend block is similar to a use requisite, but there are some important differences.

Whereas a use or use_in requisite will copy defaults to or from another state, the extend block will only modify the state that has been extended.

# cat /srv/generic_apache/init.sls 
apache2_conf: 
  file: 
  - managed 
    - name: /etc/apache2/apache2.conf 
    - source: salt://apache2/apache2.conf 
(In django_server/init.sls) 
include: 
- generic_apache 
extend: 
  apache2_conf: 
    file: 
    - source: salt://django/apache2.conf 
(In image_server/init.sls) 
include: 
  - generic_apache 
extend: 
  apache2_conf: 
    file: 
      - source: salt://django/apache2.conf 

The preceding example makes use of a generic Apache configuration file, which will be overridden as appropriate for either a Django server or a web server that is only serving images.

Grains were originally designed to describe the static components of a minion, so that execution modules could detect how to behave appropriately. For instance, minions which contain the Debian os_family grain are likely to use the apt suite of tools for package management. Minions which contain the RedHat os_family grain are likely to use yum for package management.

A number of grains will automatically be discovered by Salt. Grains such as os, os_family, saltversion, and pythonversion are likely to be always available. Grains such as shell, systemd, and ps are not likely to be available on, for instance, Windows minions.

Grains are loaded when the minion process starts up, and then cached in memory. This improves minion performance, because the Salt-minion process doesn't need to rescan the system for every operation. This is critical to Salt, because it is designed to execute tasks immediately, and not wait several seconds on each execution.

To discover which grains are set on a minion, use the grains.items function:

salt myminion grains.items

To look at only a specific grain, pass its name as an argument to grains.item:

salt myminion grains.item os_family

Custom grains can be defined as well. Previously, static grains were defined in the minion configuration file (/etc/salt/minion on Linux and some Unix platforms):

grains: 
  foo: bar 
  baz: qux 

However, while this is still possible, it has fallen out of favor. It is now more common to define static grains in a file called grains (/etc/salt/grains on Linux and some Unix platforms). Using this file has some advantages:

That second point is important: whereas the minion configuration file is designed to accommodate user comments, the grains file is designed to be rewritten by Salt as necessary. Hand-editing the grains file is fine, but don't expect any comments to be preserved. Other than not including the grains top-level declaration, the grains file looks like the grains configuration in the minion file:

foo: bar 
baz: qux 

To add or modify a grain in the grains file, use the grains.setval function:

salt myminion grains.setval mygrain 'This is the content of mygrain'

Grains can contain a number of different types of values. Most grains contain only strings, but lists are also possible:

my_items: 
  - item1 
  - item2 

In order to add an item to this list, use the grains.append function:

salt myminion grains.append my_items item3

In order to remove a grain from the grains file, use the grains.delval function:

salt myminion grains.delval my_items

In most instances, pillars behave in much the same way as grains, with one important difference: they are defined on the master, typically in a centralized location. By default, this is the /srv/pillar/ directory on Linux machines. Because one location contains information for multiple minions, there must be a way to target that information to the minions. Because of this, SLS files are used.

The top.sls file for pillars is identical in configuration and function to the top.sls file for states: first an environment is declared, then a target, then a list of SLS files that will be applied to that target:

base: 
  '*': 
    - bash 

Pillar SLS files are much simpler than state SLS files, because they serve only as a static data store. They define key/value pairs, which may also be hierarchical.

skel_dir: /etc/skel/ 
role: web 
web_content: 
  images: 
    - jpg 
    - png 
    - gif 
  scripts: 
    - css 
    - js 

Like state SLS files, pillar SLS files may also include other pillar SLS files.

include: 
  - users 

To view all pillar data, use the pillar.items function:

salt myminion pillar.items

Take note that in older versions of Salt, when running this command, by default the master's configuration data will appear as a pillar item called master. This can cause problems if the master configuration includes sensitive data. To disable this output, add the following line to the master configuration:

pillar_opts: False 

Fortunately, this option defaults to False as of Salt version 2015.5.0. This is also a good time to mention that, outside the master configuration data, pillars are only viewable to the minion or minions to which they are targeted. In other words, no minion is allowed to access another minion's pillar data, at least by default. It is possible to allow a minion to perform master commands using the peer system, but that is outside the scope of this chapter.

Salt is able to use templates, which take advantage of grains and pillars, to make the state system more dynamic. A number of other templating engines are also available, including (as of version 2016.3) the following:

These are made available via Salt's rendering system. The preceding list only contains renderers that are typically used as templates to create configuration files and the like. Other renderers are available as well, but are designed more to describe data structures:

Finally, the following Renderer can decrypt GPG data stored on the master, before passing it through another renderer:

By default, state SLS files will be sent through the Jinja renderer, and then the yaml renderer. There are two ways to switch an SLS file to another renderer. First, if only one SLS file needs to be rendered differently, the first line of the file can contain a shabang line that specifies the renderer:

#!py 

The shabang can also specify multiple Renderers, separated by pipes, in the order in which they are to be used. This is known as a render pipe. To use Mako and JSON instead of Jinja and YAML, use:

#!mako|json 

To change the system default, set the renderer option in the master configuration file. The default is:

renderer: yaml_jinja 

It is also possible to specify the templating engine to be used on a file that created the minion using the file.managed state:

apache2_conf: 
  file: 
    - managed 
    - name: /etc/apache2/apache2.conf 
    - source: salt://apache2/apache2.conf 
    - template: jinja 

Because Jinja is by far the most commonly-used templating engine in Salt, we will focus on it here. Jinja is not hard to learn, and a few basics will go a long way.

Variables can be referred to by enclosing them in double-braces. Assuming a grain is set called user, the following will access it:

The user {{ grains['user'] }} is referred to here. 

Pillars can be accessed in the same way:

The user {{ pillar['user'] }} is referred to here. 

However, if the user pillar or grain is not set, the template will not render properly. A safer method is to use the salt built-in to cross-call an execution module:

The user {{ salt['grains.get']('user', 'larry') }} is referred to here. 
The user {{ salt['pillar.get']('user', 'larry') }} is referred to here. 

In both of these examples, if the user has not been set, then larry will be used as the default.

We can also make our templates more dynamic by having them search through grains and pillars for us. Using the config.get function, Salt will first look inside the minion's configuration. If it does not find the requested variable there, it will check the grains. Then it will search pillar. If it can't find it there, it will look inside the master configuration. If all else fails, it will use the default provided.

The user {{ salt['config.get']('user', 'larry') }} is referred to here. 

Codeblocks are enclosed within braces and percent signs. To set a variable that is local to a template (that is, not available via config.get), use the set keyword:

{% set myvar = 'My Value' %} 

Because Jinja is based on Python, most Python data types are available. For instance, lists and dictionaries:

{% set mylist = ['apples', 'oranges', 'bananas'] %} 
{% set mydict = {'favorite pie': 'key lime', 'favorite cake': 'saccher torte'} %} 

Jinja also offers logic that can help define which parts of a template are used, and how. Conditionals are performed using if blocks. Consider the following example:

{% if grains['os_family'] == 'Debian' %} 
apache2: 
{% elif grains['os_family'] == 'RedHat' %} 
httpd: 
{% endif %} 
  pkg: 
    - installed 
  service: 
    - running 

The Apache package is called apache2 on Debian-style systems, and httpd on RedHat-style systems. However, everything else in the state is the same. This template will auto-detect the type of system that it is on, install the appropriate package, and start the appropriate service.

Loops can be performed using for blocks, as follows:

{% set berries = ['blue', 'rasp', 'straw'] %} 
{% for berry in berries %} 
{{ berry }}berry 
{% endfor %}