awx.awx.tower_api – Search the API for objects
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
- 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 |
|
Error if the response does not contain either a detail view or a list view.
| |
expect_one boolean |
|
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 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.
| ||
return_all boolean |
|
If the response is paginated, return all pages. | |
return_ids boolean |
|
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.
| |
return_objects boolean |
|
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 |
|
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
|
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/awx/awx/tower_api_lookup.html