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::
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::
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::
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
..code-block:: json
@ -518,7 +520,7 @@ Fact caching can improve performance. If you manage thousands of hosts, you can
Disabling facts
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
- hosts: whatever
gather_facts: no
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
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:
.._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::
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::
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
Andrew Klychkov
4 years ago
committed by