awx.awx.tower_api – Search the API for objects

Note

This plugin is part of the awx.awx collection (version 14.1.0).

To install it use: ansible-galaxy collection install awx.awx.

To use it in a playbook, specify: awx.awx.tower_api.

Synopsis

Requirements

The below requirements are needed on the local controller node that executes this lookup.

  • None

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string / required
The endpoint to query, i.e. teams, users, tokens, job_templates, etc.
expect_objects
boolean
    Choices:
  • no ←
  • yes
Error if the response does not contain either a detail view or a list view.

aliases: expect_object
expect_one
boolean
    Choices:
  • no ←
  • yes
Error if the response contains more than one object.
host
string
env:TOWER_HOST
The network address of your Ansible Tower host.
max_objects
integer
Default:
1000
if return_all is true, this is the maximum of number of objects to return from the list.
If a list view returns more an max_objects an exception will be raised
oauth_token
string
env:TOWER_OAUTH_TOKEN
The Tower OAuth token to use.
password
string
env:TOWER_PASSWORD
The password for your Ansible Tower user.
query_params
dictionary
The query parameters to search for in the form of key/value pairs.

aliases: query, data, filter, params
return_all
boolean
    Choices:
  • no ←
  • yes
If the response is paginated, return all pages.
return_ids
boolean
    Choices:
  • no ←
  • yes
If response contains objects, promote the id key to the top-level entries in the list.
Allows looking up a related object and passing it as a parameter to another module.
This will convert the return to a string or list of strings depending on the number of selected items.

aliases: return_id
return_objects
boolean
    Choices:
  • no
  • yes ←
If a list view is returned, promote the list of results to the top-level of list returned.
Allows using this lookup plugin to loop over objects without additional work.
username
string
env:TOWER_USERNAME
The user that you plan to use to access inventories on Ansible Tower.
verify_ssl
boolean
    Choices:
  • no
  • yes
env:TOWER_VERIFY_SSL
Specify whether Ansible should verify the SSL certificate of Ansible Tower host.
Defaults to True, but this is handled by the shared module_utils code

aliases: validate_certs

Notes

Note

  • If the query is not filtered properly this can cause a performance impact.

  • If no config_file is provided we will attempt to use the tower-cli library defaults to find your Tower host information.

  • config_file should contain Tower configuration in the following format host=hostname username=username password=password

Examples

- name: Load the UI settings
  set_fact:
    tower_settings: "{{ lookup('awx.awx.tower_api', 'settings/ui') }}"

- name: Report the usernames of all users with admin privs
  debug:
    msg: "Admin users: {{ query('awx.awx.tower_api', 'users', query_params={ 'is_superuser': true }) | map(attribute='username') | join(', ') }}"

- name: debug all organizations in a loop  # use query to return a list
  debug:
    msg: "Organization description={{ item['description'] }} id={{ item['id'] }}"
  loop: "{{ query('awx.awx.tower_api', 'organizations') }}"
  loop_control:
    label: "{{ item['name'] }}"

- name: Make sure user 'john' is an org admin of the default org if the user exists
  tower_role:
    organization: Default
    role: admin
    user: john
  when: "lookup('awx.awx.tower_api', 'users', query_params={ 'username': 'john' }) | length == 1"

- name: Create an inventory group with all 'foo' hosts
  tower_group:
    name: "Foo Group"
    inventory: "Demo Inventory"
    hosts: >-
      {{ query(
           'awx.awx.tower_api',
            'hosts',
            query_params={ 'name__startswith' : 'foo', },
        ) | map(attribute='name') | list }}
  register: group_creation

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
dictionary
on successful request
Response from the API


Authors

  • John Westcott IV (@john-westcott-iv)