salt.renderers.pydsl¶

A Python-based DSL

The pydsl renderer allows one to author salt formulas(.sls files) in pure Python using a DSL that's easy to write and easy to read. Here's an example:

1
2
3
4
5
6
7
8
9

 #!pydsl

 apache = state('apache')
 apache.pkg.installed()
 apache.service.running()
 state('/var/www/index.html') \
     .file('managed',
           source='salt://webserver/index.html') \
     .require(pkg='apache')

Notice that any Python code is allow in the file as it's really a Python module, so you have the full power of Python at your disposal. In this module, a few objects are defined for you, including the usual(with __ added) __salt__ dictionary, __grains__, __pillar__, __opts__, __env__, and __sls__, plus a few more:

__file__

local file system path to the sls module.

__pydsl__

Salt PyDSL object, useful for configuring DSL behavior per sls rendering.

include

Salt PyDSL function for creating include declaration's.

extend

Salt PyDSL function for creating extend declaration's.

state

Salt PyDSL function for creating ID declaration's.

A state ID declaration is created with a state(id) function call. Subsequent state(id) call with the same id returns the same object. This singleton access pattern applies to all declaration objects created with the DSL.

state('example')
assert state('example') is state('example')
assert state('example').cmd is state('example').cmd
assert state('example').cmd.running is state('example').cmd.running

The id argument is optional. If omitted, an UUID will be generated and used as the id.

state(id) returns an object under which you can create a state declaration object by accessing an attribute named after any state module available in Salt.

state('example').cmd
state('example').file
state('example').pkg
...

Then, a function declaration object can be created from a state declaration object by one of the following two ways:

1. by directly calling the attribute named for the state declaration, and supplying the state function name as the first argument.

state('example').file('managed', ...)

2. by calling a method named after the state function on the state declaration object.

state('example').file.managed(...)

With either way of creating a function declaration object, any function arg declaration's can be passed as keyword arguments to the call. Subsequent calls of a function declaration will update the arg declarations.

state('example').file('managed', source='salt://webserver/index.html')
state('example').file.managed(source='salt://webserver/index.html')

As a shortcut, the special name argument can also be passed as the first(second if calling using the first way) positional argument.

state('example').cmd('run', 'ls -la', cwd='/')
state('example').cmd.run('ls -la', cwd='/')

Finally, a requisite declaration object with its requisite reference's can be created by invoking one of the requisite methods(require, watch, use, require_in, watch_in, and use_in) on either a function declaration object or a state declaration object. The return value of a requisite call is also a function declaration object, so you can chain several requisite calls together.

Arguments to a requisite call can be a list of state declaration objects and/or a set of keyword arguments whose names are state modules and values are IDs of ID declaration's or names of name declaration's.

apache2 = state('apache2')
apache2.pkg.installed()
state('libapache2-mod-wsgi').pkg.installed()

# you can call requisites on function declaration
apache2.service.running() \
               .require(apache2.pkg,
                        pkg='libapache2-mod-wsgi') \
               .watch(file='/etc/apache2/httpd.conf')

# or you can call requisites on state declaration.
# this actually creates an anonymous function declaration object
# to add the requisites.
apache2.service.require(state('libapache2-mod-wsgi').pkg,
                        pkg='apache2') \
               .watch(file='/etc/apache2/httpd.conf')
 
# we still need to set the name of the function declaration.
apache2.service.running()

include declaration objects can be created with the include function, while extend declaration objects can be created with the extend function, whose arguments are just function declaration objects.

include('edit.vim', 'http.server')
extend(state('apache2').service.watch(file='/etc/httpd/httpd.conf')

The include function, by default, causes the included sls file to be rendered as soon as the include function is called. It returns a list of rendered module objects; sls files not rendered with the pydsl renderer return None's. This behavior creates no include declaration's in the resulting high state data structure.

import types

# including multiple sls returns a list.
_, mod = include('a-non-pydsl-sls', 'a-pydsl-sls')

assert _ is None
assert isinstance(slsmods[1], types.ModuleType)

# including a single sls returns a single object
mod = include('a-pydsl-sls')

# myfunc is a function that calls state(...) to create more states.
mod.myfunc(1, 2, "three")

Notice how you can define a reusable function in your pydsl sls module and then call it via the module returned by include.

It's still possible to do late includes by passing the delayed=True keyword argument to include.

include('edit.vim', 'http.server', delayed=True)

Above will just create a include declaration in the rendered result, and such call always returns None.

greeting = "hello world"
def helper(something, *args, **kws):
    print greeting                # hello world
    print something, args, kws    # test123 ['a', 'b', 'c'] {'x': 1, 'y': 2}
    
state().cmd.call(helper, "test123", 'a', 'b', 'c', x=1, y=2)

include('some.sls.file')

A = state('A').cmd.run(cwd='/var/tmp')
extend(A)

__pydsl__.set(ordered=True)

for i in range(10):
    i = str(i)
    state(i).cmd.run('echo '+i, cwd='/')
state('1').cmd.run('echo one')
state('2').cmd.run(name='echo two')

#!pydsl

s = state() # save for later invocation

# configure it
s.cmd.run('echo at render time', cwd='/')
s.file.managed('target.txt', source='salt://source.txt')

s() # execute the two states now

#!pydsl|stateconf -ps

include('xxx', 'yyy')

# ensure that states in xxx run BEFORE states in this file.
extend(state('.start').stateconf.require(stateconf='xxx::goal'))

# ensure that states in yyy run AFTER states in this file.
extend(state('.goal').stateconf.require_in(stateconf='yyy::start'))

__pydsl__.set(ordered=True)

...