Documentation

11. Inventories

An Inventory is a collection of hosts against which jobs may be launched, the same as an Ansible inventory file. Inventories are divided into groups and these groups contain the actual hosts. Groups may be sourced manually, by entering host names into Tower, or from one of Ansible Tower’s supported cloud providers.

Note

If you have a custom dynamic inventory script, or a cloud provider that is not yet supported natively in Tower, you can also import that into Tower. Refer to the Tower Administration Guide.

This tab displays a list of the inventories that are currently available. The inventory list may be sorted and searched by Name or Organization. This list may also be filtered by selecting Cloud Sourced, Failed Hosts, or Sync Failures.

Inventories - home with examples

The list of Inventory details includes:

  • Inventory Sync: If configured, you can “Sync” to fetch the project details from the configured source control.

  • Status Dot: This shows the status of recent jobs for this inventory.

  • Name: The inventory name. Clicking the Inventory name navigates to the properties screen for the selected inventory, which shows the inventory’s groups and hosts. (This view is also accessible from the Action menu.)

  • Organization: The organization to which the inventory belongs.

  • Actions: The following actions are available for the selected inventory:

    • Edit: Edit the properties for the selected inventory
    • Delete: Delete the selected inventory. This operation cannot be reversed!

11.1. Add a new inventory

To create a new inventory click the add button, which opens the Create Inventory window.

Inventories_create_new - create new inventory

Enter the appropriate details into the following fields and select Save:

  • Name: Enter a name appropriate for this inventory.
  • Description: Enter an arbitrary description as appropriate.
  • Organization: Choose among the available organizations.
  • Variables: Variable definitions and values to be applied to all hosts in this inventory. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

Inventories_create_new_saved - create new inventory

After clicking save, the Groups and Hosts Management screen appears.

Inventories_manage_grouphost - new inventory group host manage

11.2. Groups and Hosts

Inventories are divided into groups, which may contain hosts and other groups, and hosts. There are several actions available for 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

11.2.1. Groups

Under Groups, you can view which groups belong to this inventory, easily filtered or searched by group name.

Additional actions may be performed on the group by selecting the buttons to the right of the group name:

  • Sync status: Show the status of inventory synchronization for groups configured with cloud sources. If synchronization is configured, clicking this button shows the synchronization log for the selected group.
  • Host status: Show the status of successful and failed jobs for the selected group. Clicking this button shows the list of hosts that are members of the selected group.
  • Start sync process: Initiate a synchronization of the group with the configured cloud source. (A synchronization process that is in progress may be canceled by clicking the cancel button that appears here during synchronization.)
  • Edit Group: Edit the properties for the selected group
  • Copy Group: Groups can be nested. This allows you to copy or move the group to a different group.
  • Delete: Delete the selected group. This operation cannot be reversed!

11.2.1.1. Add a new group

Create a new group for an inventory by clicking the add group button button, which opens the Create Group window.

Inventories_manage_group_add

Enter the appropriate details into the required and optional fields, and click Save.

  • Name: Required
  • Description: Enter an arbitrary description as appropriate
  • Source: Choose a source which matches the credential type against which a host can be entered.
  • 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.

In prior versions of Ansible Tower, the Source default was manual, meaning that the hosts must be entered into Tower manually. Beginning with Ansible Tower 3.0, host can be added via multiple methods/credential sources. (Refer to Add a new host for more information on managing hosts individually.)

To synchronize the inventory group from a cloud source, choose the appropriate source from the Source menu.

Note

Starting with version 2.2, Ansible Tower supports Amazon Web Services EC2, Rackspace Cloud Servers, Google Compute Engine, VMware vCenter, Microsoft Azure, OpenStack, and custom scripts added by the administrator. With Ansible Tower version 3.0, Microsoft Azure Classic (deprecated) and Microsoft Azure Resource Manager were added to expand upon the support offered for Microsoft Azure, and support for Red Hat Satellite 6 and RH Cloudforms credentials were also added.

All cloud inventory sources have the following update options:

  • Overwrite: When checked all child groups and hosts not found on the remote source are deleted from the local inventory. When not checked any local child hosts and groups not found on the external source remains 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 is 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.

Note

If you intend to use Tower’s provisioning callback feature with a dynamic inventory source, “Update on Launch” should be set for the inventory group.

When done, click Save.

