awx.awx.controller_api lookup – Search the API for objects
Note
This lookup plugin is part of the awx.awx collection (version 24.2.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install awx.awx.
You need further requirements to be able to use this lookup plugin,
see Requirements for details.
To use it in a playbook, specify: awx.awx.controller_api.
Synopsis
Returns GET requests from the Automation Platform Controller 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.controller collection see the controller_meta module
Aliases: tower_api
Requirements
The below requirements are needed on the local controller node that executes this lookup.
None
Terms
Parameter |
Comments |
|---|---|
The endpoint to query, i.e. teams, users, tokens, job_templates, etc. |
Keyword parameters
This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following
examples: lookup('awx.awx.controller_api', key1=value1, key2=value2, ...) and query('awx.awx.controller_api', key1=value1, key2=value2, ...)
Parameter |
Comments |
|---|---|
Error if the response does not contain either a detail view or a list view. Choices:
|
|
Error if the response contains more than one object. Choices:
|
|
The network address of your Automation Platform Controller host. Configuration:
|
|
if If a list view returns more an max_objects an exception will be raised Default: |
|
The OAuth token to use. Configuration:
|
|
The password for your controller user. Configuration:
|
|
The query parameters to search for in the form of key/value pairs. |
|
Specify the timeout Ansible should use in requests to the controller host. Defaults to 10 seconds This will not work with the export or import modules. Configuration:
|
|
If the response is paginated, return all pages. Choices:
|
|
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. Choices:
|
|
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. Choices:
|
|
The user that you plan to use to access inventories on the controller. Configuration:
|
|
Specify whether Ansible should verify the SSL certificate of the controller host. Defaults to True, but this is handled by the shared module_utils code Choices:
Configuration:
|
Notes
Note
When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
lookup('awx.awx.controller_api', term1, term2, key1=value1, key2=value2)andquery('awx.awx.controller_api', term1, term2, key1=value1, key2=value2)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 host information.
config_file should be in the following format host=hostname username=username password=password
Examples
- name: Load the UI settings
set_fact:
controller_settings: "{{ lookup('awx.awx.controller_api', 'settings/ui') }}"
- name: Load the UI settings specifying the connection info
set_fact:
controller_settings: "{{ lookup('awx.awx.controller_api', 'settings/ui', host='controller.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.controller_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.controller_api', 'organizations') }}"
loop_control:
label: "{{ item['name'] }}"
- name: Make sure user 'john' is an org admin of the default org if the user exists
role:
organization: Default
role: admin
user: john
when: "lookup('awx.awx.controller_api', 'users', query_params={ 'username': 'john' }) | length == 1"
- name: Create an inventory group with all 'foo' hosts
group:
name: "Foo Group"
inventory: "Demo Inventory"
hosts: >-
{{ query(
'awx.awx.controller_api',
'hosts',
query_params={ 'name__startswith' : 'foo', },
) | map(attribute='name') | list }}
register: group_creation
Return Value
Key |
Description |
|---|---|
Response from the API Returned: on successful request |