shanemcd.awx.controller_api (20.0.14) — lookup

Install collection

Install with ansible-galaxy collection install shanemcd.awx:==20.0.14

Add to requirements.yml

  collections:
    - name: shanemcd.awx
      version: 20.0.14

Description

Returns GET requests from the Automation Platform Controller API. See U(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

Requirements

• None

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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(', ') }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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'] }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
host:
    description: The network address of your Automation Platform Controller host.
    env:
    - name: CONTROLLER_HOST
    - deprecated:
        alternatives: CONTROLLER_HOST
        collection_name: awx.awx
        version: 4.0.0
        why: Collection name change
      name: TOWER_HOST

_terms:
    description:
    - The endpoint to query, i.e. teams, users, tokens, job_templates, etc.
    required: true

password:
    description: The password for your controller user.
    env:
    - name: CONTROLLER_PASSWORD
    - deprecated:
        alternatives: CONTROLLER_PASSWORD
        collection_name: awx.awx
        version: 4.0.0
        why: Collection name change
      name: TOWER_PASSWORD

username:
    description: The user that you plan to use to access inventories on the controller.
    env:
    - name: CONTROLLER_USERNAME
    - deprecated:
        alternatives: CONTROLLER_USERNAME
        collection_name: awx.awx
        version: 4.0.0
        why: Collection name change
      name: TOWER_USERNAME

expect_one:
    default: false
    description:
    - Error if the response contains more than one object.
    type: boolean

return_all:
    default: false
    description:
    - If the response is paginated, return all pages.
    type: boolean

return_ids:
    aliases:
    - return_id
    default: false
    description:
    - 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.
    type: boolean

verify_ssl:
    aliases:
    - validate_certs
    description:
    - 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
    env:
    - name: CONTROLLER_VERIFY_SSL
    - deprecated:
        alternatives: CONTROLLER_VERIFY_SSL
        collection_name: awx.awx
        version: 4.0.0
        why: Collection name change
      name: TOWER_VERIFY_SSL
    type: bool

max_objects:
    default: 1000
    description:
    - if C(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
    type: integer

oauth_token:
    description:
    - The OAuth token to use.
    env:
    - name: CONTROLLER_OAUTH_TOKEN
    - deprecated:
        alternatives: CONTROLLER_OAUTH_TOKEN
        collection_name: awx.awx
        version: 4.0.0
        why: Collection name change
      name: TOWER_OAUTH_TOKEN

query_params:
    aliases:
    - query
    - data
    - filter
    - params
    description:
    - The query parameters to search for in the form of key/value pairs.
    required: false
    type: dict

expect_objects:
    aliases:
    - expect_object
    default: false
    description:
    - Error if the response does not contain either a detail view or a list view.
    type: boolean

return_objects:
    default: true
    description:
    - 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.
    type: boolean

Outputs

_raw:
  description:
  - Response from the API
  returned: on successful request
  type: dict