Inventories_manage_group_add-saved

11.2.1.2. Credential Sources

Choose a source which matches the credential type against which a host can be entered.

11.2.1.2.1. Rackspace Cloud Servers

To configure a group for Rackspace, select Rackspace Cloud Servers and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • Regions: Click on the regions field to see a list of regions for your cloud provider. You can select multiple regions, or choose “All” to include all regions. Tower will only be updated with Hosts associated with the selected regions.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create Rackspace group for example inventory

11.2.1.2.2. Amazon Web Services EC2

To configure a group for AWS, select Amazon EC2 and enter the following details:

Inventories - create AWS group for example inventory

  • Cloud Credential: Choose from an existing credential (for more information, refer to Credentials).

    If Tower is running on an EC2 instance with an assigned IAM Role, the credential may be omitted, and the security credentials from the instance metadata will be used instead. For more information on using IAM Roles, refer to the IAM_Roles_for_Amazon_EC2_documentation_at_Amazon.

  • Regions: Click on the regions field to see a list of regions for your cloud provider. You can select multiple regions, or choose “All” to include all regions. Tower will only be updated with Hosts associated with the selected regions.

  • Instance Filters: Rather than importing your entire Amazon EC2 inventory, filter the instances returned by the inventory script based on a variety of metadata. Hosts are imported if they match any of the filters entered here.

    Examples:

    • To limit to hosts having the tag TowerManaged: Enter tag-key=TowerManaged
    • To limit to hosts using either the key-name staging or production: Enter key-name=staging, key-name=production
    • To limit to hosts where the Name tag begins with test: Enter tag:Name=test*

    For more information on the filters that can be used here, refer to the Describe Instances documentation at Amazon.

  • Only Group By: By default, Tower creates groups based on the following Amazon EC2 parameters:

    • Availability Zones
    • Image ID
    • Instance Type
    • Key Name
    • Region
    • Security Group
    • Tags (by name)
    • VPC ID

    If you do not want all these groups created, select from the dropdown the list of groups that you would like created by default. You can also select Instance ID to create groups based on the Instance ID of your instances.

  • 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.

  • Source Variables: Override variables found in ec2.ini and used by the inventory update script. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables view ec2.ini in the Ansible GitHub repo.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.
11.2.1.2.3. Google Compute Engine

To configure a group for Google Compute Engine, select Google Compute Engine and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • Regions: Click on the regions field to see a list of regions for your cloud provider. You can select multiple regions, or choose “All” to include all regions. Tower will only be updated with Hosts associated with the selected regions.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create GCE group for example inventory

11.2.1.2.4. Microsoft Azure Classic (deprecated)

To configure a group for Microsoft Azure Classic, select Microsoft Azure Classic (deprecated) and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • Regions: Click on the regions field to see a list of regions for your cloud provider. You can select multiple regions, or choose “All” to include all regions. Tower will only be updated with Hosts associated with the selected regions.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create Azure group for example inventory

11.2.1.2.5. Microsoft Azure Resource Manager

To configure a group for Microsoft Azure Resource Manager, select Microsoft Azure Resource Managee and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • Regions: Click on the regions field to see a list of regions for your cloud provider. You can select multiple regions, or choose “All” to include all regions. Tower will only be updated with Hosts associated with the selected regions.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create Azure Resource Manager group for example inventory

11.2.1.2.6. VMware vCenter

To configure a group for VMware vCenter, select VMware and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • 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.
  • Source Variables: Override variables found in vmware.ini and used by the inventory update script. For a detailed description of these variables view vmware.ini in the Ansible GitHub repo. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create VMware group for example inventory

11.2.1.2.7. Red Hat Satellite 6

To configure a group for Red Hat Satellite 6, select Red Hat Satellite 6 and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create RHSat6 group for example inventory

11.2.1.2.8. Red Hat CloudForms

To configure a group for Red Hat CloudForms, select Red Hat CloudForms and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • 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.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create RHCloudForm group for example inventory

11.2.1.2.9. OpenStack

To configure a group for OpenStack, select OpenStack and enter the following details:

  • Cloud Credential: Choose from an existing Credential. For more information, refer to Credentials.
  • 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.
  • Source Variables: Override variables found in openstack.yml and used by the inventory update script. For a detailed description of these variables view openstack.yml in the Ansible GitHub repo. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create OpenStack group for example inventory

