[2.10] Docsite backport of 71973, 71975, 71980 (#71991)
* Docsite: improve user_guide/playbooks_vars_facts (#71973) * Docsite: improve user_guide/playbooks_vars_facts * Docsite: update user_guide/vault (#71975) * Docsite: update user_guide/playbooks_filters (#71980)
This commit is contained in:
Andrew Klychkov
GitHub
parent
775d6e6752
commit
dbbc44b1f4
|
|
@ -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:
|
||||
|
|
@ -1561,7 +1566,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::
|
||||
|
||||
|
|
|
|||
|
|
@ -14,13 +14,15 @@ Ansible facts
|
|||
|
||||
Ansible facts are data related to your remote systems, including operating systems, IP addresses, attached filesystems, and more. You can access this data in the ``ansible_facts`` variable. By default, you can also access some Ansible facts as top-level variables with the ``ansible_`` prefix. You can disable this behavior using the :ref:`INJECT_FACTS_AS_VARS` setting. To see all available facts, add this task to a play::
|
||||
|
||||
- debug: var=ansible_facts
|
||||
- name: Print all available facts
|
||||
ansible.builtin.debug:
|
||||
var: ansible_facts
|
||||
|
||||
To see the 'raw' information as gathered, run this command at the command line::
|
||||
|
||||
ansible <hostname> -m setup
|
||||
ansible <hostname> -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 <hostname> -m setup -a "filter=ansible_local"
|
||||
ansible <hostname> -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"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in a new issue