Documentation

4. Inventory File Importing

Ansible Tower 3.2 introduced the ability to choose an inventory file from source control, rather than creating one from scratch. This function is the same as custom inventory scripts, except that the contents are obtained from source control instead of editing their contents browser. This means, the files are non-editable and as inventories are updated at the source, the inventories within the projects are also updated accordingly, including the group_vars and host_vars files or directory associated with them. SCM types can consume both inventory files and scripts, the overlap between inventory files and custom types in that both do scripts.

Note

Inventory updates run with Ansible version 2.8 and later, will use inventory plugins for some source types. These will be ran with options enabled to return the old content as well as the new content (e.g., hostvars, host names, groups). For more detail, refer to the Inventory Plugins section of the Ansible Tower User Guide.

4.1. Custom Dynamic Inventory Scripts

A custom dynamic inventory script stored in version control can be imported and run. This makes it much easier to make changes to an inventory script, rather than having to copy and paste one into Tower, it is pulled directly from source control and then executed. The script must be written to handle any credentials needed for doing its work and you are responsible for installing any Python libraries needed by the script (which is the same requirement for custom dynamic inventory scripts). And this applies to both user-defined inventory source scripts and SCM sources as they are both exposed to Ansible virtualenv requirements related to playbooks.

You can specify environment variables when you edit the SCM inventory source itself. For some scripts, this will be sufficient, however, this is not a secure way to store secret information that gives access to cloud providers or inventory.

The better way is to create a new credential type for the inventory script you are going to use. The credential type will need to specify all the necessary types of inputs. Then, when you create a credential of this type, the secrets will be stored in an encrypted form. If you apply that credential to the inventory source, the script will have access to those inputs like environment variables or files.

For more detail, refer to Credential types.

4.1.1. Update on Project Update

If the inventory source contains static content, it may be desirable to automatically update its content whenever the SHA-1 hash of its source project changes. This can be done by configuring the inventory source to Update on Project Update.

_images/sourced-from-project-update-on-project-update.png

When this box is checked, the inventory source will not allow update-on-launch. Update-on-launch is important because some configurations require it. For example, when you set up a project that the inventory references to update in series before a Job Template runs, so that the inventory that the Job Template runs will have the updated form of that inventory. However, there are two other alternative ways to accomplish this:

  • You can make a job template that uses a project as well as an inventory that updates from that same project. In this case, you can set the project to update_on_launch, in which case it will trigger an inventory update, if needed.

  • If you must use a different project for the playbook than for the inventory source, then you can still place the project in a workflow and then have a job template run on success of the project update.

This is guaranteed to have the inventory update “on time” (meaning that the inventory changes are complete before the job template is launched), because the project does not transition to the completed state until the inventory update is finished.

Note

A failed inventory update does not mark the project as failed. Also, not every project update will trigger a corresponding inventory update. If the project revision has not changed and the inventory has not been edited, the inventory update will not execute.

4.2. SCM Inventory Source Fields

The source fields used are:

  • source_project: project to use

  • source_path: relative path inside the project indicating a directory or a file. If left blank, “” is still a relative path indicating the root directory of the project

  • source_vars: if set on a “file” type inventory source then they will be passed to the environment vars when running

An update of the project automatically triggers an inventory update where it is used. An update of the project is scheduled immediately after creation of the inventory source.

You can specify a location manually in the Tower User Interface from the Create Inventory Source page.

Refer to the Inventories section of the Ansible Tower User Guide for instructions on creating an inventory source.

This listing should be refreshed to latest SCM info on a project update. If no inventory sources use a project as an SCM inventory source, then the inventory listing may not be refreshed on update.

For inventories with SCM sources, starting in Ansible Tower 3.5, the Job Details page for inventory updates show a status indicator for the project update as well as the name of the project. The status indicator links to the project update job. The project name links to the project.

_images/jobs-details-scm-sourced-inventories.png

4.2.1. Supported File Syntax

Ansible Tower uses the ansible-inventory module from Ansible 2.4 and later that supports all valid inventory syntax that Tower requires.

In order to make it configurable on the command line, the option --method is available with the awx-manage inventory_import command. Inventory updates from files will use a backported version of the ansible-inventory command for Ansible versions 2.4 and earlier.

For versions of Ansible 2.4 and later, the officially distributed ansible-inventory command will be used to process inventory files.