Merge pull request #6256 from beeankha/collections_toolbox

Module Generation Tools for the AWX Collection

Reviewed-by: https://github.com/apps/softwarefactory-project-zuul

awx_collection/galaxy.yml.j2

@@ -19,6 +19,7 @@ tags:
 - automation
 version: {{ collection_version }}
 build_ignore:
+- tools
 - setup.cfg
 - galaxy.yml.j2
 - template_galaxy.yml

awx_collection/plugins/modules/tower_group.py

@@ -28,12 +28,6 @@ options:
         - The name to use for the group.
       required: True
       type: str
-    new_name:
-      description:
-        - A new name for this group (for renaming)
-      required: False
-      type: str
-      version_added: "3.7"
     description:
       description:
         - The description to use for the group.
@@ -53,6 +47,12 @@ options:
       default: "present"
       choices: ["present", "absent"]
       type: str
+    new_name:
+      description:
+        - A new name for this group (for renaming)
+      required: False
+      type: str
+      version_added: "3.7"
     tower_oauthtoken:
       description:
         - The Tower OAuth token to use.

awx_collection/plugins/modules/tower_user.py

@@ -45,7 +45,7 @@ options:
       type: str
     is_superuser:
       description:
-        - User is a system wide administrator.
+        - Designates that this user has all permissions without explicitly assigning them.
       required: False
       type: bool
       default: False
@@ -59,10 +59,9 @@ options:
       aliases: ['auditor']
     password:
       description:
-        - Password of the user; write-only field.
+        - Write-only field used to change the password.
       required: False
       type: str
-      default: ''
     state:
       description:
         - Desired state of the resource.
@@ -128,7 +127,7 @@ def main():
         email=dict(required=False, type='str'),
         is_superuser=dict(required=False, type='bool', default=False, aliases=['superuser']),
         is_system_auditor=dict(required=False, type='bool', default=False, aliases=['auditor']),
-        password=dict(required=False, type='str', default=''),
+        password=dict(required=False, type='str'),
         state=dict(choices=['present', 'absent'], default='present'),
     )
 

awx_collection/tools/generate.yml

@@ -0,0 +1,82 @@
+---
+- name: Generate the awx.awx collection
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  vars:
+    api_url: "{{ lookup('env', 'TOWER_HOST') }}"
+  vars_files:
+    - vars/generate_for.yml
+    - vars/aliases.yml
+    - vars/examples.yml
+  module_defaults:
+    uri:
+      validate_certs: false
+      force_basic_auth: true
+      url_username: "{{ lookup('env', 'TOWER_USERNAME') }}"
+      url_password: "{{ lookup('env', 'TOWER_PASSWORD') }}"
+
+  tasks:
+    - name: Get date time data
+      setup:
+        gather_subset: min
+
+    - name: Create module directory
+      file:
+        state: directory
+        name: "modules"
+
+    - name: Load api/v2
+      uri:
+        method: GET
+        url: "{{ api_url }}/api/v2/"
+      register: endpoints
+
+    - name: Load endpoint options
+      uri:
+        method: "OPTIONS"
+        url: "{{ api_url }}{{ item.value }}"
+      loop: "{{ endpoints['json'] | dict2items }}"
+      loop_control:
+        label: "{{ item.key }}"
+      register: end_point_options
+      when: "generate_for is not defined or item.key in generate_for"
+
+    - name: Scan POST options for different things
+      set_fact:
+        all_options: "{{ all_options | default({}) | combine(options[0]) }}"
+      loop: "{{ end_point_options.results }}"
+      vars:
+        options: "{{ item | json_query('json.actions.POST.[*]') }}"
+      loop_control:
+        label: "{{ item['item']['key'] }}"
+      when:
+        - item is not skipped
+        - options is defined
+
+    - name: Process endpoint
+      template:
+        src: "templates/tower_module.j2"
+        dest: "{{ playbook_dir | dirname }}/plugins/modules/{{ file_name }}"
+      loop: "{{ end_point_options['results'] }}"
+      loop_control:
+        label: "{{ item['item']['key'] }}"
+      when: "'json' in item and 'actions' in item['json'] and 'POST' in item['json']['actions']"
+      vars:
+        item_type: "{{ item['item']['key'] }}"
+        human_readable: "{{ item_type | replace('_', ' ') }}"
+        singular_item_type: "{{ item['item']['key'] | regex_replace('ies$', 'y') | regex_replace('s$', '') }}"
+        file_name: "tower_{% if item['item']['key'] in ['settings'] %}{{ item['item']['key'] }}{% else %}{{ singular_item_type }}{% endif %}.py"
+        type_map:
+          bool: 'bool'
+          boolean: 'bool'
+          choice: 'str'
+          datetime: 'str'
+          id: 'str'
+          int: 'int'
+          integer: 'int'
+          json: 'dict'
+          list: 'list'
+          object: 'dict'
+          password: 'str'
+          string: 'str'

awx_collection/tools/templates/tower_module.j2

