Document facts.d

docsite/latest/rst/playbooks.rst

@@ -155,11 +155,12 @@ If just referencing the value of another simple variable though, it's fine to sa
 
 To learn more about Jinja2, you can optionally see the `Jinja2 docs <http://jinja.pocoo.org/docs/>`_ - though remember that Jinja2 loops and conditionals are only for 'templates' in Ansible, in playbooks, ansible has the 'when' and 'with' keywords for conditionals and loops.
 
-If there are discovered variables about the system, called 'facts', these variables bubble up back into the
+If there are discovered variables about the system, called 'facts', these variables bubble up back into the playbook, and can be used on each system just like explicitly set variables.  Ansible provides several
-playbook, and can be used on each system just like explicitly set variables.  Ansible provides several
 of these, prefixed with 'ansible', which are documented under 'setup' in the module documentation.  Additionally,
 facts can be gathered by ohai and facter if they are installed.  Facter variables are prefixed with ``facter_`` and Ohai variables are prefixed with ``ohai_``.  These add extra dependencies and are only there for ease of users
-porting over from those other configuration systems.
+porting over from those other configuration systems.  Finally, it's possible to drop files
+on to the remote systems that provide additional sources of fact data, see "Facts.d" as documented
+in the Advanced Playbooks section.
 
 How about an example.  If I wanted to write the hostname into the /etc/motd file, I could say::
 

docsite/latest/rst/playbooks2.rst

@@ -1098,6 +1098,48 @@ Which of course means that, though more verbose, this is also legal syntax::
     - name: foo
       template: { src: '/templates/motd.j2', dest: '/etc/motd' }
 
+Local Facts (Facts.d)
+`````````````````````
+
+.. version_added:: 1.3
+
+As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables.
+Usually these are discovered automatically by the 'setup' module in Ansible. Users can also write custom facts modules, as described
+in the API guide.  However, what if you want to have a simple way to provide system or user 
+provided data for use in Ansible variables, without writing a fact module?  For instance, what if you want users to be able to control some aspect about how their systems are managed? "Facts.d" is one such mechanism.
+
+If a remotely managed system has an "/etc/ansible/facts.d" directory, any files in this directory
+ending in ".fact", can be JSON, INI, or executable files returning JSON, and these can supply local facts in Ansible.
+
+For instance assume a /etc/ansible/facts.d/preferences.fact::
+
+    [general]
+    asdf=1
+    bar=2
+
+This will produce 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"
+
+And you will see the following fact added::
+
+    "ansible_local": {
+            "preferences": {
+                "general": {
+                    "asdf" : "1", 
+                    "bar"  : "2"
+                }
+            }
+     }
+
+And this data can be accessed in a template/playbook as::
+
+     {{ ansible_local.preferences.general.asdf }}
+
+The local namespace prevents any user supplied fact from overriding system facts
+or variables defined elsewhere in the playbook.
+
 Style Points
 ````````````