salt.renderers.jinja

Jinja loading utils to enable a more powerful backend for jinja templates

Important

Jinja supports a secure, sandboxed template execution environment that Salt takes advantage of. Other text Renderers do not support this functionality, so Salt highly recommends usage of jinja / jinja|yaml.

salt.renderers.jinja.render(template_file, saltenv='base', sls='', argline='', context=None, tmplpath=None, **kws)

Render the template_file, passing the functions and grains into the Jinja rendering system.

Return type:

string

class salt.utils.jinja.SerializerExtension(environment)

Yaml and Json manipulation.

Format filters

Allows jsonifying or yamlifying any data structure. For example, this dataset:

data = {
    'foo': True,
    'bar': 42,
    'baz': [1, 2, 3],
    'qux': 2.0
}

yaml = {{ data|yaml }}
json = {{ data|json }}
python = {{ data|python }}
xml  = {{ {'root_node': data}|xml }}

will be rendered as:

yaml = {bar: 42, baz: [1, 2, 3], foo: true, qux: 2.0}
json = {"baz": [1, 2, 3], "foo": true, "bar": 42, "qux": 2.0}
python = {'bar': 42, 'baz': [1, 2, 3], 'foo': True, 'qux': 2.0}
xml = """<<?xml version="1.0" ?>
         <root_node bar="42" foo="True" qux="2.0">
          <baz>1</baz>
          <baz>2</baz>
          <baz>3</baz>
         </root_node>"""

The yaml filter takes an optional flow_style parameter to control the default-flow-style parameter of the YAML dumper.

{{ data|yaml(False) }}

will be rendered as:

bar: 42
baz:
  - 1
  - 2
  - 3
foo: true
qux: 2.0

Load filters

Strings and variables can be deserialized with load_yaml and load_json tags and filters. It allows one to manipulate data directly in templates, easily:

{%- set yaml_src = "{foo: it works}"|load_yaml %}
{%- set json_src = '{"bar": "for real"}'|load_json %}
Dude, {{ yaml_src.foo }} {{ json_src.bar }}!

will be rendered as:

Dude, it works for real!

Load tags

Salt implements load_yaml and load_json tags. They work like the import tag, except that the document is also deserialized.

Syntaxes are {% load_yaml as [VARIABLE] %}[YOUR DATA]{% endload %} and {% load_json as [VARIABLE] %}[YOUR DATA]{% endload %}

For example:

{% load_yaml as yaml_src %}
    foo: it works
{% endload %}
{% load_json as json_src %}
    {
        "bar": "for real"
    }
{% endload %}
Dude, {{ yaml_src.foo }} {{ json_src.bar }}!

will be rendered as:

Dude, it works for real!

Import tags

External files can be imported and made available as a Jinja variable.

{% import_yaml "myfile.yml" as myfile %}
{% import_json "defaults.json" as defaults %}
{% import_text "completeworksofshakespeare.txt" as poems %}

Catalog

import_* and load_* tags will automatically expose their target variable to import. This feature makes catalog of data to handle.

for example:

# doc1.sls
{% load_yaml as var1 %}
    foo: it works
{% endload %}
{% load_yaml as var2 %}
    bar: for real
{% endload %}

# doc2.sls
{% from "doc1.sls" import var1, var2 as local2 %}
{{ var1.foo }} {{ local2.bar }}

** Escape Filters **

New in version 2017.7.0.

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

For 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 **

New in version 2017.7.0.

Performs set math using Jinja filters.

For example:

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

will be rendered as:

unique = ['foo', 'bar']

** Salt State Parameter Format Filters **

New in version 3005.

Renders a formatted multi-line YAML string from a Python dictionary. Each key/value pair in the dictionary will be added as a single-key dictionary to a list that will then be sent to the YAML formatter.

For example:

{% set thing_params = {
    "name": "thing",
    "changes": True,
    "warnings": "OMG! Stuff is happening!"
   }
%}

thing:
  test.configurable_test_state:
    {{ thing_params | dict_to_sls_yaml_params | indent }}

will be rendered as:

.. code-block:: yaml

thing:

test.configurable_test_state:

• name: thing

• changes: true

• warnings: OMG! Stuff is happening!