ansible/docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst
Sandra McCann ae9c1167e4
[2.10] Docs Backportapalooza 7 (#71261)
* Fixes due to branch being renamed (#71115)
The ansible collection repository correctly renamed their default branch from `master` to `main`, which has caused a number for broken urls. This PR fixes those urls.

(cherry picked from commit fb9c9570d5)

* Docs:  Fix typo (#71119)

(cherry picked from commit cb9336ab6d)

* remove network for 2.10 base porting guide (#71158)

(cherry picked from commit 56748a8060)

* Updating Getting Started with Resources section #68962 (#71102)

* Updating Getting Started with Resources section #68962
* Add links, including Workshops URL #68962

(cherry picked from commit 5f8b45a70e)

* start of 'data manipulation' examples (#46979)

Co-authored-by: Klaus Frank <agowa338@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit f46b124d65)

* toml: Clarify about inventory examples (#71180)

Add a note in toml inventory plugin about three different
inventory examples. Fixes: #67003

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit edac065bd2)

* filters: minor doc fix (#71178)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 0a7ab396c7)

* docs: 'ansible_play_hosts' lists active hosts, not limited by serial (#71116)

ansible_play_batch lists the currently targeted host(s) in the serial/batch, while
ansible_play_hosts lists all the hosts which will be targeted by the play.

(cherry picked from commit e72e12aa27)

* Fix references to Ansible Collections Overview (#71227)

(cherry picked from commit 19589db10c)

* add another resource module example (#71162)

* Update docs/docsite/rst/network/user_guide/network_resource_modules.rst
Co-authored-by: Nilashish Chakraborty <nilashishchakraborty8@gmail.com>

(cherry picked from commit f4388de14d)

* Adds fest link (#71241)

(cherry picked from commit ae3b8eec12)

* Update release page for ansible and ansible-base (#71229)

* [docs] 2.7 is EOL, add 2.10 which is almost out
- Remove 2.7 support from the maintenance schedule
- Add 2.10 which is in RC and will be out soon enough.
Signed-off-by: Rick Elrod <rick@elrod.me>

* Update docs/docsite/rst/reference_appendices/release_and_maintenance.rst, fix table and separate ansible-base from ansible, fix rstcheck errors, clean up sections, explain the two packages
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Rick Elrod <rick@elrod.me>

(cherry picked from commit 553ccedcd3)

Co-authored-by: Daniel Finneran <dan@thebsdbox.co.uk>
Co-authored-by: Liviu Chircu <liviu@opensips.org>
Co-authored-by: kshitijcode <ikshitijsharma@gmail.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
Co-authored-by: Håkon Solbjørg <hakon@solbj.org>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
2020-08-13 12:23:46 -05:00

112 lines
4.3 KiB
ReStructuredText

.. _playbooks_advanced_syntax:
***************
Advanced Syntax
***************
The advanced YAML syntax examples on this page give you more control over the data placed in YAML files used by Ansible. You can find additional information about Python-specific YAML in the official `PyYAML Documentation <https://pyyaml.org/wiki/PyYAMLDocumentation#YAMLtagsandPythontypes>`_.
.. contents::
:local:
.. _unsafe_strings:
Unsafe or raw strings
=====================
When handling values returned by lookup plugins, Ansible uses a data type called ``unsafe`` to block templating. Marking data as unsafe prevents malicious users from abusing Jinja2 templates to execute arbitrary code on target machines. The Ansible implementation ensures that unsafe values are never templated. It is more comprehensive than escaping Jinja2 with ``{% raw %} ... {% endraw %}`` tags.
You can use the same ``unsafe`` data type in variables you define, to prevent templating errors and information disclosure. You can mark values supplied by :ref:`vars_prompts<unsafe_prompts>` as unsafe. You can also use ``unsafe`` in playbooks. The most common use cases include passwords that allow special characters like ``{`` or ``%``, and JSON arguments that look like templates but should not be templated. For example:
.. code-block:: yaml
---
mypassword: !unsafe 234%234{435lkj{{lkjsdf
In a playbook::
---
hosts: all
vars:
my_unsafe_variable: !unsafe 'unsafe % value'
tasks:
...
For complex variables such as hashes or arrays, use ``!unsafe`` on the individual elements::
---
my_unsafe_array:
- !unsafe 'unsafe element'
- 'safe element'
my_unsafe_hash:
unsafe_key: !unsafe 'unsafe value'
.. _anchors_and_aliases:
YAML anchors and aliases: sharing variable values
=================================================
`YAML anchors and aliases <https://yaml.org/spec/1.2/spec.html#id2765878>`_ help you define, maintain, and use shared variable values in a flexible way.
You define an anchor with ``&``, then refer to it using an alias, denoted with ``*``. Here's an example that sets three values with an anchor, uses two of those values with an alias, and overrides the third value::
---
...
vars:
app1:
jvm: &jvm_opts
opts: '-Xms1G -Xmx2G'
port: 1000
path: /usr/lib/app1
app2:
jvm:
<<: *jvm_opts
path: /usr/lib/app2
...
Here, ``app1`` and ``app2`` share the values for ``opts`` and ``port`` using the anchor ``&jvm_opts`` and the alias ``*jvm_opts``.
The value for ``path`` is merged by ``<<`` or `merge operator <https://yaml.org/type/merge.html>`_.
Anchors and aliases also let you share complex sets of variable values, including nested variables. If you have one variable value that includes another variable value, you can define them separately::
vars:
webapp_version: 1.0
webapp_custom_name: ToDo_App-1.0
This is inefficient and, at scale, means more maintenance. To incorporate the version value in the name, you can use an anchor in ``app_version`` and an alias in ``custom_name``::
vars:
webapp:
version: &my_version 1.0
custom_name:
- "ToDo_App"
- *my_version
Now, you can re-use the value of ``app_version`` within the value of ``custom_name`` and use the output in a template::
---
- name: Using values nested inside dictionary
hosts: localhost
vars:
webapp:
version: &my_version 1.0
custom_name:
- "ToDo_App"
- *my_version
tasks:
- name: Using Anchor value
debug:
msg: My app is called "{{ webapp.custom_name | join('-') }}".
You've anchored the value of ``version`` with the ``&my_version`` anchor, and re-used it with the ``*my_version`` alias. Anchors and aliases let you access nested values inside dictionaries.
.. seealso::
:ref:`playbooks_variables`
All about variables
:doc:`complex_data_manipulation`
Doing complex data manipulation in Ansible
`User Mailing List <https://groups.google.com/group/ansible-project>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel