awx.awx.tower_api – Search the API for objects

Note

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

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

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

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

Synopsis

Returns GET requests from the Ansible Tower API. See https://docs.ansible.com/ansible-tower/latest/html/towerapi/index.html for API usage.
For use that is cross-compatible between the awx.awx and ansible.tower collection see the tower_meta module

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	no ← yes		Error if the response does not contain either a detail view or a list view. aliases: expect_object
expect_one boolean	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	no ← yes		If the response is paginated, return all pages.
return_ids boolean	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	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	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: Load the UI settings specifying the connection info
  set_fact:
    tower_settings: "{{ lookup('awx.awx.tower_api', 'settings/ui' host='tower.example.com', username='admin', password=my_pass_var, verify_ssl=False) }}"

- 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)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/awx/awx/tower_api_lookup.html