From 0c012703c12d80529947fc5908775b97048fce16 Mon Sep 17 00:00:00 2001 From: Joshua Smith Date: Fri, 2 Feb 2018 05:03:17 -0500 Subject: [PATCH] Update developing inventory script docs. (#35639) * Update developing inventory script docs. * Copy edit. --- .../rst/dev_guide/developing_inventory.rst | 96 +++++++++++-------- 1 file changed, 56 insertions(+), 40 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index 1a03f21706b..aa7a0ad21dd 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -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 `` 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 + }, + "children": ["group002"] }, - "webservers": ["host2.example.com", "host3.example.com"], - "atlanta": { - "hosts": ["host1.example.com", "host4.example.com", "host5.example.com"], + "group002": { + "hosts": ["host003","host004"], "vars": { - "b": false + "var2": 500 }, - "children": ["marietta", "5points"] - }, - "marietta": ["host6.example.com"], - "5points": ["host7.example.com"] + "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 `` (where 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 `` (where 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`