11.2.1.2.10. Custom Script

Tower allows you to use a custom dynamic inventory script, if your administrator has added one.

To configure a group to use a Custom Inventory Script, select Custom Script and enter the following details:

  • Custom Inventory Script: Choose from an existing Inventory Script.

  • Environment Variables: Set variables in the environment to be used by the inventory update script. The variables would be specific to the script that you have written.

    Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.

You can also configure Update Options.

  • Overwrite: If checked, all child groups and hosts not found on the external source are deleted from the local inventory. When not checked, local child hosts and groups not found on the external source remain untouched by the inventory update process.
  • Overwrite Variables: If checked, all variables for child groups and hosts are removed and replaced by those found on the external source. When not checked, a merge is 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.

Inventories - create custom group for example inventory

For more information on syncing or using custom inventory scripts, refer to Custom Inventory Scripts in the Ansible Tower Administration Guide.

11.2.1.3. Scheduling

For groups sourced from a cloud service, the inventory update process may be scheduled via the Schedule view. To access the Schedule view, click the Schedule (schedule-button) button beside the Inventory Group name to open the Edit Group dialog.

inventories-edit-group-edit

This screen displays a list of the schedules that are currently available for the selected Group. The schedule list may be sorted and searched by Name.

inventories-edit-group-schedule

The list of schedules includes:

  • Name (Clicking the schedule name opens the Edit Schedule dialog)
  • First Run
  • Next Run

Buttons located in the upper right corner of the Schedules screen provide the following actions:

  • Create a new schedule
  • Refresh this view
11.2.1.3.1. Add a new schedule

To create a new schedule click the add button.

Group - create new schedule

Enter the appropriate details into the following fields and select Save:

  • Name (required)
  • Start Date (required)
  • Start Time (required)
  • Local Time Zone (the entered Start Time should be in this timezone)
  • Repeat Frequency (the appropriate options are displayed as the update frequency is modified)
  • None
_images/inventories-edit-group-schedule-none.png
  • Minute, Hour, or Day
_images/inventories-edit-group-schedule-minute.png
  • Week
_images/inventories-edit-group-schedule-week.png
  • Month
_images/inventories-edit-group-schedule-month.png
  • Year
_images/inventories-edit-group-schedule-year.png

The Schedule Description panel displays an detailed overview of the schedule and a list of the scheduled occurrences in the selected Local Time Zone or in UTC (be sure to select Local Time or UTC as based on your needs).

Note

When using UTC time settings, repeating jobs that runs at a specific time of day may move relative to a local timezone when Daylight Saving Time shifts occur.

Once you have saved the schedule, it can be viewed by clicking on the Schedule (schedule-button) tab beside the group name.

Inventories - group with example schedule

There are server actions available for schedules:

  • ON/OFF – Stop an active schedule or activate a stopped schedule by using the toggle button.
  • Edit schedule
  • Delete schedule

11.2.2. Hosts

Hosts are listed on the right side of the Inventory display screen.

Inventories - hosts list for example group

The host list may be sorted and searched by Name or Groups, and filtered by hosts that are disabled, by hosts with failed jobs, and by hosts synchronized with an external source.

This list displays information about each host and provides for several actions:

  • ON/OFF Indicates whether a host is available and should be included in running jobs. For hosts that are part of an external inventory, this flag is set by the inventory sync process and cannot be manually changed.
  • Name: Opens the Host Properties dialog
  • Available: A toggle indicating whether the host is enabled to receive jobs from Tower. Click to toggle this setting.
  • Jobs: Shows the most recent Jobs run against this Host. Clicking this button displays a window showing the most recent jobs and their status.
  • Edit host: Opens the Host Properties dialog
  • Copy host: Copies or moves the host to a different group
  • Delete: Removes the host from Tower. This operation is not reversible!

11.2.2.1. Add a new host

Hosts can be added manually, by IP address, or hostname. Tower can also sync inventory directly from AWS EC2, Google Compute Engine, MS Azure, VMware, Rackspace Open Cloud, or OpenStack.

To create a new host and add it to an existing group, click the add host button button.

This opens the Create New Host dialog.

Inventories - create new host for example group

