ansible/docs/docsite/rst/dev_guide/developing_inventory.rst

Developing Dynamic Inventory Sources

Topics

As described in 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.

Script Conventions

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:

{
    "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 <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:

{
    "VAR001": "VALUE",
    "VAR002": "VALUE",
}

Printing variables is optional. If the inventory provider does not do this, it should print an empty hash or dictionary.

Tuning the External Inventory Script

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": {}
    }
}

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": {}
}

developing_api

Python API to Playbooks and Ad Hoc Task Execution

developing_modules

How to develop modules

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