cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update developing inventory script docs. (#35639)

Browse source 
* Update developing inventory script docs.

* Copy edit.
This commit is contained in:
Joshua Smith 2018-02-02 05:03:17 -05:00 committed by scottb
parent 25a83a4ac8
commit 0c012703c1
1 changed files with 57 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
docs/docsite/rst/dev_guide/developing_inventory.rst
View file

@ -4,53 +4,47 @@ Developing Dynamic Inventory Sources
.. contents:: Topics
:local:
As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources.
How do we write a new one?
Simple! We just create a script or program that can print JSON in the right format when fed the proper arguments.
You can do this in any language.
As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider.
.. _inventory_script_conventions:
Script Conventions
``````````````````
When the external node script is called with the single argument ``--list``, the script must output a JSON encoded hash/dictionary of all the groups to be managed to stdout. Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or simply a list of host/IP addresses, like so::
Dynamic inventory providers must accept the ``--list`` and ``--host <hostname>`` arguments.
When the dynamic inventory provider is called with the single argument ``--list``, the script must output to stdout a JSON-encoded hash or dictionary containing all of the groups to be managed. Each group's value should be either a hash or dictionary containing a list of each host, any child groups, and potential group variables, or simply a list of hosts::
{
"databases": {
"hosts": ["host1.example.com", "host2.example.com"],
"group001": {
"hosts": ["host001", "" "host002"],
"vars": {
"a": true
}
"var1": true
},
"webservers": ["host2.example.com", "host3.example.com"],
"atlanta": {
"hosts": ["host1.example.com", "host4.example.com", "host5.example.com"],
"children": ["group002"]
},
"group002": {
"hosts": ["host003","host004"],
"vars": {
"b": false
"var2": 500
},
"children": ["marietta", "5points"]
},
"marietta": ["host6.example.com"],
"5points": ["host7.example.com"]
"children":[]
}
.. versionadded:: 1.0
}
Before version 1.0, each group could only have a list of hostnames/IP addresses, like the webservers, marietta, and 5points groups above.
If any of the elements of a group are empty they may be omitted from the output.
When called with the argument ``--host <hostname>`` (where <hostname> is a host from above), the script must print either an empty JSON hash/dictionary, or a hash/dictionary of variables to make available to templates and playbooks. For example::
When called with the arguments ``--host <hostname>`` (where <hostname> is a host from above), the script must print either an empty JSON
hash/dictionary, or a hash/dictionary of variables to make available to templates and playbooks. Printing variables is optional,
if the script does not wish to do this, printing an empty hash/dictionary is the way to go::
{
"favcolor": "red",
"ntpserver": "wolf.example.com",
"monitoring": "pack.example.com"
"VAR001": "VALUE",
"VAR002": "VALUE",
}
Printing variables is optional. If the inventory provider does not do this, it should print an empty hash or dictionary.
.. _inventory_script_tuning:
Tuning the External Inventory Script
@ -58,14 +52,15 @@ Tuning the External Inventory Script
.. versionadded:: 1.3
The stock inventory script system detailed above works for all versions of Ansible, but calling
``--host`` for every host can be rather expensive, especially if it involves expensive API calls to
a remote subsystem. In Ansible
1.3 or later, if the inventory script returns a top level element called "_meta", it is possible
to return all of the host variables in one inventory script call. When this meta element contains
a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host. This
results in a significant performance increase for large numbers of hosts, and also makes client
side caching easier to implement for the inventory script.
The stock inventory script system detailed above works for all versions of
Ansible, but calling ``--host`` for every host can be rather inefficient,
especially if it involves API calls to a remote subsystem. In Ansible 1.3 or
later, if the inventory script returns a top level element called "_meta", it
is possible to return all of the host variables in one inventory provider call.
When this meta element contains a value for "hostvars", the inventory script
will not be invoked with ``--host`` for each host. This results in a
significant performance increase for large numbers of hosts, and also makes
client-side caching easier to implement for the inventory provider.
The data to be added to the top level JSON dictionary looks like this::
@ -76,17 +71,17 @@ The data to be added to the top level JSON dictionary looks like this::
"_meta": {
"hostvars": {
"moocow.example.com": {
"asdf" : 1234
"host001": {
"var001" : "value"
},
"llama.example.com": {
"asdf": 5678
"host002": {
"var002": "value"
}
}
}
}
To satisfy the requirements of using ``_meta``, to prevent ansible from calling your inventory with ``--host`` you must at least populate ``_meta`` with an empty ``hostvars`` dictionary, such as::
To satisfy the requirements of using ``_meta``, to prevent ansible from calling your inventory with ``--host`` you must at least populate ``_meta`` with an empty ``hostvars`` dictionary. For example::
{
@ -98,6 +93,27 @@ To satisfy the requirements of using ``_meta``, to prevent ansible from calling
}
}
.. _replacing_inventory_ini_with_dynamic_provider:
If you intend to replace an existing inventory ini file with a dynamic provider,
it must return a JSON object which contains an 'all' group that includes every
host in the inventory as a member and every group in the inventory as a child.
It should also include an 'ungrouped' group which contains all hosts which are not members of
any other group. A skeleton example of this JSON object is::
{
"_meta": {
"hostvars": {}
},
"all": {
"children": [
"ungrouped"
]
},
"ungrouped": {}
}
.. seealso::
:doc:`developing_api`