Enter the appropriate details into the following fields and click Save:

  • Host Name: The hostname or IP address of the host
  • Description: Enter an arbitrary description as appropriate
  • Enabled?: Indicates if a host is available and should be included in running jobs. For hosts that are part of an external inventory, this flag cannot be changed. It is set by the inventory sync process.
  • Variables: Variable definitions and values to be applied to the selected host. Enter variables using either JSON or YAML syntax, using the radio button to toggle between JSON or YAML.

11.3. Running Ad Hoc Commands

To run an ad hoc command, first select an inventory source. The inventory source can be a single group or host, a selection of multiple hosts, or a selection of multiple groups.

ad hoc-commands-inventory-home

Then, click the adhoc button.

_images/ad-hoc-run-command-empty.png

Enter the details for the following fields:

  • Module: Select one of the modules that Tower supports running commands against.

    command apt_repository mount win_service
    shell apt_rpm ping win_updates
    yum service selinux win_group
    apt group setup win_user
    apt_key user win_ping

  • Arguments: Provide arguments to be used with the module you selected.

  • Host Pattern: Enter the pattern used to target hosts in the inventory. To target all hosts in the inventory enter all or *, or leave the field blank. This is automatically populated with whatever was selected in the previous view prior to clicking the launch button.

  • Machine Credential: Select the credential to use when accessing the remote hosts to run the command. Choose the credential containing the username and SSH key or password that Ansbile needs to log into the remote hosts.

  • Enable Privilege Escalation: If enabled, the playbook is run with administrator privileges. This is the equivalent of passing the --become option to the ansible command.

  • Verbosity: Select a verbosity level for the standard output.

  • Forks: If needed, select the number of parallel or simultaneous processes to use while executing the command.

Click the launch button to run this ad hoc command.

ad hoc-commands-inventory-run-command

11.4. System Tracking

Note

System Tracking, introduced as a new feature in Ansible Tower 2.2, is only available to those with Enterprise-level licenses.

System Tracking offers the ability to compare the results of two scan runs from different dates on one host or the same date on two hosts.

Data is grouped by fact modules:

  • Packages
  • Services
  • Files
  • Ansible
  • Custom

Tower is designed to make every attempt to find your data. If you select a date without any scan runs, Tower gathers the previous year’s worth of scan runs to verify possible data to include. Successful comparisons display results from the available dates instead of the specified dates. Unsuccessful comparisons display a message indicating why they did not work.

Note

Service scan jobs should not run against an inventory with hosts that point to the same physical machine.

11.4.1. Single Host Workflow

Select a single host in an inventory to compare against two dates and click the system-tracking button.

select one host to compare

Note

If you have not already created a job template set to scan, you will not be able to proceed until the correct job template has been created.

Select two dates on which you have scan data for the host, with the earliest date to compare on the left and the latest date to compare on the right.

select one host two dates

Select the module (Packages, Services, or Ansible) for which you want to compare differences. To change modules, click on the module button with the button navigation to filter by different types of facts. Note that differences among the “ansible” and “files” modules changes are highlighted in red, while only changes for “packages” and “services” are shown.

You may also choose the same date in both date selectors if you want to compare multiple scan runs against a single date. If two or more scan jobs runs are discovered on a particular day, Tower compares the most recent and the second-most recent. If there is only one run for the selected date, Tower may display a message saying it could not find any scan job runs in one of the columns. (Also noted in Known Issues in the Ansible Tower Release Notes manual.)

select one host one date module expanded

Please note that if the scans found for the selected date are identical, Tower displays a single result of all facts scanned.

As an example, say that a user selects “7/7/2015” for both dates and selects the “packages” module. And say that two runs occurred on this date, but there were no changes to packages on the selected host. The user sees a message indicating the scans were identical as well as a single column containing all package versions, instead of a two-column listing of differences.

_images/system-tracking-one-date-identical-scan.png

11.4.2. Host to Host Workflow

To compare two hosts, select the hosts and click the system-tracking button.

select two hosts to compare

Select a single date on which to compare the two hosts. Next, select the module for which you want to view differences.

select two hosts scanned

Although Tower only supports picking a single date for both hosts, you may notice different dates in the results. Remember that Tower is designed to make every attempt to find your data. If a date is selected without any scan runs, Tower gathers the previous year’s worth of scan runs to verify possible data to include. Note that differences among the “ansible” and “files” modules changes are highlighted in red, while only changes for “packages” and “services” are shown.

select two hosts scanned expanded