diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 6976607932e..f009900a5b6 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 -m setup + ansible -m ansible.builtin.setup -Facts include a large amount of variable data, which may look like this on Ansible 2.7: +Facts include a large amount of variable data, which may look like this: .. code-block:: json @@ -518,7 +520,7 @@ Fact caching can improve performance. If you manage thousands of hosts, you can Disabling facts --------------- -By default, Ansible gathers facts at the beginning of each play. If you do not need to gather facts (for example, if you know know everything about your systems centrally), you can turn off fact gathering at the play level to improve scalability. Disabling facts may particularly improve performance in push mode with very large numbers of systems, or if you are using Ansible on experimental platforms. To disable fact gathering:: +By default, Ansible gathers facts at the beginning of each play. If you do not need to gather facts (for example, if you know everything about your systems centrally), you can turn off fact gathering at the play level to improve scalability. Disabling facts may particularly improve performance in push mode with very large numbers of systems, or if you are using Ansible on experimental platforms. To disable fact gathering:: - hosts: whatever gather_facts: no @@ -526,7 +528,7 @@ By default, Ansible gathers facts at the beginning of each play. If you do not n Adding custom facts ------------------- -The setup module in Ansible automatically discovers a standard set of facts about each host. If you want to add custom values to your facts, you can write a custom facts module, set temporary facts with a ``set_fact`` task, or provide permanent custom facts using the facts.d directory. +The setup module in Ansible automatically discovers a standard set of facts about each host. If you want to add custom values to your facts, you can write a custom facts module, set temporary facts with a ``ansible.builtin.set_fact`` task, or provide permanent custom facts using the facts.d directory. .. _local_facts: @@ -547,7 +549,7 @@ To add static facts, simply add a file with the ``.facts`` extension. For exampl The next time fact gathering runs, your facts will include a hash variable fact named ``general`` with ``asdf`` and ``bar`` as members. To validate this, run the following:: - ansible -m setup -a "filter=ansible_local" + ansible -m ansible.builtin.setup -a "filter=ansible_local" And you will see your custom fact added:: @@ -582,14 +584,20 @@ By default, fact gathering runs once at the beginning of each play. If you creat - hosts: webservers tasks: - - name: create directory for ansible custom facts - file: state=directory recurse=yes path=/etc/ansible/facts.d + - name: Create directory for ansible custom facts + ansible.builtin.file: + state: directory + recurse: yes + path: /etc/ansible/facts.d - - name: install custom ipmi fact - copy: src=ipmi.fact dest=/etc/ansible/facts.d + - name: Install custom ipmi fact + ansible.builtin.copy: + src: ipmi.fact + dest: /etc/ansible/facts.d - - name: re-read facts after adding custom fact - setup: filter=ansible_local + - name: Re-read facts after adding custom fact + ansible.builtin.setup: + filter: ansible_local If you use this pattern frequently, a custom facts module would be more efficient than facts.d. @@ -664,9 +672,9 @@ Ansible version To adapt playbook behavior to different versions of Ansible, you can use the variable ``ansible_version``, which has the following structure:: "ansible_version": { - "full": "2.0.0.2", + "full": "2.10.1", "major": 2, - "minor": 0, - "revision": 0, - "string": "2.0.0.2" + "minor": 10, + "revision": 1, + "string": "2.10.1" } diff --git a/docs/docsite/rst/user_guide/vault.rst b/docs/docsite/rst/user_guide/vault.rst index 0f5d035b710..d84aefec483 100644 --- a/docs/docsite/rst/user_guide/vault.rst +++ b/docs/docsite/rst/user_guide/vault.rst @@ -264,7 +264,7 @@ You can view the original value of an encrypted variable using the debug module. .. code-block:: console - ansible localhost -m debug -a var="new_user_password" -e "@vars.yml" --vault-id dev@a_password_file + ansible localhost -m ansible.builtin.debug -a var="new_user_password" -e "@vars.yml" --vault-id dev@a_password_file localhost | SUCCESS => { "new_user_password": "hunter2"