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. 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 `````````````````` 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:: { "group001": { "hosts": ["host001", "" "host002"], "vars": { "var1": true }, "children": ["group002"] }, "group002": { "hosts": ["host003","host004"], "vars": { "var2": 500 }, "children":[] } } If any of the elements of a group are empty they may be omitted from the output. 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:: { "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 ```````````````````````````````````` .. 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 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:: { # results of inventory script as above go here # ... "_meta": { "hostvars": { "host001": { "var001" : "value" }, "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. For example:: { # results of inventory script as above go here # ... "_meta": { "hostvars": {} } } .. _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` Python API to Playbooks and Ad Hoc Task Execution :doc:`developing_modules` How to develop modules :doc:`developing_plugins` How to develop plugins `Ansible Tower `_ REST API endpoint and GUI for Ansible, syncs with dynamic inventory `Development Mailing List `_ Mailing list for development topics `irc.freenode.net `_ #ansible IRC chat channel