19. Inventories¶

19.1.1. Smart Host Filter¶

You can use a search filter to populate hosts for an inventory. This feature utilized the capability of the fact searching feature.

Facts generated by an Ansible playbook during a Job Template run are stored by the automation controller 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 For example: /api/v2/hosts?host_filter=ansible_facts__ansible_processor_vcpus=8

The host_filter parameter allows for:

• grouping via ()

• use of the boolean and operator:

  • __ to reference related fields in relational fields

  • __ is used on ansible_facts to separate keys in a JSON key path

  • [] is used to denote a json array in the path specification

  • "" can be used in the value when spaces are wanted in the value

• “classic” Django queries may be embedded in the host_filter

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__an

You can search host_filter by host name, group name, and Ansible facts.

The format for a group search is:

groups.name:groupA

The format for a fact search is:

ansible_facts.ansible_fips:false

You can also perform Smart Search searches, which consist a host name and host description.

host_filter=name=my_host

If a search term in host_filter is of string type, to make the value a number (e.g. 2.66), or a JSON keyword (e.g. null, true or false) valid, add double quotations around the value to prevent the controller from mistakenly parsing it as a non-string:

host_filter=ansible_facts__packages__dnsmasq[]__version="2.66"

19.1.2. Define host filter with ansible_facts¶

To use ansible_facts to define the host filter when creating Smart Inventories, perform the following steps:

1. In the Create new smart inventory screen, click the button next to the Smart host filter field to open a pop-up window to filter hosts for this inventory.

2. In the search pop-up window, change the search criteria from Name to Advanced and select ansible_facts from the Key field.

If you wanted to add an ansible fact of

/api/v2/hosts/?host_filter=ansible_facts__ansible_processor[]="GenuineIntel"

In the search field, enter ansible_processor[]="GenuineIntel" (no extra spaces or __ before the value) and press [Enter].

The resulting search criteria for the specified ansible fact populates in the lower part of the window.

3. Click Select to add it to the Smart host filter field.

4. Click Save to save the new Smart Inventory.

The Details tab of the new Smart Inventory opens and displays the specified ansible facts in the Smart host filter field.

5. From the Details view, you can edit the Smart host filter field by clicking Edit and delete existing filter(s), clear all existing filters, or add new ones.

19.2.1. Group name and variables filtering¶

Two different conditions are demonstrated here to describe the input inventory content:

• First condition is that the state variable defined on the host is set to shutdown

• Second condition is membership in a group with account_alias variable set to product_dev

The variable account_alias is used to demonstrate a group variable. In this hypothetical, each account has its own group, with group variables giving metadata about those accounts, which is common in cloud-source inventories. These variables are shown in the general hostvars namespace in Ansible, which is why it has no special treatment in source_vars.

The hosts inside the input inventory will fit one condition, the other condition, neither, or both. This results in four hosts total for demonstration purposes.

This folder defines the inventory as an ini type named two_conditions.ini:

[account_1234]
host1
host2 state=shutdown

[account_4321]
host3
host4 state=shutdown

[account_1234:vars]
account_alias=product_dev

[account_4321:vars]
account_alias=sustaining

The goal here is to return only shutdown hosts that are present in the group with the account_alias variable of product_dev. There are two approaches to this, both shown in yaml format. The first one suggested is recommended.

1. Construct 2 groups, limit to intersection

source_vars:

plugin: constructed
strict: true
groups:
  is_shutdown: state | default("running") == "shutdown"
  product_dev: account_alias == "product_dev"

limit: is_shutdown:&product_dev

This constructed inventory input creates a group for both of the categories and uses the limit (host pattern) to only return hosts that are in the intersection of those two groups, which is documented in host patterns in Ansible.

Also, when a variable may or may not be defined (depending on the host), you can give a default, like with | default("running") if you know what value it should have when it is not defined. This helps with debugging, as described in the Debugging tips section.

2. Construct 1 group, limit to group

source_vars:

plugin: constructed
strict: true
groups:
  shutdown_in_product_dev: state | default("running") == "shutdown" and account_alias == "product_dev"

limit: shutdown_in_product_dev

This input creates one group that only includes hosts that match both criteria. The limit is then just the group name by itself, returning just host2, same as the previous approach.

plugin: constructed
strict: true
groups:
  shutdown_in_product_dev: state | default("running") == "shutdown" and account_alias == "product_dev"
compose:
  resolved_state: state | default("running")
  is_in_product_dev: account_alias == "product_dev"

19.2.2. Nested groups¶

The inventory contents of two groups where one is a child of the other is used here to demonstrate nested groups. The child group has a host inside of it, and the parent group has a variable defined. Due to how Ansible core works, the variable of the parent group will be available in the namespace as a playbook is running, and can be used for filtering.

Define the inventory file in a yaml format named nested.yml:

all:
  children:
    groupA:
      vars:
        filter_var: filter_val
      children:
        groupB:
          hosts:
            host1: {}
    ungrouped:
      hosts:
        host2: {}

The goal here is to filter hosts based on indirect membership in a group (because host1 is in groupB, it is also in groupA).

plugin: constructed

plugin: constructed
strict: true
groups:
  filter_var_is_filter_val: filter_var | default("") == "filter_val"

19.2.3. Ansible facts¶

To create an inventory with Ansible facts, you need to run a playbook against the inventory that has gather_facts: true. The actual facts will differ system-to-system. The following example problems exemplify some example cases and are not intended to address all known scenarios.

plugin: constructed
strict: true
groups:
  hosts_using_xterm: ansible_env.TERM == "xterm"

plugin: constructed
strict: true
groups:
  intel_hosts: "GenuineIntel" in ansible_processor

19.2.4. User interface¶

Follow the procedure described in the subsequent section, Add a new inventory to create a new constructed inventory.

Example of a constructed inventory details view:

19.4.1. Add permissions¶

1. In the Access tab, click the Add button.

2. Select a user or team to add and click Next

3. Select one or more users or teams from the list by clicking the check box(es) next to the name(s) to add them as members and click Next.

In this example, two users have been selected to be added.

4. Select the role(s) you want the selected user(s) or team(s) to have. Be sure to scroll down for a complete list of roles. Different resources have different options available.

5. Click the Save button to apply the roles to the selected user(s) or team(s) and to add them as members.

The Add Users/Teams window closes to display the updated roles assigned for each user and team.

To remove roles for a particular user, click the disassociate (x) button next to its resource.

This launches a confirmation dialog, asking you to confirm the disassociation.

19.4.2. Add groups¶

Inventories are divided into groups, which may contain hosts and other groups, and hosts. Groups are only applicable to standard inventories and is not a configurable directly through a Smart Inventory. You can associate an existing group through host(s) that are used with standard inventories. There are several actions available for standard inventories:

• Create a new Group

• Create a new Host

• Run a command on the selected Inventory

• Edit Inventory properties

• View activity streams for Groups and Hosts

• Obtain help building your Inventory

To create a new group for an inventory:

1. Click the Add button to open the Create Group window.

2. Enter the appropriate details into the required and optional fields:

• Name: Required

• Description: Enter an arbitrary description as appropriate (optional)

• Variables: Enter definitions and values to be applied to all hosts in this group. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

3. When done, click Save.

19.4.2.2. View or edit inventory groups¶

The list view displays all your inventory groups at once, or you can filter it to only display the root group(s). An inventory group is considered a root group if it is not a subset of another group.

You may be able to delete a subgroup without concern for dependencies, since the controller will look for dependencies such as any child groups or hosts. If any exists, a confirmation dialog displays for you to choose whether to delete the root group and all of its subgroups and hosts; or promote the subgroup(s) so they become the top-level inventory group(s), along with their host(s).

19.4.3. Add hosts¶

You can configure hosts for the inventory as well as for groups and groups within groups. To configure hosts:

1. Click the Hosts tab.

2. Click the Add button, and select whether to add a host that already exists in your configuration or create a new host.

3. If creating a new host, select the button to specify whether or not to include this host while running jobs.

