Understanding Jinja¶

Including Context During Include/Import¶

By adding with context to the include/import directive, the current context can be passed to an included/imported template.

{% import 'openssl/vars.sls' as ssl with context %}

strftime¶

Converts any time related object into a time based string. It requires valid strftime directives. An exhaustive list can be found here in the Python documentation.

{% set curtime = None | strftime() %}

Fuzzy dates require the timelib Python module is installed.

{{ "2002/12/25"|strftime("%y") }}
{{ "1040814000"|strftime("%Y-%m-%d") }}
{{ datetime|strftime("%u") }}
{{ "tomorrow"|strftime }}

sequence¶

Ensure that parsed data is a sequence.

yaml_encode¶

Serializes a single object into a YAML scalar with any necessary handling for escaping special characters. This will work for any scalar YAML data type: ints, floats, timestamps, booleans, strings, unicode. It will not work for multi-objects such as sequences or maps.

{%- set bar = 7 %}
{%- set baz = none %}
{%- set zip = true %}
{%- set zap = 'The word of the day is "salty"' %}

{%- load_yaml as foo %}
bar: {{ bar|yaml_encode }}
baz: {{ baz|yaml_encode }}
zip: {{ zip|yaml_encode }}
zap: {{ zap|yaml_encode }}
{%- endload %}

In the above case {{ bar }} and {{ foo.bar }} should be identical and {{ baz }} and {{ foo.baz }} should be identical.

yaml_dquote¶

Serializes a string into a properly-escaped YAML double-quoted string. This is useful when the contents of a string are unknown and may contain quotes or unicode that needs to be preserved. The resulting string will be emitted with opening and closing double quotes.

{%- set bar = '"The quick brown fox . . ."' %}
{%- set baz = 'The word of the day is "salty".' %}

{%- load_yaml as foo %}
bar: {{ bar|yaml_dquote }}
baz: {{ baz|yaml_dquote }}
{%- endload %}

In the above case {{ bar }} and {{ foo.bar }} should be identical and {{ baz }} and {{ foo.baz }} should be identical. If variable contents are not guaranteed to be a string then it is better to use yaml_encode which handles all YAML scalar types.

yaml_squote¶

Similar to the yaml_dquote filter but with single quotes. Note that YAML only allows special escapes inside double quotes so yaml_squote is not nearly as useful (viz. you likely want to use yaml_encode or yaml_dquote).

to_bool¶

Returns the logical value of an element.

Example:

{{ 'yes' | to_bool }}
{{ 'true' | to_bool }}
{{ 1 | to_bool }}
{{ 'no' | to_bool }}

Will be rendered as:

True
True
True
False

exactly_n_true¶

Tests that exactly N items in an iterable are "truthy" (neither None, False, nor 0).

Example:

{{ ['yes', 0, False, 'True'] | exactly_n_true(2) }}

Returns:

True

exactly_one_true¶

Tests that exactly one item in an iterable is "truthy" (neither None, False, nor 0).

Example:

{{ ['yes', False, 0, None] | exactly_one_true }}

Returns:

True

quote¶

This text will be wrapped in quotes.

regex_search¶

Scan through string looking for a location where this regular expression produces a match. Returns None in case there were no matches found

Example:

{{ 'abcdefabcdef' | regex_search('BC(.*)', ignorecase=True) }}

Returns:

("defabcdef",)

regex_match¶

If zero or more characters at the beginning of string match this regular expression, otherwise returns None.

Example:

{{ 'abcdefabcdef' | regex_match('BC(.*)', ignorecase=True) }}

Returns:

None

regex_replace¶

Searches for a pattern and replaces with a sequence of characters.

Example:

{% set my_text = 'yes, this is a TEST' %}
{{ my_text | regex_replace(' ([a-z])', '__\\1', ignorecase=True) }}

Returns:

yes,__this__is__a__TEST

uuid¶

Return a UUID.

Example:

{{ 'random' | uuid }}

Returns:

3652b285-26ad-588e-a5dc-c2ee65edc804

is_list¶

Return if an object is list.

Example:

{{ [1, 2, 3] | is_list }}

Returns:

True

is_iter¶

Return if an object is iterable.

Example:

{{ [1, 2, 3] | is_iter }}

Returns:

True

min¶

Return the minimum value from a list.

Example:

{{ [1, 2, 3] | min }}

Returns:

1

max¶

Returns the maximum value from a list.

Example:

{{ [1, 2, 3] | max }}

Returns:

3

