From 0645436acd9fac3cdbdc5745d1fc09e9f92ef5a8 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 28 Sep 2020 21:26:57 +0300 Subject: [PATCH] Docsite: update user_guide/playbooks_filters (#71980) --- .../rst/user_guide/playbooks_filters.rst | 76 ++++++++++--------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index f6d1e04b833..3af6dc0ecb3 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -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 `_:: - - 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