salt.modules.slsutil¶

Utility functions for use with or in SLS files

salt.modules.slsutil.banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=None, title=None, text=None, newline=False)¶

Create a standardized comment block to include in a templated file.

A common technique in configuration management is to include a comment block in managed files, warning users not to modify the file. This function simplifies and standardizes those comment blocks.

Parameters:

width -- The width, in characters, of the banner. Default is 72. commentchar -- The character to be used in the starting position of each line. This value should be set to a valid line comment character for the syntax of the file in which the banner is being inserted. Multiple character sequences, like '//' are supported. If the file's syntax does not support line comments (such as XML), use the blockstart and blockend options. borderchar -- The character to use in the top and bottom border of the comment box. Must be a single character. blockstart -- The character sequence to use at the beginning of a block comment. Should be used in conjunction with blockend blockend -- The character sequence to use at the end of a block comment. Should be used in conjunction with blockstart title -- The first field of the comment block. This field appears centered at the top of the box. text -- The second filed of the comment block. This field appears left-justified at the bottom of the box. newline -- Boolean value to indicate whether the comment block should end with a newline. Default is False.

Example 1 - the default banner:

{{ salt['slsutil.banner']() }}

########################################################################
#                                                                      #
#              THIS FILE IS MANAGED BY SALT - DO NOT EDIT              #
#                                                                      #
# The contents of this file are managed by Salt. Any changes to this   #
# file may be overwritten automatically and without warning.           #
########################################################################

Example 2 - a Javadoc-style banner:

{{ salt['slsutil.banner'](commentchar=' *', borderchar='*', blockstart='/**', blockend=' */') }}

/**
 ***********************************************************************
 *                                                                     *
 *              THIS FILE IS MANAGED BY SALT - DO NOT EDIT             *
 *                                                                     *
 * The contents of this file are managed by Salt. Any changes to this  *
 * file may be overwritten automatically and without warning.          *
 ***********************************************************************
 */

Example 3 - custom text:

{{ set copyright='This file may not be copied or distributed without permission of SaltStack, Inc.' }}
{{ salt['slsutil.banner'](title='Copyright 2019 SaltStack, Inc.', text=copyright, width=60) }}

############################################################
#                                                          #
#              Copyright 2019 SaltStack, Inc.              #
#                                                          #
# This file may not be copied or distributed without       #
# permission of SaltStack, Inc.                            #
############################################################

salt.modules.slsutil.boolstr(value, true='true', false='false')¶

Convert a boolean value into a string. This function is intended to be used from within file templates to provide an easy way to take boolean values stored in Pillars or Grains, and write them out in the appropriate syntax for a particular file template.

Parameters:	value -- The boolean value to be converted true -- The value to return if value is True false -- The value to return if value is False

In this example, a pillar named smtp:encrypted stores a boolean value, but the template that uses that value needs yes or no to be written, based on the boolean value.

Note: this is written on two lines for clarity. The same result could be achieved in one line.

{% set encrypted = salt[pillar.get]('smtp:encrypted', false) %}
use_tls: {{ salt['slsutil.boolstr'](encrypted, 'yes', 'no') }}

Result (assuming the value is True):

use_tls: yes

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

Deserialize a Python object using one of the available serializer modules.

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.dir_exists(path, saltenv='base')¶

Return True if a directory exists in the state tree, False otherwise.

Parameters:	path (str) -- The fully qualified path to a directory in the state tree. saltenv (str) -- The fileserver environment to search. Default: base

New in version 3004.

CLI Example:

salt '*' slsutil.dir_exists nginx/files

salt.modules.slsutil.file_exists(path, saltenv='base')¶

Return True if a file exists in the state tree, False otherwise.

New in version 3004.

Parameters:	path (str) -- The fully qualified path to a file in the state tree. saltenv (str) -- The fileserver environment to search. Default: base

CLI Example:

salt '*' slsutil.file_exists nginx/defaults.yaml

salt.modules.slsutil.findup(startpath, filenames, saltenv='base')¶

Find the first path matching a filename or list of filenames in a specified directory or the nearest ancestor directory. Returns the full path to the first file found.

New in version 3004.

Parameters:	startpath (str) -- The fileserver path from which to begin the search. An empty string refers to the state tree root. filenames -- A filename or list of filenames to search for. Searching for directory names is also supported. saltenv (str) -- The fileserver environment to search. Default: base

Example: return the path to defaults.yaml, walking up the tree from the state file currently being processed.

{{ salt["slsutil.findup"](tplfile, "defaults.yaml") }}

CLI Example:

salt '*' slsutil.findup formulas/shared/nginx map.jinja

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.path_exists(path, saltenv='base')¶

Return True if a path exists in the state tree, False otherwise. The path could refer to a file or directory.

New in version 3004.

Parameters:	path (str) -- The fully qualified path to a file or directory in the state tree. saltenv (str) -- The fileserver environment to search. Default: base

CLI Example:

salt '*' slsutil.path_exists nginx/defaults.yaml

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 default_renderer='jinja'
salt '*' slsutil.renderer /path/to/file.sls default_renderer='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 one of the available serializer modules.

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}'