avg¶

Returns the average value of the elements of a list

Example:

{{ [1, 2, 3] | avg }}

Returns:

2

union¶

Return the union of two lists.

Example:

{{ [1, 2, 3] | union([2, 3, 4]) | join(', ') }}

Returns:

1, 2, 3, 4

intersect¶

Return the intersection of two lists.

Example:

{{ [1, 2, 3] | intersect([2, 3, 4]) | join(', ') }}

Returns:

2, 3

difference¶

Return the difference of two lists.

Example:

{{ [1, 2, 3] | difference([2, 3, 4]) | join(', ') }}

Returns:

1

symmetric_difference¶

Return the symmetric difference of two lists.

Example:

{{ [1, 2, 3] | symmetric_difference([2, 3, 4]) | join(', ') }}

Returns:

1, 4

method_call¶

Returns a result of object's method call.

Example #1:

{{ [1, 2, 1, 3, 4] | method_call('index', 1, 1, 3) }}

Returns:

2

This filter can be used with the map filter to apply object methods without using loop constructs or temporary variables.

Example #2:

{% set host_list = ['web01.example.com', 'db01.example.com'] %}
{% set host_list_split = [] %}
{% for item in host_list %}
  {% do host_list_split.append(item.split('.', 1)) %}
{% endfor %}
{{ host_list_split }}

Example #3:

{{ host_list|map('method_call', 'split', '.', 1)|list }}

Return of examples #2 and #3:

[[web01, example.com], [db01, example.com]]

is_sorted¶

Return True if an iterable object is already sorted.

Example:

{{ [1, 2, 3] | is_sorted }}

Returns:

True

compare_lists¶

Compare two lists and return a dictionary with the changes.

Example:

{{ [1, 2, 3] | compare_lists([1, 2, 4]) }}

Returns:

{"new": [4], "old": [3]}

compare_dicts¶

Compare two dictionaries and return a dictionary with the changes.

Example:

{{ {'a': 'b'} | compare_dicts({'a': 'c'}) }}

Returns:

{"a": {"new": "c", "old": "b"}}

is_hex¶

Return True if the value is hexadecimal.

Example:

{{ '0xabcd' | is_hex }}
{{ 'xyzt' | is_hex }}

Returns:

True
False

contains_whitespace¶

Return True if a text contains whitespaces.

Example:

{{ 'abcd' | contains_whitespace }}
{{ 'ab cd' | contains_whitespace }}

Returns:

False
True

substring_in_list¶

Return True if a substring is found in a list of string values.

Example:

{{ 'abcd' | substring_in_list(['this', 'is', 'an abcd example']) }}

Returns:

True

check_whitelist_blacklist¶

Check a whitelist and/or blacklist to see if the value matches it.

This filter can be used with either a whitelist or a blacklist individually, or a whitelist and a blacklist can be passed simultaneously.

If whitelist is used alone, value membership is checked against the whitelist only. If the value is found, the function returns True. Otherwise, it returns False.

If blacklist is used alone, value membership is checked against the blacklist only. If the value is found, the function returns False. Otherwise, it returns True.

If both a whitelist and a blacklist are provided, value membership in the blacklist will be examined first. If the value is not found in the blacklist, then the whitelist is checked. If the value isn't found in the whitelist, the function returns False.

Whitelist Example:

{{ 5 | check_whitelist_blacklist(whitelist=[5, 6, 7]) }}

Returns:

True

Blacklist Example:

{{ 5 | check_whitelist_blacklist(blacklist=[5, 6, 7]) }}

False

date_format¶

Converts unix timestamp into human-readable string.

Example:

{{ 1457456400 | date_format }}
{{ 1457456400 | date_format('%d.%m.%Y %H:%M') }}

Returns:

2017-03-08
08.03.2017 17:00

to_num¶

Converts a string to its numerical value.

Example:

{{ '5' | to_num }}

Returns:

5

to_bytes¶

Converts string-type object to bytes.

Example:

{{ 'wall of text' | to_bytes }}

json_encode_list¶

Recursively encodes all string elements of the list to bytes.

Example:

{{ [1, 2, 3] | json_encode_list }}

Returns:

[1, 2, 3]

json_encode_dict¶

Recursively encodes all string items in the dictionary to bytes.

Example:

Assuming that pillar['foo'] contains {u'a': u'\u0414'}, and your locale is en_US.UTF-8:

{{ pillar['foo'] | json_encode_dict }}

Returns:

{"a": "\xd0\x94"}