4. Enter the appropriate details into the required and optional fields:

• Host Name: Required

• Description: Enter an arbitrary description as appropriate (optional)

• Variables: Enter definitions and values to be applied to all hosts in this group. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

5. When done, click Save.

The Create Host window closes and the newly created host displays as an entry in the list of hosts associated with the group that it was created for.

If you chose to add an existing host, available hosts will appear in a separate selection window.

Once a host is selected, it displays as an entry in the list of hosts associated with the group. You can disassociate a host from this screen by selecting the host and click the Disassociate button.

6. To configure additional groups for the host, click on the name of the host from the list of hosts.

This opens the Details tab of the selected host.

7. Click the Groups tab to configure groups for the host.

1. Click the Add button to associate the host with an existing group.

Available groups appear in a separate selection window.

2. Click to select the group(s) to associate with the host and click Save.

Once a group is associated, it displays as an entry in the list of groups associated with the host.

8. If a host was used to run a job, you can view details about those jobs in the Completed Jobs tab of the host and click Expanded to view details about each job.

19.4.4. Add source¶

Inventory sources are not associated with groups. Spawned groups are top-level and may still have child groups, and all of these spawned groups may have hosts. Adding a source to an inventory only applies to standard inventories. Smart inventories inherit their source from the standard inventories they are associated with. To configure the source for the inventory:

1. In the inventory you want to add a source, click the Sources tab.

2. Click the Add button.

This opens the Create Source window.

3. Enter the appropriate details into the required and optional fields:

• Name: Required

• Description: Enter an arbitrary description as appropriate (optional)

• Execution Environment: Optionally search () or enter the name of the execution environment with which you want to run your inventory imports. Refer to the Execution Environments section for details on building an execution environment.

• Source: Choose a source for your inventory. Refer to the Inventory Sources section for more information about each source and details for entering the appropriate information.

4. After completing the required information for your chosen inventory source, you can continue to optionally specify other common parameters, such as verbosity, host filters, and variables.

Note

The Regions, Instance Filters, and Only Group By fields have been removed in automation controller 3.8.

5. Select the appropriate level of output on any inventory source’s update jobs from the Verbosity drop-down menu.

6. Use the Host Filter field to specify only matching host names to be imported into the controller.

7. In the Enabled Variable, specify the controller to retrieve the enabled state from the given dictionary of host variables. The enabled variable may be specified using dot notation as ‘foo.bar’, in which case the lookup will traverse into nested dicts, equivalent to: from_dict.get('foo', {}).get('bar', default).

8. If you specified a dictionary of host variables in the Enabled Variable field, you can provide a value to enable on import. For example, if enabled_var='status.power_state' and enabled_value='powered_on' with the following host variables, the host would be marked enabled:

{
"status": {
"power_state": "powered_on",
"created": "2020-08-04T18:13:04+00:00",
"healthy": true
},
"name": "foobar",
"ip_address": "192.168.2.1"
}

If power_state were any value other than powered_on, then the host would be disabled when imported into the controller. If the key is not found, then the host will be enabled.

9. All cloud inventory sources have the following update options:

• Overwrite: If checked, any hosts and groups that were previously present on the external source but are now removed, will be removed from the controller inventory. Hosts and groups that were not managed by the inventory source will be promoted to the next manually created group, or if there is no manually created group to promote them into, they will be left in the “all” default group for the inventory.

When not checked, local child hosts and groups not found on the external source will remain untouched by the inventory update process.

• Overwrite Variables: If checked, all variables for child groups and hosts will be removed and replaced by those found on the external source. When not checked, a merge will be performed, combining local variables with those found on the external source.

• Update on Launch: Each time a job runs using this inventory, refresh the inventory from the selected source before executing job tasks. To avoid job overflows if jobs are spawned faster than the inventory can sync, selecting this allows you to configure a Cache Timeout to cache prior inventory syncs for a certain number of seconds.

