10. Inventories¶

10.2.3.1. Fact Scan Playbook¶

The scan_facts.yml playbook contains invocations of, potentially, multiple file fact scan modules. The default playbook bundled with Tower invokes four (4) fact scan modules–ansible, packages, services, and files. The scan_facts.yml playbook file looks like the following:

- hosts: all
  vars:
    scan_use_checksum: false
    scan_use_recursive: false
  tasks:
    - scan_packages:
    - scan_services:
    - scan_files:
        paths: '{{ scan_file_paths }}'
        get_checksum: '{{ scan_use_checksum }}'
        recursive: '{{ scan_use_recursive }}'
      when: scan_file_paths is defined

The fact file scan module is the only module that accepts parameters:

scan_file_paths: '/tmp/'
scan_use_checksum: true
scan_use_recursive: true

• The scan_file_paths parameter may have multiple settings (such as /tmp/ or /var/log).
• The scan_use_checksum and scan_use_recursive parameters may also be set to false or omitted. An omission is the same as a false setting.

10.2.3.2. Custom Fact Scans¶

The playbook for custom fact scans is similar to the example of the Fact Scan Playbook above. It differs in that it only invokes the custom fact scan module, scan_foo.

scan_custom.yml:

- hosts: all
  gather_facts: false
  tasks:
    - scan_foo:

scan_foo.py:

def main():
    module = AnsibleModule(
        argument_spec = dict())

    foo = [
      {
        "hello": "world"
      },
      {
        "foo": "bar"
      }
    ]
    results = dict(ansible_facts=dict(foo=foo))
    module.exit_json(**results)

main()

The custom fact scan module lives in the /library/ subdirectory of the Ansible project. The fact scan module is very simple, returning a hard-coded set of facts:

[
   {
     "hello": "world"
   },
   {
     "foo": "bar"
   }
 ]

10.3.1.1. Add a new group¶

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

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

• Name: Required
• Description: Enter an arbitray description as appropriate
• 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.

By default, the group Source is manual, meaning that the hosts must be entered into Tower manually. (Refer to Add a new host for more information on managing hosts individually.)

To synchronize the inventory group from a cloud source, select the Source tab and choose the appropriate source from the Source menu. Tower 2.2 supports Amazon Web Services EC2, Rackspace Cloud Servers, Google Compute Engine, VMware vCenter, Microsoft Azure, OpenStack, and custom scripts added by the administrator.

All cloud inventory sources have the following update options:

• Overwrite: When checked all child groups and hosts not found on the remote source is 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.

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

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.

10.3.1.3. Amazon Web Services EC2¶

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

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

Source Variables

Override variables found in ec2.ini and used by the inventory update script. For a detailed description of these variables view ec2.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.

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

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.

10.3.1.5. Microsoft Azure¶

To configure a group for Microsoft Azure, select Microsoft Azure 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.

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.

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

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

10.3.1.8. 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. For information on how to add custom inventory scripts to Tower, refer to Custom Inventory Scripts.

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

10.3.1.9. Scheduling¶

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

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.

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

10.3.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 button.

This opens the Create New Host dialog.

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.