tojson¶

Dumps a data structure to JSON.

This filter was added to provide this functionality to hosts which have a Jinja release older than version 2.9 installed. If Jinja 2.9 or newer is installed, then the upstream version of the filter will be used. See the upstream docs for more information.

random_hash¶

Generates a random number between 1 and the number passed to the filter, and then hashes it. The default hash type is the one specified by the minion's hash_type config option, but an alternate hash type can be passed to the filter as an argument.

Example:

{% set num_range = 99999999 %}
{{ num_range | random_hash }}
{{ num_range | random_hash('sha512') }}

Returns:

43ec517d68b6edd3015b3edc9a11367b
d94a45acd81f8e3107d237dbc0d5d195f6a52a0d188bc0284c0763ece1eac9f9496fb6a531a296074c87b3540398dace1222b42e150e67c9301383fde3d66ae5

set_dict_key_value¶

..versionadded:: 3000

Allows you to set a value in a nested dictionary without having to worry if all the nested keys actually exist. Missing keys will be automatically created if they do not exist. The default delimiter for the keys is ':', however, with the delimiter-parameter, a different delimiter can be specified.

Examples:

Example 1:

{%- set foo = {} %} {{ foo | set_dict_key_value('bar:baz', 42) }}

Example 2:

{{ {} | set_dict_key_value('bar.baz.qux', 42, delimiter='.') }}

Returns:

Example 1:

{'bar': {'baz': 42}}

Example 2:

{'bar': {'baz': {'qux': 42}}}

append_dict_key_value¶

..versionadded:: 3000

Allows you to append to a list nested (deep) in a dictionary without having to worry if all the nested keys (or the list itself) actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is ':', however, with the delimiter-parameter, a different delimiter can be specified.

Examples:

Example 1:

{%- set foo = {'bar': {'baz': [1, 2]}} %} {{ foo | append_dict_key_value('bar:baz', 42) }}

Example 2:

{%- set foo = {} %} {{ foo | append_dict_key_value('bar:baz:qux', 42) }}

Returns:

Example 1:

{'bar': {'baz': [1, 2, 42]}}

Example 2:

{'bar': {'baz': {'qux': [42]}}}

extend_dict_key_value¶

..versionadded:: 3000

Allows you to extend a list nested (deep) in a dictionary without having to worry if all the nested keys (or the list itself) actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is ':', however, with the delimiter-parameter, a different delimiter can be specified.

Examples:

Example 1:

{%- set foo = {'bar': {'baz': [1, 2]}} %} {{ foo | extend_dict_key_value('bar:baz', [42, 42]) }}

Example 2:

{{ {} | extend_dict_key_value('bar:baz:qux', [42]) }}

Returns:

Example 1:

{'bar': {'baz': [1, 2, 42, 42]}}

Example 2:

{'bar': {'baz': {'qux': [42]}}}

update_dict_key_value¶

..versionadded:: 3000

Allows you to update a dictionary nested (deep) in another dictionary without having to worry if all the nested keys actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is ':', however, with the delimiter-parameter, a different delimiter can be specified.

Examples:

Example 1:

{%- set foo = {'bar': {'baz': {'qux': 1}}} %} {{ foo | update_dict_key_value('bar:baz', {'quux': 3}) }}

Example 2:

{{ {} | update_dict_key_value('bar:baz:qux', {'quux': 3}) }}

Example 1:

{'bar': {'baz': {'qux': 1, 'quux': 3}}}

Example 2:

{'bar': {'baz': {'qux': {'quux': 3}}}}

md5¶

Return the md5 digest of a string.

Example:

{{ 'random' | md5 }}

Returns:

7ddf32e17a6ac5ce04a8ecbf782ca509

sha256¶

Return the sha256 digest of a string.

Example:

{{ 'random' | sha256 }}

Returns:

a441b15fe9a3cf56661190a0b93b9dec7d04127288cc87250967cf3b52894d11

sha512¶

Return the sha512 digest of a string.

Example:

{{ 'random' | sha512 }}

Returns:

811a90e1c8e86c7b4c0eef5b2c0bf0ec1b19c4b1b5a242e6455be93787cb473cb7bc9b0fdeb960d00d5c6881c2094dd63c5c900ce9057255e2a4e271fc25fef1

base64_encode¶

Encode a string as base64.

Example:

{{ 'random' | base64_encode }}

Returns:

cmFuZG9t

base64_decode¶

Decode a base64-encoded string.

