prefer ansible_facts namespace and dict notation (#44980)

* prefer ansible_facts namespace and dict notation

* fixed mistranslation

1 files changed, 18 insertions, 12 deletions

diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst
index 4328e04765..c1433d0ed0 100644
--- a/docs/docsite/rst/user_guide/playbooks_variables.rst
+++ b/docs/docsite/rst/user_guide/playbooks_variables.rst
@@ -161,11 +161,17 @@ Information discovered from systems: Facts
 
 There are other places where variables can come from, but these are a type of variable that are discovered, not set by the user.
 
-Facts are information derived from speaking with your remote systems.
+Facts are information derived from speaking with your remote systems. You can find a complete set under the ``ansible_facts`` variable,
+most facts are also 'injected' as top level variables preserving the ``ansible_`` prefix, but some are dropped due to conflicts.
+This can be disabled via the :ref:INJECT_FACTS_AS_VARS setting.
 
 An example of this might be the IP address of the remote host, or what the operating system is.
 
-To see what information is available, try the following::
+To see what information is available, try the following in a play::
+
+    - debug: var=ansible_facts
+
+To see the 'raw' information as gathered::
 
     ansible hostname -m setup
 
@@ -406,15 +412,15 @@ This will return a large amount of variable data, which may look like this, as t
 
 In the above the model of the first harddrive may be referenced in a template or playbook as::
 
-    {{ ansible_devices.sda.model }}
+    {{ ansible_facts['devices']['sda']['model'] }}
 
 Similarly, the hostname as the system reports it is::
 
-    {{ ansible_nodename }}
+    {{ ansible_facts['nodename'] }}
 
 and the unqualified hostname shows the string before the first period(.)::
 
-    {{ ansible_hostname }}
+    {{ ansible_facts['hostname'] }}
 
 Facts are frequently used in conditionals (see :doc:`playbooks_conditionals`) and also in templates.
 
@@ -475,11 +481,11 @@ And you will see the following fact added::
 
 And this data can be accessed in a ``template/playbook`` as::
 
-     {{ ansible_local.preferences.general.asdf }}
+     {{ ansible_local['preferences']['general']['asdf'] }}
 
 The local namespace prevents any user supplied fact from overriding system facts or variables defined elsewhere in the playbook.
 
-.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local.preferences.general.xyz }}`` and not ``{{ ansible_local.preferences.general.XYZ }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lower case.
+.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local['preferences']['general']['xyz'] }}`` and not ``{{ ansible_local['preferences']['general']['XYZ'] }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lower case.
 
 .. _ConfigParser: https://docs.python.org/2/library/configparser.html
 .. _optionxform: https://docs.python.org/2/library/configparser.html#ConfigParser.RawConfigParser.optionxform
@@ -526,7 +532,7 @@ Fact Caching
 
 As shown elsewhere in the docs, it is possible for one server to reference variables about another, like so::
 
-    {{ hostvars['asdf.example.com']['ansible_os_family'] }}
+    {{ hostvars['asdf.example.com']['ansible_facts']['os_family'] }}
 
 With "Fact Caching" disabled, in order to do this, Ansible must have already talked to 'asdf.example.com' in the
 current play, or another play up higher in the playbook.  This is the default configuration of ansible.
@@ -615,11 +621,11 @@ We already described facts a little higher up in the documentation.
 Some provided facts, like networking information, are made available as nested data structures.  To access
 them a simple ``{{ foo }}`` is not sufficient, but it is still easy to do.   Here's how we get an IP address::
 
-    {{ ansible_eth0["ipv4"]["address"] }}
+    {{ ansible_facts["eth0"]["ipv4"]["address"] }}
 
 OR alternatively::
 
-    {{ ansible_eth0.ipv4.address }}
+    {{ ansible_facts.eth0.ipv4.address }}
 
 Similarly, this is how we access the first element of an array::
 
@@ -641,7 +647,7 @@ or set of playbooks, you can still get the variables, but you will not be able t
 If your database server wants to use the value of a 'fact' from another node, or an inventory variable
 assigned to another node, it's easy to do so within a template or even an action line::
 
-    {{ hostvars['test.example.com']['ansible_distribution'] }}
+    {{ hostvars['test.example.com']['ansible_facts']['distribution'] }}
 
 Additionally, ``group_names`` is a list (array) of all the groups the current host is in.  This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host
 
@@ -666,7 +672,7 @@ A frequently used idiom is walking a group to find all IP addresses in that grou
 .. code-block:: jinja
 
    {% for host in groups['app_servers'] %}
-      {{ hostvars[host]['ansible_eth0']['ipv4']['address'] }}
+      {{ hostvars[host]['ansible_facts']['eth0']['ipv4']['address'] }}
    {% endfor %}
 
 An example of this could include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.