The “Update on Launch” setting refers to a dependency system for projects and inventory, and it will not specifically exclude two jobs from running at the same time. If a cache timeout is specified, then the dependencies for the second job is created and it uses the project and inventory update that the first job spawned. Both jobs then wait for that project and/or inventory update to finish before proceeding. If they are different job templates, they can then both start and run at the same time, if the system has the capacity to do so. If you intend to use the controller’s provisioning callback feature with a dynamic inventory source, Update on Launch should be set for the inventory group.

If you sync an inventory source that uses a project that has Update On Launch set, then the project may automatically update (according to cache timeout rules) before the inventory update starts.

You can create a job template that uses an inventory that sources from the same project that the template uses. In this case, the project will update and then the inventory will update (if updates are not already in-progress, or if the cache timeout has not already expired).

10. Review your entries and selections and click Save when done. This allows you to configure additional details, such as schedules and notifications.

11. To configure schedules associated with this inventory source, click the Schedules tab.

1. If schedules are already set up; review, edit, or enable/disable your schedule preferences.

2. if schedules have not been set up, refer to Schedules for more information.

Note

The Notifications tab is only present after you save the newly-created source.

12. To configure notifications for the source, click the Notifications tab.

1. If notifications are already set up, use the toggles to enable or disable the notifications to use with your particular source. For more detail, see Enable and Disable Notifications.

2. if notifications have not been set up, refer to Notifications for more information.

13. Review your entries and selections and click Save when done.

Once a source is defined, it displays as an entry in the list of sources associated with the inventory. From the Sources tab you can perform a sync on a single source, or sync all of them at once. You can also perform additional actions such as scheduling a sync process, and edit or delete the source.

$ awx-manage export_custom_scripts --filename=my_scripts.tar
Dump of old custom inventory scripts at my_scripts.tar

$ mkdir my_scripts
$ tar -xf my_scripts.tar -C my_scripts

$ ls my_scripts
_10__inventory_script_rawhook             _19__                                       _30__inventory_script_listenhospital
_11__inventory_script_upperorder          _1__inventory_script_commercialinternet45   _4__inventory_script_whitestring
_12__inventory_script_eastplant           _22__inventory_script_pinexchange           _5__inventory_script_literaturepossession
_13__inventory_script_governmentculture   _23__inventory_script_brainluck             _6__inventory_script_opportunitytelephone
_14__inventory_script_bottomguess         _25__inventory_script_buyerleague           _7__inventory_script_letjury
_15__inventory_script_wallisland          _26__inventory_script_lifesport             _8__random_inventory_script_
_16__inventory_script_wallisland          _27__inventory_script_exchangesomewhere     _9__random_inventory_script_
_17__inventory_script_bidstory            _28__inventory_script_boxchild
_18__p                                    _29__inventory_script_wearstress

$ ./my_scripts/_11__inventory_script_upperorder
{"group_\ud801\udcb0\uc20e\u7b0e\ud81c\udfeb\ub12b\ub4d0\u9ac6\ud81e\udf07\u6ff9\uc17b": {"hosts":
["host_\ud821\udcad\u68b6\u7a51\u93b4\u69cf\uc3c2\ud81f\uddbe\ud820\udc92\u3143\u62c7",
"host_\u6057\u3985\u1f60\ufefb\u1b22\ubd2d\ua90c\ud81a\udc69\u1344\u9d15",
"host_\u78a0\ud820\udef3\u925e\u69da\ua549\ud80c\ude7e\ud81e\udc91\ud808\uddd1\u57d6\ud801\ude57",
"host_\ud83a\udc2d\ud7f7\ua18a\u779a\ud800\udf8b\u7903\ud820\udead\u4154\ud808\ude15\u9711",
"host_\u18a1\u9d6f\u08ac\u74c2\u54e2\u740e\u5f02\ud81d\uddee\ufbd6\u4506"], "vars": {"ansible_host": "127.0.0.1", "ansible_connection":
"local"}}}

$ ansible-inventory -i ./my_scripts/_11__inventory_script_upperorder --list --export

19.4.5. View completed jobs¶

If an inventory was used to run a job, you can view details about those jobs in the Completed Jobs tab of the inventory and click Expanded to view details about each job.