Documentation homepage Last update: Sep 22, 2021

Inventory Refresh Overview

AWX should have an inventory view that is more aligned towards systems management rather than merely maintaining inventory for automation.

Inventory Source Promotion

Starting with Tower 3.2, InventorySource will be associated directly with an Inventory.

Fact Searching

Facts generated by an Ansible playbook during a Job Template run are stored by AWX into the database whenever use_fact_cache=True is set per-Job-Template. New facts are merged with existing facts and are per-host. These stored facts can be used to filter hosts via the /api/v2/hosts endpoint, using the GET query parameter host_filter i.e., /api/v2/hosts?host_filter=ansible_facts__ansible_processor_vcpus=8

The grammar of host_filter allows for:

Examples:

/api/v2/hosts/?host_filter=name=localhost
/api/v2/hosts/?host_filter=ansible_facts__ansible_date_time__weekday_number="3"
/api/v2/hosts/?host_filter=ansible_facts__ansible_processor[]="GenuineIntel"
/api/v2/hosts/?host_filter=ansible_facts__ansible_lo__ipv6[]__scope="host"
/api/v2/hosts/?host_filter=ansible_facts__ansible_processor_vcpus=8
/api/v2/hosts/?host_filter=ansible_facts__ansible_env__PYTHONUNBUFFERED="true"
/api/v2/hosts/?host_filter=(name=localhost or name=database) and (groups__name=east or groups__name="west coast") and ansible_facts__ansible_processor_vcpus=8

Smart Inventory

Starting in Tower 3.2, Tower will support the ability to define a Smart Inventory. Users will define the inventories using the same language that is currently supported in Smart Search.

Inventory Changes

Smart Filter (host_filter)

The SmartFilter class handles our translation of the smart search string. We store the filter value in the host_filter field for an inventory. This value should be expressed the same way for existing smart searches.

host_filter="search=foo"
host_filter="group__search=bar"
host_filter="search=baz and group__search=bang"
host_filter="name=localhost or group__name=local"

Creating a new Smart Inventory for all of our GCE and EC2 groups might look like this:

HTTP POST /api/v2/inventories/

{
    "name": "GCE and EC2 Smart Inventory",
    "kind": "smart",
    "host_filter": "group__search=ec2 and group__search=gce"
    ...
}

More On Searching

The host_filter that is set will search over the entirety of the hosts the user has access to in AWX. If the user wants to restrict their search in anyway, they will want to declare that in their host filter.

For example, if wanting to restrict the search to only hosts in an inventory named "US-East", create a host_filter that looks something like this:

{
    "name": "NYC Hosts",
    "kind": "smart",
    "host_filter": "inventory__name='US-East' and search='nyc'",
    ...
}

In the above example, the search is limited to the "US-East" inventory and hosts with a name containing "nyc".

Acceptance Critera

When verifying acceptance, ensure the following statements are true: ``

API Concerns

There are no breaking or backwards-incompatible changes for this feature.

Other Changes

Inventory Updates All inventory_sources

A new endpoint /api/v2/inventories/:id/update_inventory_sources has been added. This endpoint functions in the same way that /api/v2/inventory_source/:id/update functions for a single InventorySource with the exception that it updates all of the inventory sources for the Inventory.

HTTP GET /api/v2/inventories/:id/update_inventory_sources will list all of the inventory sources and whether or not they will be updated when a POST to the same endpoint is made. The result of this request will look like this:

{
    results: [
        "inventory_source": 1, "can_update": True,
        "inventory_source": 2, "can_update": False,
    ]
}

Note: All manual inventory sources (source='') will be ignored by the update_inventory_sources endpoint.

When making a POST to the same endpoint, the response will contain a status as well as the job ID for the update:

POST /api/v2/inventories/:id/update_inventory_sources

{
    results: [
        "inventory_update": 20, "inventory_source": 1, "status": "started",
        "inventory_update": 21, "inventory_source": 2, "status": "Could not start because `can_update` returned False"
    ]
}

The response code from this action will be:

Background Deletion of Inventory

If a DELETE request is submitted to an inventory, the field pending_delete will be True until a separate task fully completes the task of deleting the inventory and all its contents.