@@ -0,0 +1,186 @@
+#!/usr/bin/python
+# coding: utf-8 -*-
+
+{# The following is set by the generate.yml file:
+ #   item_type: the type of item i.e. 'teams'
+ #   human_readable: the type with _ replaced with spaces i.e. worflow job template
+ #   singular_item_type: the type of an item replace singularized i.e. team
+ #   type_map: a mapping of things like string to str
+ #}
+{% set name_option = 'username' if item_type == 'users' else 'name' %}
+
+# (c) {{ ansible_date_time['year'] }}, John Westcott IV <john.westcott.iv@redhat.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: tower_{{ singular_item_type }}
+author: "John Westcott IV (@john-westcott-iv)"
+version_added: "2.3"
+short_description: create, update, or destroy Ansible Tower {{ human_readable }}.
+description:
+    - Create, update, or destroy Ansible Tower {{ human_readable }}. See
+      U(https://www.ansible.com/tower) for an overview.
+options:
+{% for option in item['json']['actions']['POST'] %}
+{# to do: sort documentation options #}
+    {{ option }}:
+      description:
+{% if 'help_text' in item['json']['actions']['POST'][option] %}
+        - {{ item['json']['actions']['POST'][option]['help_text'] }}
+{% else %}
+        - NO DESCRIPTION GIVEN IN THE TOWER API
+{% endif %}
+      required: {{ item['json']['actions']['POST'][option]['required'] }}
+      type: {{ type_map[ item['json']['actions']['POST'][option]['type'] ] }}
+{% if item['json']['actions']['POST'][option].get('default', '') != '' %}
+      default: {{ item['json']['actions']['POST'][option]['default'] }}
+{% endif %}
+{% if 'choices' in item['json']['actions']['POST'][option] %}
+      choices:
+{% for choice in item['json']['actions']['POST'][option]['choices'] %}
+        - '{{ choice[0] }}'
+{% endfor %}
+{%endif %}
+{% if aliases[item_type][option] | default(False) %}
+      aliases:
+{% for alias_name in aliases[item_type][option] %}
+        - {{ alias_name }}
+{% endfor %}
+{% endif %}
+{% if option == name_option %}
+    new_{{ name_option }}:
+      description:
+        - Setting this option will change the existing name (looked up via the {{ name_option }} field.
+      required: True
+      type: str
+{% endif %}
+{% endfor %}
+    state:
+      description:
+        - Desired state of the resource.
+      choices: ["present", "absent"]
+      default: "present"
+      type: str
+    tower_oauthtoken:
+      description:
+        - The Tower OAuth token to use.
+      required: False
+      type: str
+      version_added: "3.7"
+extends_documentation_fragment: awx.awx.auth
+'''
+
+EXAMPLES = '''
+{% if examples[item_type] | default(False) %}
+{{ examples[item_type] }}
+{% endif %}
+'''
+
+from ..module_utils.tower_api import TowerModule
+
+
+def main():
+    # Any additional arguments that are not fields of the item can be added here
+    argument_spec = dict(
+{% for option in item['json']['actions']['POST'] %}
+{%   set option_data = [] %}
+{{   option_data.append('required={}'.format(item['json']['actions']['POST'][option]['required'])) -}}
+{{   option_data.append('type=\'{}\''.format(type_map[item['json']['actions']['POST'][option]['type']])) -}}
+{%   if item['json']['actions']['POST'][option]['type'] == 'password' %}
+{{     option_data.append('no_log=True') -}}
+{%   endif %}
+{%   if 'choices' in item['json']['actions']['POST'][option] %}
+{%     set all_choices = [] %}
+{%     for choice in item['json']['actions']['POST'][option]['choices'] %}
+{{       all_choices.append("'{}'".format(choice[0])) -}}
+{%     endfor %}
+{{     option_data.append('choices=[{}]'.format(all_choices | join(', '))) -}}
+{%   endif %}
+{%   if item['json']['actions']['POST'][option].get('default', '') != '' %}
+{{     option_data.append("default='{}'".format(item['json']['actions']['POST'][option]['default'])) -}}
+{%   endif %}
+{%   if aliases[item_type][option] | default(False) %}
+{%     set alias_list = [] %}
+{%     for alias_name in aliases[item_type][option] %}
+{{       alias_list.append("'{}'".format(alias_name)) -}}
+{%     endfor %}
+{{     option_data.append('aliases=[{}]'.format(alias_list | join(', '))) -}}
+{%   endif %}
+        {{ option }}=dict({{ option_data | join(', ') }}),
+{% if option == name_option %}
+        new_{{ name_option }}=dict(required=False, type='str'),
+{% endif %}
+{% endfor %}
+        state=dict(choices=['present', 'absent'], default='present'),
+    )
+
+    # Create a module for ourselves
+    module = TowerModule(argument_spec=argument_spec, supports_check_mode=True)
+
+    # Extract our parameters
+{% for option in item['json']['actions']['POST'] %}
+    {{ option }} = module.params.get('{{ option }}')
+{% if option == name_option %}
+    new_{{ name_option }} = module.params.get("new_{{ name_option }}")
+{% endif %}
+{% endfor %}
+    state = module.params.get('state')
+
+{% if item['json']['actions']['POST'] | length() > 0 %}
+    # Attempt to look up the related items the user specified (these will fail the module if not found)
+{% for option in item['json']['actions']['POST'] %}
+{% if item['json']['actions']['POST'][option]['type'] == 'id' %}
+    {{ option }}_id = None
+    if {{ option }}:
+        {{ option }}_id = module.resolve_name_to_id('{{ option }}', {{ option }})
+{% endif %}
+{% endfor %}
+{% endif %}
+
+    # Attempt to look up an existing item based on the provided data
+    existing_item = module.get_one('{{ item_type }}', **{
+        'data': {
+            '{{ name_option }}': {{ name_option }},
+{% if 'organization' in item['json']['actions']['POST'] and item['json']['actions']['POST']['organization']['type'] == 'id' %}
+            'organization': org_id,
+{% endif %}
+{% if item_type in ['hosts', 'groups', 'inventory_sources'] %}
+            'inventory': inventory_id,
+{% endif %}
+        }
+    })
+
+    # Create the data that gets sent for create and update
+    new_fields = {}
+{% for option in item['json']['actions']['POST'] %}
+{% if option == name_option %}
+    new_fields['{{ name_option }}'] = new_{{ name_option }} if new_{{ name_option }} else {{ name_option }}
+{% else %}
+    if {{ option }}:
+{% if item['json']['actions']['POST'][option]['type'] == 'id' %}
+        new_fields['{{ option }}'] = {{ option }}_id
+{% else %}
+        new_fields['{{ option }}'] = {{ option }}
+{% endif %}
+{% endif %}
+{% endfor %}
+
+    if state == 'absent':
+        # If the state was absent we can let the module delete it if needed, the module will handle exiting from this
+        module.delete_if_needed(existing_item)
+    elif state == 'present':
+        # If the state was present and we can let the module build or update the existing item, this will return on its own
+        module.create_or_update_if_needed(existing_item, new_fields, endpoint='{{ item_type }}', item_type='{{ singular_item_type }}')
+
+
+if __name__ == '__main__':
+    main()

awx_collection/tools/vars/aliases.yml

@@ -0,0 +1,29 @@
+---
+aliases:
+  job_templates:
+    ask_tags_on_launch:
+      - ask_tags
+    ask_verbosity_on_launch:
+      - ask_verbosity
+    ask_diff_mode_on_launch:
+      - ask_diff_mode
+    allow_simultaneous:
+      - concurrent_jobs_enabled
+    diff_mode:
+      - diff_mode_enabled
+    ask_inventory_on_launch:
+      - ask_inventory
+    limit:
+      - ask_limit
+    force_handlers:
+      - force_handlers_enabled
+    ask_job_type_on_launch:
+      - ask_job_type
+    ask_skip_tags_on_launch:
+      - ask_skip_tags
+    use_fact_cache:
+      - fact_caching_enabled
+    extra_vars:
+      - ask_extra_vars
+    ask_credential_on_launch:
+      - ask_credential

awx_collection/tools/vars/examples.yml

@@ -0,0 +1,52 @@
+---
+examples:
+  users: |
+    - name: Add tower user
+      tower_user:
+        username: jdoe
+        password: foobarbaz
+        email: jdoe@example.org
+        first_name: John
+        last_name: Doe
+        state: present
+        tower_config_file: "~/tower_cli.cfg"
+
+    - name: Add tower user as a system administrator
+      tower_user:
+        username: jdoe
+        password: foobarbaz
+        email: jdoe@example.org
+        superuser: yes
+        state: present
+        tower_config_file: "~/tower_cli.cfg"
+
+    - name: Add tower user as a system auditor
+      tower_user:
+        username: jdoe
+        password: foobarbaz
+        email: jdoe@example.org
+        auditor: yes
+        state: present
+        tower_config_file: "~/tower_cli.cfg"
+
+    - name: Delete tower user
+      tower_user:
+        username: jdoe
+        email: jdoe@example.org
+        state: absent
+        tower_config_file: "~/tower_cli.cfg"
+
+  job_templates: |
+    - name: Create tower Ping job template
+      tower_job_template:
+        name: "Ping"
+        job_type: "run"
+        inventory: "Local"
+        project: "Demo"
+        playbook: "ping.yml"
+        credential: "Local"
+        state: "present"
+        tower_config_file: "~/tower_cli.cfg"
+        survey_enabled: yes
+        survey_spec: "{{ '{{' }} lookup('file', 'my_survey.json') {{ '}}' }}"
+        custom_virtualenv: "/var/lib/awx/venv/custom-venv/"

awx_collection/tools/vars/generate_for.yml

@@ -0,0 +1,16 @@
+---
+generate_for:
+  # - credentials
+  # - credential_types
+  # - groups
+  # - hosts
+  # - inventorues
+  # - inventory_sources
+  # - job_templates
+  # - labels
+  # - notification_templates
+  # - organizations
+  # - projects
+  - schedules
+  # - teams
+  # - users