Docsite: update user_guide/playbooks_filters (#71980)
This commit is contained in:
Andrew Klychkov
GitHub
parent
0c3a9c7ae6
commit
0645436acd
1 changed files with 41 additions and 35 deletions
|
|
@ -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``::
|
||||
|
||||
- name: touch files with an optional mode
|
||||
file:
|
||||
- name: Touch files with an optional mode
|
||||
ansible.builtin.file:
|
||||
dest: "{{ item.path }}"
|
||||
state: touch
|
||||
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.
|
||||
|
||||
.. 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:
|
||||
|
||||
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 }}
|
||||
|
||||
|
|
@ -234,10 +234,12 @@ If you are reading in some already formatted data::
|
|||
for example::
|
||||
|
||||
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
|
||||
|
||||
- set_fact:
|
||||
- name: Set a variable
|
||||
ansible.builtin.set_fact:
|
||||
myvar: "{{ result.stdout | from_json }}"
|
||||
|
||||
|
||||
|
|
@ -266,9 +268,12 @@ The ``from_yaml_all`` filter will return a generator of parsed YAML documents.
|
|||
for example::
|
||||
|
||||
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
|
||||
- debug:
|
||||
|
||||
- name: Print the transformed variable
|
||||
ansible.builtin.debug:
|
||||
msg: '{{ item }}'
|
||||
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``::
|
||||
|
||||
- name: give me list combo of two lists
|
||||
debug:
|
||||
- name: Give me list combo of two lists
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}"
|
||||
|
||||
- name: give me shortest combo of two lists
|
||||
debug:
|
||||
- name: Give me shortest combo of two lists
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}"
|
||||
|
||||
To always exhaust all lists use ``zip_longest``::
|
||||
|
||||
- name: give me longest combo of three lists , fill with X
|
||||
debug:
|
||||
- name: Give me longest combo of three lists , fill with X
|
||||
ansible.builtin.debug:
|
||||
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``::
|
||||
|
|
@ -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::
|
||||
|
||||
- name: Set authorized ssh key, extracting just that data from 'users'
|
||||
authorized_key:
|
||||
ansible.posix.authorized_key:
|
||||
user: "{{ item.0.name }}"
|
||||
key: "{{ lookup('file', item.1) }}"
|
||||
loop: "{{ users | subelements('authorized') }}"
|
||||
|
|
@ -633,20 +638,20 @@ permutations
|
|||
^^^^^^^^^^^^
|
||||
To get permutations of a list::
|
||||
|
||||
- name: give me largest permutations (order matters)
|
||||
debug:
|
||||
- name: Give me largest permutations (order matters)
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ [1,2,3,4,5] | permutations | list }}"
|
||||
|
||||
- name: give me permutations of sets of three
|
||||
debug:
|
||||
- name: Give me permutations of sets of three
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ [1,2,3,4,5] | permutations(3) | list }}"
|
||||
|
||||
combinations
|
||||
^^^^^^^^^^^^
|
||||
Combinations always require a set size::
|
||||
|
||||
- name: give me combinations for sets of two
|
||||
debug:
|
||||
- name: Give me combinations for sets of two
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ [1,2,3,4,5] | combinations(2) | list }}"
|
||||
|
||||
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::
|
||||
|
||||
- name: generate multiple hostnames
|
||||
debug:
|
||||
- name: Generate multiple hostnames
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ ['foo', 'bar'] | product(['com']) | map('join', '.') | join(',') }}"
|
||||
|
||||
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::
|
||||
|
||||
- name: "Display all cluster names"
|
||||
debug:
|
||||
- name: Display all cluster names
|
||||
ansible.builtin.debug:
|
||||
var: item
|
||||
loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
|
||||
|
||||
To extract all server names::
|
||||
|
||||
- name: "Display all server names"
|
||||
debug:
|
||||
- name: Display all server names
|
||||
ansible.builtin.debug:
|
||||
var: item
|
||||
loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
|
||||
|
||||
To extract ports from cluster1::
|
||||
|
||||
- name: "Display all ports from cluster1"
|
||||
- ansible.builtin.name: Display all ports from cluster1
|
||||
debug:
|
||||
var: item
|
||||
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::
|
||||
|
||||
- name: "Display all ports from cluster1 as a string"
|
||||
debug:
|
||||
- name: Display all ports from cluster1 as a string
|
||||
ansible.builtin.debug:
|
||||
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.
|
||||
|
||||
You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_::
|
||||
|
||||
- name: "Display all ports from cluster1"
|
||||
debug:
|
||||
- name: Display all ports from cluster1
|
||||
ansible.builtin.debug:
|
||||
var: item
|
||||
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::
|
||||
|
||||
- name: "Display all server ports and names from cluster1"
|
||||
debug:
|
||||
- name: Display all server ports and names from cluster1
|
||||
ansible.builtin.debug:
|
||||
var: item
|
||||
loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
|
||||
vars:
|
||||
|
|
@ -1569,7 +1574,8 @@ Manipulating strings
|
|||
|
||||
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::
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue