@ -12,13 +12,17 @@ With Ansible you can retrieve or discover certain variables containing informati
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::
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:
..code-block:: yaml
- 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:
..code-block:: shell
ansible <hostname> -m ansible.builtin.setup
@ -483,11 +487,15 @@ Facts include a large amount of variable data, which may look like this:
"module_setup": true
}
You can reference the model of the first disk in the facts shown above in a template or playbook as::
You can reference the model of the first disk in the facts shown above in a template or playbook as:
..code-block:: jinja
{{ ansible_facts['devices']['xvda']['model'] }}
To reference the system hostname::
To reference the system hostname:
..code-block:: jinja
{{ ansible_facts['nodename'] }}
@ -509,7 +517,9 @@ On some distros, you may see missing fact values or facts set to default values
Caching facts
-------------
Like registered variables, facts are stored in memory by default. However, unlike registered variables, facts can be gathered independently and cached for repeated use. With cached facts, you can refer to facts from one system when configuring a second system, even if Ansible executes the current play on the second system first. For example::
Like registered variables, facts are stored in memory by default. However, unlike registered variables, facts can be gathered independently and cached for repeated use. With cached facts, you can refer to facts from one system when configuring a second system, even if Ansible executes the current play on the second system first. For example:
@ -522,7 +532,9 @@ 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 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:
..code-block:: yaml
- hosts: whatever
gather_facts: no
@ -543,7 +555,9 @@ You can add static custom facts by adding static files to facts.d, or add dynami
To use facts.d, create an ``/etc/ansible/facts.d`` directory on the remote host or hosts. If you prefer a different directory, create it and specify it using the ``fact_path`` play keyword. Add files to the directory to supply your custom facts. All file names must end with ``.fact``. The files can be JSON, INI, or executable files returning JSON.
To add static facts, simply add a file with the ``.fact`` extension. For example, create ``/etc/ansible/facts.d/preferences.fact`` with this content::
To add static facts, simply add a file with the ``.fact`` extension. For example, create ``/etc/ansible/facts.d/preferences.fact`` with this content:
..code-block:: ini
[general]
asdf=1
@ -551,22 +565,30 @@ To add static facts, simply add a file with the ``.fact`` extension. For example
..note:: Make sure the file is not executable as this will break the ``ansible.builtin.setup`` module.
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:
..code-block:: shell
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:
"ansible_local": {
..code-block:: json
{
"ansible_local": {
"preferences": {
"general": {
"asdf" : "1",
"bar" : "2"
}
}
}
}
}
The ansible_local namespace separates custom facts created by facts.d from system facts or variables defined elsewhere in the playbook, so variables will not override each other. You can access this custom fact in a template or playbook as::
The ansible_local namespace separates custom facts created by facts.d from system facts or variables defined elsewhere in the playbook, so variables will not override each other. You can access this custom fact in a template or playbook as:
@ -583,7 +605,9 @@ You can also use facts.d to execute a script on the remote host, generating dyna
#. Make sure your script is executable by the Ansible connection user.
#. Gather facts to execute the script and add the JSON output to ansible_local.
By default, fact gathering runs once at the beginning of each play. If you create a custom fact using facts.d in a playbook, it will be available in the next play that gathers facts. If you want to use it in the same play where you created it, you must explicitly re-run the setup module. For example::
By default, fact gathering runs once at the beginning of each play. If you create a custom fact using facts.d in a playbook, it will be available in the next play that gathers facts. If you want to use it in the same play where you created it, you must explicitly re-run the setup module. For example:
..code-block:: yaml
- hosts: webservers
tasks:
@ -614,7 +638,9 @@ You can access information about Ansible operations, including the python versio
The most commonly used magic variables are ``hostvars``, ``groups``, ``group_names``, and ``inventory_hostname``. With ``hostvars``, you can access variables defined for any host in the play, at any point in a playbook. You can access Ansible facts using the ``hostvars`` variable too, but only after you have gathered (or cached) facts.
If you want to configure your database server using the value of a 'fact' from another node, or the value of an inventory variable assigned to another node, you can use ``hostvars`` in a template or on an action line::
If you want to configure your database server using the value of a 'fact' from another node, or the value of an inventory variable assigned to another node, you can use ``hostvars`` in a template or on an action line:
Joshua Ford
3 years ago
committed by