ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases 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

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

@ -4,53 +4,47 @@ Developing Dynamic Inventory Sources
.. contents:: Topics .. contents:: Topics
:local: :local:
As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. 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.
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.
.. _inventory_script_conventions: .. _inventory_script_conventions:
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": { "group001": {
"hosts": ["host1.example.com", "host2.example.com"], "hosts": ["host001", "" "host002"],
"vars": { "vars": {
"a": true "var1": true
}
},
"webservers": ["host2.example.com", "host3.example.com"],
"atlanta": {
"hosts": ["host1.example.com", "host4.example.com", "host5.example.com"],
"vars": {
"b": false
}, },
"children": ["marietta", "5points"] "children": ["group002"]
}, },
"marietta": ["host6.example.com"], "group002": {
"5points": ["host7.example.com"] "hosts": ["host003","host004"],
"vars": {
"var2": 500
},
"children":[]
}
} }
.. versionadded:: 1.0 If any of the elements of a group are empty they may be omitted from the output.
Before version 1.0, each group could only have a list of hostnames/IP addresses, like the webservers, marietta, and 5points groups above. 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", "VAR001": "VALUE",
"ntpserver": "wolf.example.com", "VAR002": "VALUE",
"monitoring": "pack.example.com"
} }
Printing variables is optional. If the inventory provider does not do this, it should print an empty hash or dictionary.
.. _inventory_script_tuning: .. _inventory_script_tuning:
Tuning the External Inventory Script Tuning the External Inventory Script
@ -58,14 +52,15 @@ Tuning the External Inventory Script
.. versionadded:: 1.3 .. versionadded:: 1.3
The stock inventory script system detailed above works for all versions of Ansible, but calling The stock inventory script system detailed above works for all versions of
``--host`` for every host can be rather expensive, especially if it involves expensive API calls to Ansible, but calling ``--host`` for every host can be rather inefficient,
a remote subsystem. In Ansible especially if it involves API calls to a remote subsystem. In Ansible 1.3 or
1.3 or later, if the inventory script returns a top level element called "_meta", it is possible later, if the inventory script returns a top level element called "_meta", it
to return all of the host variables in one inventory script call. When this meta element contains is possible to return all of the host variables in one inventory provider call.
a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host. This When this meta element contains a value for "hostvars", the inventory script
results in a significant performance increase for large numbers of hosts, and also makes client will not be invoked with ``--host`` for each host. This results in a
side caching easier to implement for the inventory script. 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:: 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": { "_meta": {
"hostvars": { "hostvars": {
"moocow.example.com": { "host001": {
"asdf" : 1234 "var001" : "value"
}, },
"llama.example.com": { "host002": {
"asdf": 5678 "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:: .. seealso::
:doc:`developing_api` :doc:`developing_api`