{{ 'Z2V0IHNhbHRlZA==' | base64_decode }}

Returns:

get salted

hmac¶

Verify a challenging hmac signature against a string / shared-secret. Returns a boolean value.

Example:

{{ 'get salted' | hmac('shared secret', 'eBWf9bstXg+NiP5AOwppB5HMvZiYMPzEM9W5YMm/AmQ=') }}

Returns:

True

http_query¶

Return the HTTP reply object from a URL.

Example:

{{ 'http://jsonplaceholder.typicode.com/posts/1' | http_query }}

Returns:

{
  'body': '{
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi option reprehenderit",
    "body": "quia et suscipit\\nsuscipit recusandae consequuntur expedita et cum\\nreprehenderit molestiae ut ut quas totam\\nnostrum rerum est autem sunt rem eveniet architecto"
  }'
}

traverse¶

Traverse a dict or list using a colon-delimited target string. The target 'foo:bar:0' will return data['foo']['bar'][0] if this value exists, and will otherwise return the provided default value.

Example:

{{ {'a1': {'b1': {'c1': 'foo'}}, 'a2': 'bar'} | traverse('a1:b1', 'default') }}

Returns:

{"c1": "foo"}

{{ {'a1': {'b1': {'c1': 'foo'}}, 'a2': 'bar'} | traverse('a2:b2', 'default') }}

Returns:

"default"

json_query¶

A port of Ansible json_query Jinja filter to make queries against JSON data using JMESPath language. Could be used to filter pillar data, yaml maps, and together with http_query. Depends on the jmespath Python module.

Examples:

Example 1: {{ [1, 2, 3, 4, [5, 6]] | json_query('[]') }}

Example 2: {{
{"machines": [
  {"name": "a", "state": "running"},
  {"name": "b", "state": "stopped"},
  {"name": "c", "state": "running"}
]} | json_query("machines[?state=='running'].name") }}

Example 3: {{
{"services": [
  {"name": "http", "host": "1.2.3.4", "port": 80},
  {"name": "smtp", "host": "1.2.3.5", "port": 25},
  {"name": "ssh",  "host": "1.2.3.6", "port": 22},
]} | json_query("services[].port") }}

Returns:

Example 1: [1, 2, 3, 4, 5, 6]

Example 2: ['a', 'c']

Example 3: [80, 25, 22]

to_snake_case¶

Converts a string from camelCase (or CamelCase) to snake_case.

Example: {{ camelsWillLoveThis | to_snake_case }}

Returns:

Example: camels_will_love_this

to_camelcase¶

Converts a string from snake_case to camelCase (or UpperCamelCase if so indicated).

Example 1: {{ snake_case_for_the_win | to_camelcase }}

Example 2: {{ snake_case_for_the_win | to_camelcase(uppercamel=True) }}

Returns:

Example 1: snakeCaseForTheWin
Example 2: SnakeCaseForTheWin

Networking Filters¶

The following networking-related filters are supported:

is_ip¶

Return if a string is a valid IP Address.

{{ '192.168.0.1' | is_ip }}

Additionally accepts the following options:

• global

• link-local

• loopback

• multicast

• private

• public

• reserved

• site-local

• unspecified

Example - test if a string is a valid loopback IP address.

{{ '192.168.0.1' | is_ip(options='loopback') }}

is_ipv4¶

Returns if a string is a valid IPv4 address. Supports the same options as is_ip.

{{ '192.168.0.1' | is_ipv4 }}

is_ipv6¶

Returns if a string is a valid IPv6 address. Supports the same options as is_ip.

{{ 'fe80::' | is_ipv6 }}

ipaddr¶

From a list, returns only valid IP entries. Supports the same options as is_ip. The list can contains also IP interfaces/networks.

Example:

{{ ['192.168.0.1', 'foo', 'bar', 'fe80::'] | ipaddr }}

Returns:

["192.168.0.1", "fe80::"]

ipv4¶

From a list, returns only valid IPv4 entries. Supports the same options as is_ip. The list can contains also IP interfaces/networks.

Example:

{{ ['192.168.0.1', 'foo', 'bar', 'fe80::'] | ipv4 }}

Returns:

["192.168.0.1"]

ipv6¶

From a list, returns only valid IPv6 entries. Supports the same options as is_ip. The list can contains also IP interfaces/networks.

Example:

{{ ['192.168.0.1', 'foo', 'bar', 'fe80::'] | ipv6 }}

Returns:

["fe80::"]

network_hosts¶

