salt.modules.slsutil

Utility functions for use with or in SLS files

salt.modules.slsutil.deserialize(serializer, stream_or_string, **mod_kwargs)

Deserialize a Python object using a serializer module

CLI Example:

salt '*' slsutil.deserialize 'json' '{"foo": "Foo!"}'
salt '*' --no-parse=stream_or_string slsutil.deserialize 'json' \
    stream_or_string='{"foo": "Foo!"}'

Jinja Example:

{% set python_object = salt.slsutil.deserialize('json',
    '{"foo": "Foo!"}') %}
salt.modules.slsutil.merge(obj_a, obj_b, strategy='smart', renderer='yaml', merge_lists=False)

Merge a data structure into another by choosing a merge strategy

Strategies:

  • aggregate

  • list

  • overwrite

  • recurse

  • smart

CLI Example:

salt '*' slsutil.merge '{foo: Foo}' '{bar: Bar}'
salt.modules.slsutil.merge_all(lst, strategy='smart', renderer='yaml', merge_lists=False)

New in version 2019.2.0.

Merge a list of objects into each other in order

Parameters
  • lst (Iterable) -- List of objects to be merged.

  • strategy (String) -- Merge strategy. See utils.dictupdate.

  • renderer (String) -- Renderer type. Used to determine strategy when strategy is 'smart'.

  • merge_lists (Bool) -- Defines whether to merge embedded object lists.

CLI Example:

$ salt-call --output=txt slsutil.merge_all '[{foo: Foo}, {foo: Bar}]'
local: {u'foo': u'Bar'}
salt.modules.slsutil.renderer(path=None, string=None, default_renderer='jinja|yaml', **kwargs)

Parse a string or file through Salt's renderer system

Changed in version 2018.3.0: Add support for Salt fileserver URIs.

This is an open-ended function and can be used for a variety of tasks. It makes use of Salt's "renderer pipes" system to run a string or file through a pipe of any of the loaded renderer modules.

Parameters
  • path -- The path to a file on Salt's fileserver (any URIs supported by cp.get_url) or on the local file system.

  • string -- An inline string to be used as the file to send through the renderer system. Note, not all renderer modules can work with strings; the 'py' renderer requires a file, for example.

  • default_renderer -- The renderer pipe to send the file through; this is overridden by a "she-bang" at the top of the file.

  • kwargs -- Keyword args to pass to Salt's compile_template() function.

Keep in mind the goal of each renderer when choosing a render-pipe; for example, the Jinja renderer processes a text file and produces a string, however the YAML renderer processes a text file and produces a data structure.

One possible use is to allow writing "map files", as are commonly seen in Salt formulas, but without tying the renderer of the map file to the renderer used in the other sls files. In other words, a map file could use the Python renderer and still be included and used by an sls file that uses the default 'jinja|yaml' renderer.

For example, the two following map files produce identical results but one is written using the normal 'jinja|yaml' and the other is using 'py':

#!jinja|yaml
{% set apache = salt.grains.filter_by({
    ...normal jinja map file here...
}, merge=salt.pillar.get('apache:lookup')) %}
{{ apache | yaml() }}
#!py
def run():
    apache = __salt__.grains.filter_by({
        ...normal map here but as a python dict...
    }, merge=__salt__.pillar.get('apache:lookup'))
    return apache

Regardless of which of the above map files is used, it can be accessed from any other sls file by calling this function. The following is a usage example in Jinja:

{% set apache = salt.slsutil.renderer('map.sls') %}

CLI Example:

salt '*' slsutil.renderer salt://path/to/file
salt '*' slsutil.renderer /path/to/file
salt '*' slsutil.renderer /path/to/file.jinja 'jinja'
salt '*' slsutil.renderer /path/to/file.sls 'jinja|yaml'
salt '*' slsutil.renderer string='Inline template! {{ saltenv }}'
salt '*' slsutil.renderer string='Hello, {{ name }}.' name='world'
salt.modules.slsutil.serialize(serializer, obj, **mod_kwargs)

Serialize a Python object using a serializer module

CLI Example:

salt '*' --no-parse=obj slsutil.serialize 'json' obj="{'foo': 'Foo!'}

Jinja Example:

{% set json_string = salt.slsutil.serialize('json',
    {'foo': 'Foo!'}) %}
salt.modules.slsutil.update(dest, upd, recursive_update=True, merge_lists=False)

Merge upd recursively into dest

If merge_lists=True, will aggregate list object types instead of replacing. This behavior is only activated when recursive_update=True.

CLI Example:

salt '*' slsutil.update '{foo: Foo}' '{bar: Bar}'