From 11fe4566f8158f231cb7955dc2668138802698e6 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Mon, 12 Aug 2013 09:49:34 -0400 Subject: [PATCH] Document facts.d --- docsite/latest/rst/playbooks.rst | 7 +++--- docsite/latest/rst/playbooks2.rst | 42 +++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/docsite/latest/rst/playbooks.rst b/docsite/latest/rst/playbooks.rst index 22160bd7b0b..19d25680ef7 100644 --- a/docsite/latest/rst/playbooks.rst +++ b/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 `_ - 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 -playbook, and can be used on each system just like explicitly set variables. Ansible provides several +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 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:: diff --git a/docsite/latest/rst/playbooks2.rst b/docsite/latest/rst/playbooks2.rst index cee2a46da59..d14772eb167 100644 --- a/docsite/latest/rst/playbooks2.rst +++ b/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 -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 ````````````