Return the list of hosts within a networks. This utility works for both IPv4 and IPv6.

Example:

{{ '192.168.0.1/30' | network_hosts }}

Returns:

["192.168.0.1", "192.168.0.2"]

network_size¶

Return the size of the network. This utility works for both IPv4 and IPv6.

Example:

{{ '192.168.0.1/8' | network_size }}

Returns:

16777216

gen_mac¶

Generates a MAC address with the defined OUI prefix.

Common prefixes:

• 00:16:3E -- Xen

• 00:18:51 -- OpenVZ

• 00:50:56 -- VMware (manually generated)

• 52:54:00 -- QEMU/KVM

• AC:DE:48 -- PRIVATE

Example:

{{ '00:50' | gen_mac }}

Returns:

00:50:71:52:1C

mac_str_to_bytes¶

Converts a string representing a valid MAC address to bytes.

Example:

{{ '00:11:22:33:44:55' | mac_str_to_bytes }}

dns_check¶

Return the ip resolved by dns, but do not exit on failure, only raise an exception. Obeys system preference for IPv4/6 address resolution.

Example:

{{ 'www.google.com' | dns_check(port=443) }}

Returns:

'172.217.3.196'

File filters¶

is_text_file¶

Return if a file is text.

Uses heuristics to guess whether the given file is text or binary, by reading a single block of bytes from the file. If more than 30% of the chars in the block are non-text, or there are NUL ('x00') bytes in the block, assume this is a binary file.

Example:

{{ '/etc/salt/master' | is_text_file }}

Returns:

True

is_binary_file¶

Return if a file is binary.

Detects if the file is a binary, returns bool. Returns True if the file is a bin, False if the file is not and None if the file is not available.

Example:

{{ '/etc/salt/master' | is_binary_file }}

Returns:

False

is_empty_file¶

Return if a file is empty.

Example:

{{ '/etc/salt/master' | is_empty_file }}

Returns:

False

file_hashsum¶

Return the hashsum of a file.

Example:

{{ '/etc/salt/master' | file_hashsum }}

Returns:

02d4ef135514934759634f10079653252c7ad594ea97bd385480c532bca0fdda

list_files¶

Return a recursive list of files under a specific path.

Example:

{{ '/etc/salt/' | list_files | join('\n') }}

Returns:

/etc/salt/master
/etc/salt/proxy
/etc/salt/minion
/etc/salt/pillar/top.sls
/etc/salt/pillar/device1.sls

path_join¶

Joins absolute paths.

Example:

{{ '/etc/salt/' | path_join('pillar', 'device1.sls') }}

Returns:

/etc/salt/pillar/device1.sls

which¶

Python clone of /usr/bin/which.

Example:

{{ 'salt-master' | which }}

Returns:

/usr/local/salt/virtualenv/bin/salt-master

equalto¶

Tests the equality between two values.

Can be used in an if statement directly:

{% if 1 is equalto(1) %}
    < statements >
{% endif %}

If clause evaluates to True

or with the selectattr filter:

{{ [{'value': 1}, {'value': 2} , {'value': 3}] | selectattr('value', 'equalto', 3) | list }}

Returns:

[{"value": 3}]

match¶

Tests that a string matches the regex passed as an argument.

Can be used in a if statement directly:

{% if 'a' is match('[a-b]') %}
    < statements >
{% endif %}

If clause evaluates to True

or with the selectattr filter:

{{ [{'value': 'a'}, {'value': 'b'}, {'value': 'c'}] | selectattr('value', 'match', '[b-e]') | list }}

Returns:

[{"value": "b"}, {"value": "c"}]

Test supports additional optional arguments: ignorecase, multiline

Escape filters¶

regex_escape¶

Allows escaping of strings so they can be interpreted literally by another function.

Example:

regex_escape = {{ 'https://example.com?foo=bar%20baz' | regex_escape }}

will be rendered as:

regex_escape = https\:\/\/example\.com\?foo\=bar\%20baz

Set Theory Filters¶

unique¶

Performs set math using Jinja filters.

Example:

unique = {{ ['foo', 'foo', 'bar'] | unique }}

will be rendered as:

unique = ['foo', 'bar']

Logs¶

Yes, in Salt, one is able to debug a complex Jinja template using the logs. For example, making the call:

{%- do salt.log.error('testing jinja logging') -%}

Will insert the following message in the minion logs:

2017-02-01 01:24:40,728 [salt.module.logmod][ERROR   ][3779] testing jinja logging