As described in Working With 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.
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.
New in version 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": {}
}
See also