You are viewing docs from the master branch, some of these features are not yet released.

Salt Extend¶

salt-extend is a templating tool for extending SaltStack. If you're looking to add a module to SaltStack, then the salt-extend utility can guide you through the process.

You can use Salt Extend to quickly create templated modules for adding new behaviours to some of the module subsystems within Salt.

Salt Extend takes a template directory and merges it into a SaltStack source code directory.

Command line usage¶

See salt-extend

Choosing a template¶

The following templates are available:

module¶

Creates a new execution module within salt/modules/{{module_name}}.py

module_unit¶

Creates a new execution module unit test suite within tests/unit/modules/test_{{module_name}}.py

state¶

Creates a new state module within salt/states/{{module_name}}.py

state_unit¶

Creates a new state module unit test suite within tests/unit/states/test_{{module_name}}.py

Adding templates¶

Create a directory under <src>/templates
Create a file template.yml containing properties for

description - a description of the template

questions - a collection of additional questions to ask the user, the name of the item will be used as the key in the context dictionary within the jinja template.

question - The question to ask the user, as a string

default - (optional) the default value, can contain Jinja2 template syntax and has access to the default context properties

Example template.yml¶

description: "Execution module"
questions:
    depending_libraries:
        question: "What libraries does this module depend upon?"
    virtual_name:
        question: "What module virtual name to use?"
        default: "{{module_name}}"

Create the files within <src>/templates/<your template> to match the target

Note

File names can contain Jinja 2 template syntax, e.g. '{{module_name}}.py}}'

Example file in the template directory¶

print("Hello {{module_name}}")
__virtual__ = "{{__virtual_name__}}"

Default context properties¶

The default context provides the following properties

description - A description of the template
short_description - A short description of the module as entered by the user
version - The version name of the next release
module_name - The module name as entered by the user
release_date - The current date in the format YYYY-MM-DD
year - The current year in the format YYYY

As well as any additional properties entered from the questions section of template.yml

API¶

salt.utils.extend module¶

SaltStack Extend¶

A templating tool for extending SaltStack.

Takes a template directory and merges it into a SaltStack source code directory. This tool uses Jinja2 for templating.

This tool is accessed using salt-extend

codeauthor:

Anthony Shaw <anthonyshaw@apache.org>

salt.utils.extend.apply_template(template_dir, output_dir, context)¶

Apply the template from the template directory to the output using the supplied context dict.

Parameters:

src (str) -- The source path
dst (str) -- The destination path
context (dict) -- The dictionary to inject into the Jinja template as context

salt.utils.extend.run(extension=None, name=None, description=None, salt_dir=None, merge=False, temp_dir=None)¶

A template factory for extending the salt ecosystem

Parameters:

extension (str) -- The extension type, e.g. 'module', 'state', if omitted, user will be prompted
name (str) -- Python-friendly name for the module, if omitted, user will be prompted
description (str) -- A description of the extension, if omitted, user will be prompted
salt_dir (str) -- The targeted Salt source directory
merge (bool) -- Merge with salt directory, False to keep separate, True to merge trees.
temp_dir (str) -- The directory for generated code, if omitted, system temp will be used