saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Renderer index re-write for clarity.

Browse source
This commit is contained in:
Mike Place 2014-02-19 13:55:34 -07:00
parent 7001c9dcc3
commit 6186eeab68
1 changed files with 58 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
doc/ref/renderers/index.rst
View file

@ -2,35 +2,41 @@
Renderers
=========
The Salt state system operates by gathering information from simple data
structures. The state system was designed in this way to make interacting with
it generic and simple. This also means that state files (SLS files) can be one
of many formats.
The Salt state system operates by gathering information from common data
types such as lists, dictionaries and strings that would be familiar
to any developer.
SLS files are translated from whatever data templating format they are written
in back into Python data types to be consumed by Salt.
By default SLS files are rendered as Jinja templates and then parsed as YAML
documents. But since the only thing the state system cares about is raw data,
the SLS files can be any structured format that can be dreamed up.
Currently there is support for ``Jinja + YAML``, ``Mako + YAML``,
``Wempy + YAML``, ``Jinja + json`` ``Mako + json`` and ``Wempy + json``. But
renderers can be written to support anything. This means that the Salt states
could be managed by XML files, HTML files, puppet files, or any format that
can be translated into the data structure used by the state system.
``Wempy + YAML``, ``Jinja + json`` ``Mako + json`` and ``Wempy + json``.
Renderers can be written to support any template type. This means that the
Salt states could be managed by XML files, HTML files, Puppet files, or any
format that can be translated into the Pythonic data structure used by the state
system.
Multiple Renderers
------------------
When deploying a state tree a default renderer is selected in the master
configuration file with the renderer option. But multiple renderers can be
used inside the same state tree.
A default renderer is selected in the master configuration file by providing
a value to the ``renderer`` key.
When rendering SLS files Salt checks for the presence of a Salt specific
shebang line. The shebang line syntax was chosen because it is familiar to
the target audience, the systems admin and systems engineer.
When evaluating an SLS, more than one renderer can be used.
When rendering SLS files, Salt checks for the presence of a Salt-specific
shebang line.
The shebang line directly calls the name of the renderer as it is specified
within Salt. One of the most common reasons to use multiple renderers in to
use the Python or ``py`` renderer:
within Salt. One of the most common reasons to use multiple renderers is to
use the Python or ``py`` renderer.
Below, the first line is a shebang that references the ``py`` renderer.
.. code-block:: python
@ -43,16 +49,17 @@ use the Python or ``py`` renderer:
return {'include': ['python'],
'python-mako': {'pkg': ['installed']}}
The first line is a shebang that references the ``py`` renderer.
Composing Renderers
-------------------
A renderer can be composed from other renderers by connecting them in a series
of pipes(``|``). In fact, the default ``Jinja + YAML`` renderer is implemented
by combining a YAML renderer and a Jinja renderer. Such renderer configuration
is specified as: ``jinja | yaml``.
of pipes(``|``).
Other renderer combinations are possible, here's a few examples:
In fact, the default ``Jinja + YAML`` renderer is implemented by connecting a YAML
renderer to a Jinja renderer. Such renderer configuration is specified as: ``jinja | yaml``.
Other renderer combinations are possible:
``yaml``
i.e, just YAML, no templating.
@ -65,7 +72,7 @@ Other renderer combinations are possible, here's a few examples:
This one allows you to use both jinja and mako templating syntax in the
input and then parse the final rendered output as YAML.
And here's a contrived example sls file using the ``jinja | mako | yaml`` renderer:
The following is a contrived example SLS file using the ``jinja | mako | yaml`` renderer:
.. code-block:: python
@ -81,33 +88,41 @@ And here's a contrived example sls file using the ``jinja | mako | yaml`` render
<%doc> ${...} is Mako's notation, and so is this comment. </%doc>
{# Similarly, {{...}} is Jinja's notation, and so is this comment. #}
For backward compatibility, ``jinja | yaml`` can also be written as
For backward compatibility, ``jinja | yaml`` can also be written as
``yaml_jinja``, and similarly, the ``yaml_mako``, ``yaml_wempy``,
``json_jinja``, ``json_mako``, and ``json_wempy`` renderers are all supported
as well.
``json_jinja``, ``json_mako``, and ``json_wempy`` renderers are all supported.
Keep in mind that not all renderers can be used alone or with any other renderers.
For example, the template renderers shouldn't be used alone as their outputs are
just strings, which still need to be parsed by another renderer to turn them into
highstate data structures. Also, for example, it doesn't make sense to specify
``yaml | jinja`` either, because the output of the yaml renderer is a highstate
data structure(a dict in Python), which cannot be used as the input to a template
renderer. Therefore, when combining renderers, you should know what each renderer
accepts as input and what it returns as output.
highstate data structures.
For example, it doesn't make sense to specify ``yaml | jinja`` because the
output of the YAML renderer is a highstate data structure (a dict in Python), which
cannot be used as the input to a template renderer. Therefore, when combining
renderers, you should know what each renderer accepts as input and what it returns
as output.
Writing Renderers
-----------------
Writing a renderer is easy, all that is required is that a Python module is
placed in the rendered directory and that the module implements the ``render``
function. The ``render`` function will be passed the path of the SLS file. In
the ``render`` function, parse the passed file and return the data structure
derived from the file. You can place your custom renderers in a ``_renderers``
directory within the :conf_master:`file_roots` specified by the master config
file. These custom renderers are distributed when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
A custom renderer must be a Python module placed in the rendered directory and the
module implement the ``render`` function.
The ``render`` function will be passed the path of the SLS file as an argument.
The purpose of of ``render`` function is to parse the passed file and to return
the Python data structure derived from the file.
Custom renderers must be placed in a ``_renderers`` directory within the
:conf_master:`file_roots` specified by the master config file.
Custom renderers are distributed when any of the following are run:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom renderers which have been synced to a minion, that are named the
same as one of Salt's default set of renderers, will take the place of the
@ -117,8 +132,9 @@ default renderer with the same name.
Examples
--------
The best place to find examples of renderers is in the Salt source code. The
renderers included with Salt can be found here:
The best place to find examples of renderers is in the Salt source code.
Documentation for renderers included with Salt can be found here:
:blob:`salt/renderers`