Docsite: update user_guide/playbooks_filters (#71980)

pull/71989/head
Andrew Klychkov 4 years ago committed by GitHub
parent 0c3a9c7ae6
commit 0645436acd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -41,8 +41,8 @@ Making variables optional
By default Ansible requires values for all variables in a templated expression. However, you can make specific variables optional. For example, you might want to use a system default for some items and control the value for others. To make a variable optional, set the default value to the special variable ``omit``:: By default Ansible requires values for all variables in a templated expression. However, you can make specific variables optional. For example, you might want to use a system default for some items and control the value for others. To make a variable optional, set the default value to the special variable ``omit``::
- name: touch files with an optional mode - name: Touch files with an optional mode
file: ansible.builtin.file:
dest: "{{ item.path }}" dest: "{{ item.path }}"
state: touch state: touch
mode: "{{ item.mode | default(omit) }}" mode: "{{ item.mode | default(omit) }}"
@ -55,14 +55,14 @@ By default Ansible requires values for all variables in a templated expression.
In this example, the default mode for the files ``/tmp/foo`` and ``/tmp/bar`` is determined by the umask of the system. Ansible does not send a value for ``mode``. Only the third file, ``/tmp/baz``, receives the `mode=0444` option. In this example, the default mode for the files ``/tmp/foo`` and ``/tmp/bar`` is determined by the umask of the system. Ansible does not send a value for ``mode``. Only the third file, ``/tmp/baz``, receives the `mode=0444` option.
.. note:: If you are "chaining" additional filters after the ``default(omit)`` filter, you should instead do something like this: .. note:: If you are "chaining" additional filters after the ``default(omit)`` filter, you should instead do something like this:
``"{{ foo | default(None) | some_filter or omit }}"``. In this example, the default ``None`` (Python null) value will cause the later filters to fail, which will trigger the ``or omit`` portion of the logic. Using ``omit`` in this manner is very specific to the later filters you're chaining though, so be prepared for some trial and error if you do this. ``"{{ foo | default(None) | some_filter or omit }}"``. In this example, the default ``None`` (Python null) value will cause the later filters to fail, which will trigger the ``or omit`` portion of the logic. Using ``omit`` in this manner is very specific to the later filters you are chaining though, so be prepared for some trial and error if you do this.
.. _forcing_variables_to_be_defined: .. _forcing_variables_to_be_defined:
Defining mandatory values Defining mandatory values
------------------------- -------------------------
If you configure Ansible to ignore undefined variables, you may want to define some values as mandatory. By default, Ansible fails if a variable in your playbook or command is undefined. You can configure Ansible to allow undefined variables by setting :ref:`DEFAULT_UNDEFINED_VAR_BEHAVIOR` to ``false``. In that case, you may want to require some variables to be defined. You can do with this with:: If you configure Ansible to ignore undefined variables, you may want to define some values as mandatory. By default, Ansible fails if a variable in your playbook or command is undefined. You can configure Ansible to allow undefined variables by setting :ref:`DEFAULT_UNDEFINED_VAR_BEHAVIOR` to ``false``. In that case, you may want to require some variables to be defined. You can do this with::
{{ variable | mandatory }} {{ variable | mandatory }}
@ -234,10 +234,12 @@ If you are reading in some already formatted data::
for example:: for example::
tasks: tasks:
- shell: cat /some/path/to/file.json - name: Register JSON output as a variable
ansible.builtin.shell: cat /some/path/to/file.json
register: result register: result
- set_fact: - name: Set a variable
ansible.builtin.set_fact:
myvar: "{{ result.stdout | from_json }}" myvar: "{{ result.stdout | from_json }}"
@ -266,9 +268,12 @@ The ``from_yaml_all`` filter will return a generator of parsed YAML documents.
for example:: for example::
tasks: tasks:
- shell: cat /some/path/to/multidoc-file.yaml - name: Register a file content as a variable
ansible.builtin.shell: cat /some/path/to/multidoc-file.yaml
register: result register: result
- debug:
- name: Print the transformed variable
ansible.builtin.debug:
msg: '{{ item }}' msg: '{{ item }}'
loop: '{{ result.stdout | from_yaml_all | list }}' loop: '{{ result.stdout | from_yaml_all | list }}'
@ -286,18 +291,18 @@ Combining items from multiple lists: zip and zip_longest
To get a list combining the elements of other lists use ``zip``:: To get a list combining the elements of other lists use ``zip``::
- name: give me list combo of two lists - name: Give me list combo of two lists
debug: ansible.builtin.debug:
msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}" msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}"
- name: give me shortest combo of two lists - name: Give me shortest combo of two lists
debug: ansible.builtin.debug:
msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}" msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}"
To always exhaust all lists use ``zip_longest``:: To always exhaust all lists use ``zip_longest``::
- name: give me longest combo of three lists , fill with X - name: Give me longest combo of three lists , fill with X
debug: ansible.builtin.debug:
msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}" msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}"
Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to construct a ``dict``:: Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to construct a ``dict``::
@ -374,7 +379,7 @@ Data after applying the ``subelements`` filter::
You can use the transformed data with ``loop`` to iterate over the same subelement for multiple objects:: You can use the transformed data with ``loop`` to iterate over the same subelement for multiple objects::
- name: Set authorized ssh key, extracting just that data from 'users' - name: Set authorized ssh key, extracting just that data from 'users'
authorized_key: ansible.posix.authorized_key:
user: "{{ item.0.name }}" user: "{{ item.0.name }}"
key: "{{ lookup('file', item.1) }}" key: "{{ lookup('file', item.1) }}"
loop: "{{ users | subelements('authorized') }}" loop: "{{ users | subelements('authorized') }}"
@ -633,20 +638,20 @@ permutations
^^^^^^^^^^^^ ^^^^^^^^^^^^
To get permutations of a list:: To get permutations of a list::
- name: give me largest permutations (order matters) - name: Give me largest permutations (order matters)
debug: ansible.builtin.debug:
msg: "{{ [1,2,3,4,5] | permutations | list }}" msg: "{{ [1,2,3,4,5] | permutations | list }}"
- name: give me permutations of sets of three - name: Give me permutations of sets of three
debug: ansible.builtin.debug:
msg: "{{ [1,2,3,4,5] | permutations(3) | list }}" msg: "{{ [1,2,3,4,5] | permutations(3) | list }}"
combinations combinations
^^^^^^^^^^^^ ^^^^^^^^^^^^
Combinations always require a set size:: Combinations always require a set size::
- name: give me combinations for sets of two - name: Give me combinations for sets of two
debug: ansible.builtin.debug:
msg: "{{ [1,2,3,4,5] | combinations(2) | list }}" msg: "{{ [1,2,3,4,5] | combinations(2) | list }}"
Also see the :ref:`zip_filter` Also see the :ref:`zip_filter`
@ -657,8 +662,8 @@ The product filter returns the `cartesian product <https://docs.python.org/3/lib
For example:: For example::
- name: generate multiple hostnames - name: Generate multiple hostnames
debug: ansible.builtin.debug:
msg: "{{ ['foo', 'bar'] | product(['com']) | map('join', '.') | join(',') }}" msg: "{{ ['foo', 'bar'] | product(['com']) | map('join', '.') | join(',') }}"
This would result in:: This would result in::
@ -730,21 +735,21 @@ Consider this data structure::
To extract all clusters from this structure, you can use the following query:: To extract all clusters from this structure, you can use the following query::
- name: "Display all cluster names" - name: Display all cluster names
debug: ansible.builtin.debug:
var: item var: item
loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}" loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
To extract all server names:: To extract all server names::
- name: "Display all server names" - name: Display all server names
debug: ansible.builtin.debug:
var: item var: item
loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}" loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
To extract ports from cluster1:: To extract ports from cluster1::
- name: "Display all ports from cluster1" - ansible.builtin.name: Display all ports from cluster1
debug: debug:
var: item var: item
loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}" loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
@ -755,16 +760,16 @@ To extract ports from cluster1::
To print out the ports from cluster1 in a comma separated string:: To print out the ports from cluster1 in a comma separated string::
- name: "Display all ports from cluster1 as a string" - name: Display all ports from cluster1 as a string
debug: ansible.builtin.debug:
msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}" msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
.. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability. .. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:: You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_::
- name: "Display all ports from cluster1" - name: Display all ports from cluster1
debug: ansible.builtin.debug:
var: item var: item
loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}" loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
@ -772,8 +777,8 @@ You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id25
To get a hash map with all ports and names of a cluster:: To get a hash map with all ports and names of a cluster::
- name: "Display all server ports and names from cluster1" - name: Display all server ports and names from cluster1
debug: ansible.builtin.debug:
var: item var: item
loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}" loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
vars: vars:
@ -1569,7 +1574,8 @@ Manipulating strings
To add quotes for shell usage:: To add quotes for shell usage::
- shell: echo {{ string_value | quote }} - name: Run a shell command
ansible.builtin.shell: echo {{ string_value | quote }}
To concatenate a list into a string:: To concatenate a list into a string::

Loading…
Cancel
Save