diff --git a/doc/ref/auth/all/index.rst b/doc/ref/auth/all/index.rst index ba2f6f803c95..f12d6f28bff5 100644 --- a/doc/ref/auth/all/index.rst +++ b/doc/ref/auth/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.auth: -================================= -Full list of builtin auth modules -================================= +============ +auth modules +============ .. currentmodule:: salt.auth diff --git a/doc/ref/beacons/all/index.rst b/doc/ref/beacons/all/index.rst index e985d9f3fa9e..f1913c839807 100644 --- a/doc/ref/beacons/all/index.rst +++ b/doc/ref/beacons/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.beacons: -=================================== -Full list of builtin beacon modules -=================================== +============== +beacon modules +============== .. currentmodule:: salt.beacons diff --git a/doc/ref/engines/all/index.rst b/doc/ref/engines/all/index.rst index 40ac114b96d9..5da2cacab785 100644 --- a/doc/ref/engines/all/index.rst +++ b/doc/ref/engines/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.engines: -=================================== -Full list of builtin engine modules -=================================== +============== +engine modules +============== .. currentmodule:: salt.engines diff --git a/doc/ref/file_server/all/index.rst b/doc/ref/file_server/all/index.rst index 3ce9ea90a572..c6c13e291bc3 100644 --- a/doc/ref/file_server/all/index.rst +++ b/doc/ref/file_server/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.fileserver: -======================================= -Full list of builtin fileserver modules -======================================= +================== +fileserver modules +================== .. currentmodule:: salt.fileserver diff --git a/doc/ref/grains/all/index.rst b/doc/ref/grains/all/index.rst index abe957a7674a..1a14baa3cbd5 100644 --- a/doc/ref/grains/all/index.rst +++ b/doc/ref/grains/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.grains: -=================================== -Full list of builtin grains modules -=================================== +============== +grains modules +============== .. currentmodule:: salt.grains diff --git a/doc/ref/modules/all/index.rst b/doc/ref/modules/all/index.rst index f9e32e385ad9..22ca010a901b 100644 --- a/doc/ref/modules/all/index.rst +++ b/doc/ref/modules/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt_modules: -====================================== -Full list of builtin execution modules -====================================== +================= +execution modules +================= .. admonition:: Virtual modules diff --git a/doc/ref/netapi/all/index.rst b/doc/ref/netapi/all/index.rst index e978e85ccb3a..a05ec291e29d 100644 --- a/doc/ref/netapi/all/index.rst +++ b/doc/ref/netapi/all/index.rst @@ -1,8 +1,8 @@ .. _all-netapi-modules: -=========================== -Full list of netapi modules -=========================== +============== +netapi modules +============== .. toctree:: :maxdepth: 2 diff --git a/doc/ref/output/all/index.rst b/doc/ref/output/all/index.rst index acee155d6f73..954753bb3613 100644 --- a/doc/ref/output/all/index.rst +++ b/doc/ref/output/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.output: -=================================== -Full list of builtin output modules -=================================== +============== +output modules +============== Follow one of the below links for further information and examples diff --git a/doc/ref/pillar/all/index.rst b/doc/ref/pillar/all/index.rst index a4d331633224..c17f7616c36b 100644 --- a/doc/ref/pillar/all/index.rst +++ b/doc/ref/pillar/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.pillars: -=================================== -Full list of builtin pillar modules -=================================== +============== +pillar modules +============== .. currentmodule:: salt.pillar diff --git a/doc/ref/proxy/all/index.rst b/doc/ref/proxy/all/index.rst index 139595381eb9..28deb2c66c6e 100644 --- a/doc/ref/proxy/all/index.rst +++ b/doc/ref/proxy/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.proxy: -================================== -Full list of builtin proxy modules -================================== +============= +proxy modules +============= .. currentmodule:: salt.proxy diff --git a/doc/ref/queues/all/index.rst b/doc/ref/queues/all/index.rst index 5507a26ce749..2d579aa01558 100644 --- a/doc/ref/queues/all/index.rst +++ b/doc/ref/queues/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.queues: -=========================== -Full list of builtin queues -=========================== +============= +queue modules +============= .. currentmodule:: salt.queues diff --git a/doc/ref/renderers/all/index.rst b/doc/ref/renderers/all/index.rst index cf34c77e69bd..e62b7f56f0e1 100644 --- a/doc/ref/renderers/all/index.rst +++ b/doc/ref/renderers/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.renderers: -===================================== -Full list of builtin renderer modules -===================================== +================ +renderer modules +================ .. currentmodule:: salt.renderers diff --git a/doc/ref/returners/all/index.rst b/doc/ref/returners/all/index.rst index 6dd001aa5d93..2e5e97f035e8 100644 --- a/doc/ref/returners/all/index.rst +++ b/doc/ref/returners/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.returners: -===================================== -Full list of builtin returner modules -===================================== +================ +returner modules +================ .. currentmodule:: salt.returners diff --git a/doc/ref/roster/all/index.rst b/doc/ref/roster/all/index.rst index 063acd7156c6..19446af8d017 100644 --- a/doc/ref/roster/all/index.rst +++ b/doc/ref/roster/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.roster: -=================================== -Full list of builtin roster modules -=================================== +============== +roster modules +============== .. currentmodule:: salt.roster diff --git a/doc/ref/runners/all/index.rst b/doc/ref/runners/all/index.rst index e906c1d6057e..32643b8e6313 100644 --- a/doc/ref/runners/all/index.rst +++ b/doc/ref/runners/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.runners: -=========================== -Full list of runner modules -=========================== +============== +runner modules +============== .. currentmodule:: salt.runners diff --git a/doc/ref/sdb/all/index.rst b/doc/ref/sdb/all/index.rst index 8e6bdbb7a6a6..f7ce58fb7cd4 100644 --- a/doc/ref/sdb/all/index.rst +++ b/doc/ref/sdb/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.sdb: -================================ -Full list of builtin sdb modules -================================ +=========== +sdb modules +=========== .. currentmodule:: salt.sdb diff --git a/doc/ref/serializers/all/index.rst b/doc/ref/serializers/all/index.rst index a9eb50067778..261ccb01f695 100644 --- a/doc/ref/serializers/all/index.rst +++ b/doc/ref/serializers/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.serializers: -================================ -Full list of builtin serializers -================================ +================== +serializer modules +================== .. currentmodule:: salt.serializers diff --git a/doc/ref/states/all/index.rst b/doc/ref/states/all/index.rst index 3288a1c672ee..3e10009d0050 100644 --- a/doc/ref/states/all/index.rst +++ b/doc/ref/states/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.states: -================================== -Full list of builtin state modules -================================== +============= +state modules +============= .. currentmodule:: salt.states diff --git a/doc/ref/thorium/all/index.rst b/doc/ref/thorium/all/index.rst index 791e0258fdcb..9f694775e3db 100644 --- a/doc/ref/thorium/all/index.rst +++ b/doc/ref/thorium/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.thorium: -==================================== -Full list of builtin thorium modules -==================================== +=============== +thorium modules +=============== .. currentmodule:: salt.thorium diff --git a/doc/ref/tops/all/index.rst b/doc/ref/tops/all/index.rst index b7c19d5ce3a0..7072924d5c34 100644 --- a/doc/ref/tops/all/index.rst +++ b/doc/ref/tops/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.tops: -======================================== -Full list of builtin master tops modules -======================================== +=================== +master tops modules +=================== .. currentmodule:: salt.tops diff --git a/doc/ref/wheel/all/index.rst b/doc/ref/wheel/all/index.rst index 73e6d873a692..500c3d5c9eea 100644 --- a/doc/ref/wheel/all/index.rst +++ b/doc/ref/wheel/all/index.rst @@ -1,8 +1,8 @@ .. _all-salt.wheel: -================================== -Full list of builtin wheel modules -================================== +============= +wheel modules +============= .. currentmodule:: salt.wheel diff --git a/doc/topics/jinja/index.rst b/doc/topics/jinja/index.rst new file mode 100644 index 000000000000..adfcdc168816 --- /dev/null +++ b/doc/topics/jinja/index.rst @@ -0,0 +1,364 @@ +.. _jinja: + +=================== +Understanding Jinja +=================== + +`Jinja `_ is the default templating language +in SLS files. + +Jinja in States +=============== + +.. _Jinja: http://jinja.pocoo.org/docs/templates/ + +Jinja is evaluated before YAML, which means it is evaluated before the States +are run. + +The most basic usage of Jinja in state files is using control structures to +wrap conditional or redundant state elements: + +.. code-block:: yaml + + {% if grains['os'] != 'FreeBSD' %} + tcsh: + pkg: + - installed + {% endif %} + + motd: + file.managed: + {% if grains['os'] == 'FreeBSD' %} + - name: /etc/motd + {% elif grains['os'] == 'Debian' %} + - name: /etc/motd.tail + {% endif %} + - source: salt://motd + +In this example, the first if block will only be evaluated on minions that +aren't running FreeBSD, and the second block changes the file name based on the +*os* grain. + +Writing **if-else** blocks can lead to very redundant state files however. In +this case, using :doc:`pillars`, or using a previously +defined variable might be easier: + +.. code-block:: yaml + + {% set motd = ['/etc/motd'] %} + {% if grains['os'] == 'Debian' %} + {% set motd = ['/etc/motd.tail', '/var/run/motd'] %} + {% endif %} + + {% for motdfile in motd %} + {{ motdfile }}: + file.managed: + - source: salt://motd + {% endfor %} + +Using a variable set by the template, the `for loop`_ will iterate over the +list of MOTD files to update, adding a state block for each file. + +The filter_by function can also be used to set variables based on grains: + +.. code-block:: yaml + + {% set auditd = salt['grains.filter_by']({ + 'RedHat': { 'package': 'audit' }, + 'Debian': { 'package': 'auditd' }, + }) %} + +.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for + +Include and Import +================== + +Includes and imports_ can be used to share common, reusable state configuration +between state files and between files. + +.. code-block:: yaml + + {% from 'lib.sls' import test %} + +This would import the ``test`` template variable or macro, not the ``test`` +state element, from the file ``lib.sls``. In the case that the included file +performs checks again grains, or something else that requires context, passing +the context into the included file is required: + +.. code-block:: yaml + + {% from 'lib.sls' import test with context %} + +Including Context During Include/Import +--------------------------------------- + +By adding ``with context`` to the include/import directive, the +current context can be passed to an included/imported template. + +.. code-block:: yaml + + {% import 'openssl/vars.sls' as ssl with context %} + + +.. _imports: http://jinja.pocoo.org/docs/templates/#import + +Macros +====== + +Macros_ are helpful for eliminating redundant code. Macros are most useful as +mini-templates to repeat blocks of strings with a few parameterized variables. +Be aware that stripping whitespace from the template block, as well as +contained blocks, may be necessary to emulate a variable return from the macro. + +.. code-block:: yaml + + # init.sls + {% from 'lib.sls' import pythonpkg with context %} + + python-virtualenv: + pkg.installed: + - name: {{ pythonpkg('virtualenv') }} + + python-fabric: + pkg.installed: + - name: {{ pythonpkg('fabric') }} + +.. code-block:: yaml + + # lib.sls + {% macro pythonpkg(pkg) -%} + {%- if grains['os'] == 'FreeBSD' -%} + py27-{{ pkg }} + {%- elif grains['os'] == 'Debian' -%} + python-{{ pkg }} + {%- endif -%} + {%- endmacro %} + +This would define a macro_ that would return a string of the full package name, +depending on the packaging system's naming convention. The whitespace of the +macro was eliminated, so that the macro would return a string without line +breaks, using `whitespace control`_. + +Template Inheritance +==================== + +`Template inheritance`_ works fine from state files and files. The search path +starts at the root of the state tree or pillar. + +.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance +.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros +.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros +.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control + +Filters +======= + +Saltstack extends `builtin filters`_ with these custom filters: + +strftime + Converts any time related object into a time based string. It requires a + valid :ref:`strftime directives `. An + :ref:`exhaustive list ` can be found in + the official Python documentation. + + .. code-block:: yaml + + {% set curtime = None | strftime() %} + + Fuzzy dates require the `timelib`_ Python module is installed. + + .. code-block:: yaml + + {{ "2002/12/25"|strftime("%y") }} + {{ "1040814000"|strftime("%Y-%m-%d") }} + {{ datetime|strftime("%u") }} + {{ "tomorrow"|strftime }} + +sequence + Ensure that parsed data is a sequence. + +yaml_encode + Serializes a single object into a YAML scalar with any necessary + handling for escaping special characters. This will work for any + scalar YAML data type: ints, floats, timestamps, booleans, strings, + unicode. It will *not* work for multi-objects such as sequences or + maps. + + .. code-block:: yaml + + {%- set bar = 7 %} + {%- set baz = none %} + {%- set zip = true %} + {%- set zap = 'The word of the day is "salty"' %} + + {%- load_yaml as foo %} + bar: {{ bar|yaml_encode }} + baz: {{ baz|yaml_encode }} + baz: {{ zip|yaml_encode }} + baz: {{ zap|yaml_encode }} + {%- endload %} + + In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be + identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be + identical. + +yaml_dquote + Serializes a string into a properly-escaped YAML double-quoted + string. This is useful when the contents of a string are unknown + and may contain quotes or unicode that needs to be preserved. The + resulting string will be emitted with opening and closing double + quotes. + + .. code-block:: yaml + + {%- set bar = '"The quick brown fox . . ."' %} + {%- set baz = 'The word of the day is "salty".' %} + + {%- load_yaml as foo %} + bar: {{ bar|yaml_dquote }} + baz: {{ baz|yaml_dquote }} + {%- endload %} + + In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be + identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be + identical. If variable contents are not guaranteed to be a string + then it is better to use ``yaml_encode`` which handles all YAML + scalar types. + +yaml_squote + Similar to the ``yaml_dquote`` filter but with single quotes. Note + that YAML only allows special escapes inside double quotes so + ``yaml_squote`` is not nearly as useful (viz. you likely want to + use ``yaml_encode`` or ``yaml_dquote``). + +.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters +.. _`timelib`: https://github.com/pediapress/timelib/ + +Jinja in Files +============== + +Jinja_ can be used in the same way in managed files: + +.. code-block:: yaml + + # redis.sls + /etc/redis/redis.conf: + file.managed: + - source: salt://redis.conf + - template: jinja + - context: + bind: 127.0.0.1 + +.. code-block:: yaml + + # lib.sls + {% set port = 6379 %} + +.. code-block:: ini + + # redis.conf + {% from 'lib.sls' import port with context %} + port {{ port }} + bind {{ bind }} + +As an example, configuration was pulled from the file context and from an +external template file. + +.. note:: + + Macros and variables can be shared across templates. They should not be + starting with one or more underscores, and should be managed by one of the + following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and + `import_json`. + +Escaping Jinja +============== + +Occasionally, it may be necessary to escape Jinja syntax. There are two ways to +to do this in Jinja. One is escaping individual variables or strings and the +other is to escape entire blocks. + +To escape a string commonly used in Jinja syntax such as ``{{``, you can use the +following syntax: + +.. code-block:: jinja + + {{ '{{' }} + +For larger blocks that contain Jinja syntax that needs to be escaped, you can use +raw blocks: + +.. code-block:: jinja + + {% raw %} + some text that contains jinja characters that need to be escaped + {% endraw %} + +See the `Escaping`_ section of Jinja's documentation to learn more. + +A real-word example of needing to use raw tags to escape a larger block of code +is when using ``file.managed`` with the ``contents_pillar`` option to manage +files that contain something like consul-template, which shares a syntax subset +with Jinja. Raw blocks are necessary here because the Jinja in the pillar would +be rendered before the file.managed is ever called, so the Jinja syntax must be +escaped: + +.. code-block:: jinja + + {% raw %} + - contents_pillar: | + job "example-job" { + + task "example" { + driver = "docker" + + config { + image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}" + + {% endraw %} + +.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping + +Calling Salt Functions +====================== + +The Jinja renderer provides a shorthand lookup syntax for the ``salt`` +dictionary of :term:`execution function `. + +.. versionadded:: 2014.7.0 + +.. code-block:: yaml + + # The following two function calls are equivalent. + {{ salt['cmd.run']('whoami') }} + {{ salt.cmd.run('whoami') }} + +Debugging +========= + +The ``show_full_context`` function can be used to output all variables present +in the current Jinja context. + +.. versionadded:: 2014.7.0 + +.. code-block:: yaml + + Context is: {{ show_full_context() }} + +Custom Execution Modules +======================== + +Custom execution modules can be used to supplement or replace complex Jinja. Many +tasks that require complex looping and logic are trivial when using Python +in a Salt execution module. Salt execution modules are easy to write and +distribute to Salt minions. + +:ref:`Writing Execution Modules ` + +Functions in custom execution modules are available in the Salt execution +module dictionary just like the built-in execution modules: + +.. code-block:: yaml + + {{ salt['my_custom_module.my_custom_function']() }} + diff --git a/doc/topics/targeting/nodegroups.rst b/doc/topics/targeting/nodegroups.rst index 3024d7f5c8cc..998ac742e6cf 100644 --- a/doc/topics/targeting/nodegroups.rst +++ b/doc/topics/targeting/nodegroups.rst @@ -52,7 +52,7 @@ To match a nodegroup on the CLI, use the ``-N`` command-line option: .. note:: - The ``N@`` classifier cannot be used in compound mathes within the CLI or + The ``N@`` classifier cannot be used in compound matches within the CLI or :term:`top file`, it is only recognized in the :conf_master:`nodegroups` master config file parameter. diff --git a/doc/topics/tutorials/pillar.rst b/doc/topics/tutorials/pillar.rst index 4ca1d6aefd85..18baaa7208f5 100644 --- a/doc/topics/tutorials/pillar.rst +++ b/doc/topics/tutorials/pillar.rst @@ -324,11 +324,14 @@ specified list, notice the nested pillar dict: salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}' -.. note:: - - This will attempt to install telnet on your minions, feel free to - uninstall the package or replace telnet value with anything else. +This will attempt to install telnet on your minions, feel free to +uninstall the package or replace telnet value with anything else. +.. note:: + Be aware that when sending sensitive data via pillar on the command-line + that the publication containing that data will be received by all minions + and will not be restricted to the targeted minions. This may represent + a security concern in some cases. More On Pillar ============== diff --git a/doc/topics/using_salt.rst b/doc/topics/using_salt.rst index caf90ce010ee..f5f494f58651 100644 --- a/doc/topics/using_salt.rst +++ b/doc/topics/using_salt.rst @@ -14,6 +14,7 @@ This section describes the fundamental components and concepts that you need to ../ref/runners/index engines/index yaml/index + jinja/index troubleshooting/index ../faq best_practices diff --git a/doc/topics/yaml/index.rst b/doc/topics/yaml/index.rst index bfed910550af..54600d1e2778 100644 --- a/doc/topics/yaml/index.rst +++ b/doc/topics/yaml/index.rst @@ -1,3 +1,6 @@ +.. _yaml: + +================== Understanding YAML ================== @@ -107,4 +110,10 @@ Learning More One easy way to learn more about how YAML gets rendered into Python data structures is to use an online YAML parser to see the Python output. -One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/ \ No newline at end of file +One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/ + +Templating +---------- +Jinja statements and expressions are allowed by default in SLS files. See +:ref:`Understanding Jinja `. + diff --git a/salt/netapi/rest_cherrypy/app.py b/salt/netapi/rest_cherrypy/app.py index a06c3708cf2d..cda4ff84e1ab 100644 --- a/salt/netapi/rest_cherrypy/app.py +++ b/salt/netapi/rest_cherrypy/app.py @@ -247,6 +247,22 @@ .. |200| replace:: success .. |401| replace:: authentication required .. |406| replace:: requested Content-Type not available + +A Note About Curl +================= + +When sending passwords and data that might need to be urlencoded, you must set +the ``-d`` flag to indicate the content type, and the ``--data-urlencode`` flag +to urlencode the input. + +.. code-block:: bash + + curl -ksi http://localhost:8000/login \\ + -H "Accept: application/json" \\ + -d username='myapiuser' \\ + --data-urlencode password='1234+' \\ + -d eauth='pam' + ''' # We need a custom pylintrc here... # pylint: disable=W0212,E1101,C0103,R0201,W0221,W0613 diff --git a/salt/renderers/jinja.py b/salt/renderers/jinja.py index 4413e9d6ebf7..0bab045a0e25 100644 --- a/salt/renderers/jinja.py +++ b/salt/renderers/jinja.py @@ -2,319 +2,7 @@ ''' Jinja loading utils to enable a more powerful backend for jinja templates -Jinja in States -=============== - -.. _Jinja: http://jinja.pocoo.org/docs/templates/ - -The most basic usage of Jinja in state files is using control structures to -wrap conditional or redundant state elements: - -.. code-block:: yaml - - {% if grains['os'] != 'FreeBSD' %} - tcsh: - pkg: - - installed - {% endif %} - - motd: - file.managed: - {% if grains['os'] == 'FreeBSD' %} - - name: /etc/motd - {% elif grains['os'] == 'Debian' %} - - name: /etc/motd.tail - {% endif %} - - source: salt://motd - -In this example, the first if block will only be evaluated on minions that -aren't running FreeBSD, and the second block changes the file name based on the -*os* grain. - -Writing **if-else** blocks can lead to very redundant state files however. In -this case, using :doc:`pillars`, or using a previously -defined variable might be easier: - -.. code-block:: yaml - - {% set motd = ['/etc/motd'] %} - {% if grains['os'] == 'Debian' %} - {% set motd = ['/etc/motd.tail', '/var/run/motd'] %} - {% endif %} - - {% for motdfile in motd %} - {{ motdfile }}: - file.managed: - - source: salt://motd - {% endfor %} - -Using a variable set by the template, the `for loop`_ will iterate over the -list of MOTD files to update, adding a state block for each file. - -.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for - -Include and Import -================== - -Includes and imports_ can be used to share common, reusable state configuration -between state files and between files. - -.. code-block:: yaml - - {% from 'lib.sls' import test %} - -This would import the ``test`` template variable or macro, not the ``test`` -state element, from the file ``lib.sls``. In the case that the included file -performs checks again grains, or something else that requires context, passing -the context into the included file is required: - -.. code-block:: yaml - - {% from 'lib.sls' import test with context %} - -.. _imports: http://jinja.pocoo.org/docs/templates/#import - -Macros -====== - -Macros_ are helpful for eliminating redundant code, however stripping whitespace -from the template block, as well as contained blocks, may be necessary to -emulate a variable return from the macro. - -.. code-block:: yaml - - # init.sls - {% from 'lib.sls' import pythonpkg with context %} - - python-virtualenv: - pkg.installed: - - name: {{ pythonpkg('virtualenv') }} - - python-fabric: - pkg.installed: - - name: {{ pythonpkg('fabric') }} - -.. code-block:: yaml - - # lib.sls - {% macro pythonpkg(pkg) -%} - {%- if grains['os'] == 'FreeBSD' -%} - py27-{{ pkg }} - {%- elif grains['os'] == 'Debian' -%} - python-{{ pkg }} - {%- endif -%} - {%- endmacro %} - -This would define a macro_ that would return a string of the full package name, -depending on the packaging system's naming convention. The whitespace of the -macro was eliminated, so that the macro would return a string without line -breaks, using `whitespace control`_. - -Template Inheritance -==================== - -`Template inheritance`_ works fine from state files and files. The search path -starts at the root of the state tree or pillar. - -.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance -.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros -.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros -.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control - -Filters -======= - -Saltstack extends `builtin filters`_ with these custom filters: - -strftime - Converts any time related object into a time based string. It requires a - valid :ref:`strftime directives `. An - :ref:`exhaustive list ` can be found in - the official Python documentation. - - .. code-block:: yaml - - {% set curtime = None | strftime() %} - - Fuzzy dates require the `timelib`_ Python module is installed. - - .. code-block:: yaml - - {{ "2002/12/25"|strftime("%y") }} - {{ "1040814000"|strftime("%Y-%m-%d") }} - {{ datetime|strftime("%u") }} - {{ "tomorrow"|strftime }} - -sequence - Ensure that parsed data is a sequence. - -yaml_encode - Serializes a single object into a YAML scalar with any necessary - handling for escaping special characters. This will work for any - scalar YAML data type: ints, floats, timestamps, booleans, strings, - unicode. It will *not* work for multi-objects such as sequences or - maps. - - .. code-block:: yaml - - {%- set bar = 7 %} - {%- set baz = none %} - {%- set zip = true %} - {%- set zap = 'The word of the day is "salty"' %} - - {%- load_yaml as foo %} - bar: {{ bar|yaml_encode }} - baz: {{ baz|yaml_encode }} - baz: {{ zip|yaml_encode }} - baz: {{ zap|yaml_encode }} - {%- endload %} - - In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be - identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be - identical. - -yaml_dquote - Serializes a string into a properly-escaped YAML double-quoted - string. This is useful when the contents of a string are unknown - and may contain quotes or unicode that needs to be preserved. The - resulting string will be emitted with opening and closing double - quotes. - - .. code-block:: yaml - - {%- set bar = '"The quick brown fox . . ."' %} - {%- set baz = 'The word of the day is "salty".' %} - - {%- load_yaml as foo %} - bar: {{ bar|yaml_dquote }} - baz: {{ baz|yaml_dquote }} - {%- endload %} - - In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be - identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be - identical. If variable contents are not guaranteed to be a string - then it is better to use ``yaml_encode`` which handles all YAML - scalar types. - -yaml_squote - Similar to the ``yaml_dquote`` filter but with single quotes. Note - that YAML only allows special escapes inside double quotes so - ``yaml_squote`` is not nearly as useful (viz. you likely want to - use ``yaml_encode`` or ``yaml_dquote``). - -.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters -.. _`timelib`: https://github.com/pediapress/timelib/ - -Jinja in Files -============== - -Jinja_ can be used in the same way in managed files: - -.. code-block:: yaml - - # redis.sls - /etc/redis/redis.conf: - file.managed: - - source: salt://redis.conf - - template: jinja - - context: - bind: 127.0.0.1 - -.. code-block:: yaml - - # lib.sls - {% set port = 6379 %} - -.. code-block:: ini - - # redis.conf - {% from 'lib.sls' import port with context %} - port {{ port }} - bind {{ bind }} - -As an example, configuration was pulled from the file context and from an -external template file. - -.. note:: - - Macros and variables can be shared across templates. They should not be - starting with one or more underscores, and should be managed by one of the - following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and - `import_json`. - -Escaping Jinja -============== - -Occasionally, it may be necessary to escape Jinja syntax. There are two ways to -to do this in Jinja. One is escaping individual variables or strings and the -other is to escape entire blocks. - -To escape a string commonly used in Jinja syntax such as ``{{``, you can use the -following syntax: - -.. code-block:: jinja - - {{ '{{' }} - -For larger blocks that contain Jinja syntax that needs to be escaped, you can use -raw blocks: - -.. code-block:: jinja - - {% raw %] - some text that contains jinja characters that need to be escaped - {% endraw %} - -See the `Escaping`_ section of Jinja's documentation to learn more. - -A real-word example of needing to use raw tags to escape a larger block of code -is when using ``file.managed`` with the ``contents_pillar`` option to manage -files that contain something like consul-template, which shares a syntax subset -with Jinja. Raw blocks are necessary here because the Jinja in the pillar would -be rendered before the file.managed is ever called, so the Jinja syntax must be -escaped: - -.. code-block:: jinja - - {% raw %} - - contents_pillar: | - job "example-job" { - - task "example" { - driver = "docker" - - config { - image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}" - - {% endraw %} - -.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping - -Calling Salt Functions -====================== - -The Jinja renderer provides a shorthand lookup syntax for the ``salt`` -dictionary of :term:`execution function `. - -.. versionadded:: 2014.7.0 - -.. code-block:: yaml - - # The following two function calls are equivalent. - {{ salt['cmd.run']('whoami') }} - {{ salt.cmd.run('whoami') }} - -Debugging -========= - -The ``show_full_context`` function can be used to output all variables present -in the current Jinja context. - -.. versionadded:: 2014.7.0 - -.. code-block:: yaml - - Context is: {{ show_full_context() }} +For Jinja usage information see :ref:`Understanding Jinja `. ''' # Import python libs diff --git a/salt/renderers/yaml.py b/salt/renderers/yaml.py index 9d8fa83c89b8..ca506cbb699a 100644 --- a/salt/renderers/yaml.py +++ b/salt/renderers/yaml.py @@ -1,6 +1,8 @@ # -*- coding: utf-8 -*- ''' YAML Renderer for Salt + +For YAML usage information see :ref:`Understanding YAML `. ''' from __future__ import absolute_import