SLS Template Variable Reference#

Warning

In the 3005 release sls_path, tplfile, and tpldir have had some significant improvements which have the potential to break states that rely on old and broken functionality.

The template engines available to sls files and file templates come loaded with a number of context variables. These variables contain information and functions to assist in the generation of templates. See each variable below for its availability -- not all variables are available in all templating contexts.

Salt#

The salt variable is available to abstract the salt library functions. This variable is a python dictionary containing all of the functions available to the running salt minion. It is available in all salt templates.

{% for file in salt['cmd.run']('ls -1 /opt/to_remove').splitlines() %}
/opt/to_remove/{{ file }}:
  file.absent
{% endfor %}

Opts#

The opts variable abstracts the contents of the minion's configuration file directly to the template. The opts variable is a dictionary. It is available in all templates.

{{ opts['cachedir'] }}

The config.get function also searches for values in the opts dictionary.

Pillar#

The pillar dictionary can be referenced directly, and is available in all templates:

{{ pillar['key'] }}

Using the pillar.get function via the salt variable is generally recommended since a default can be safely set in the event that the value is not available in pillar and dictionaries can be traversed directly:

{{ salt['pillar.get']('key', 'failover_value') }}
{{ salt['pillar.get']('stuff:more:deeper') }}

Grains#

The grains dictionary makes the minion's grains directly available, and is available in all templates:

{{ grains['os'] }}

The grains.get function can be used to traverse deeper grains and set defaults:

{{ salt['grains.get']('os') }}

saltenv#

The saltenv variable is available in only in sls files when gathering the sls from an environment.

{{ saltenv }}

SLS Only Variables#

The following are only available when processing sls files. If you need these in other templates, you can usually pass them in as template context.

sls#

The sls variable contains the sls reference value, and is only available in the actual SLS file (not in any files referenced in that SLS). The sls reference value is the value used to include the sls in top files or via the include option.

{{ sls }}

slspath#

The slspath variable contains the path to the directory of the current sls file. The value of slspath in files referenced in the current sls depends on the reference method. For jinja includes slspath is the path to the current directory of the file. For salt includes slspath is the path to the directory of the included file. If current sls file is in root of the file roots, this will return ""

{{ slspath }}

When slspath and tpldir are populated#

slspath and tpldir are template render-time variables. They are injected by Salt's state compiler when the SLS template is rendered as a state file. As a result:

  • They are populated inside any SLS file that is being rendered as state data (top files, included SLS files, and the SLS being applied).

  • They are not populated inside templates that are rendered through file.managed or template: jinja for non-state files. In those contexts the template is rendered by the renderer subsystem, not by the state compiler, and the state-only template variables are not in scope. To get the SLS path inside a non-state template, pass it explicitly via defaults or context:

    configure-app:
  file.managed:
    - name: /etc/app.conf
    - source: salt://app/files/app.conf.j2
    - template: jinja
    - defaults:
        sls_dir: {{ slspath }}

    Inside app.conf.j2 the template can then use {{ sls_dir }}.

  • When using a Jinja {% include %} from within an SLS file, the included template inherits the current SLS render context, so slspath and tpldir continue to refer to the including SLS. When using Salt's include: directive at the top of an SLS file to pull in another SLS, each SLS sees its own slspath while it is being rendered.

sls_path#

A version of slspath with underscores as path separators instead of slashes. So, if slspath is path/to/state then sls_path is path_to_state

{{ sls_path }}

slsdotpath#

A version of slspath with dots as path separators instead of slashes. So, if slspath is path/to/state then slsdotpath is path.to.state. This is same as sls if sls points to a directory instead if a file.

{{ slsdotpath }}

slscolonpath#

A version of slspath with colons (:) as path separators instead of slashes. So, if slspath is path/to/state then slscolonpath is path:to:state.

{{ slscolonpath }}

tplpath#

Full path to sls template file being process on local disk. This is usually pointing to a copy of the sls file in a cache directory. This will be in OS specific format (Windows vs POSIX). (It is probably best not to use this.)

{{ tplpath }}

tplfile#

Relative path to exact sls template file being processed relative to file roots.

{{ tplfile }}

tpldir#

Directory, relative to file roots, of the current sls file. If current sls file is in root of the file roots, this will return ".". This is usually identical to slspath except in case of root-level sls, where this will return a ".".

A Common use case for this variable is to generate relative salt urls like:

my-file:
  file.managed:
    source: salt://{{ tpldir }}/files/my-template

tpldot#

A version of tpldir with dots as path separators instead of slashes. So, if tpldir is path/to/state then tpldot is path.to.state. NOTE: if tpldir is ., this will be set to ""

{{ tpldot }}