Ascender Ansible Collection

The ctrliq.ascender collection lets you manage an Ascender controller from Ansible playbooks: organizations, inventories, projects, job templates, credentials, schedules, workflows, and the rest of the controller API are all exposed as modules, alongside a dynamic inventory plugin and a set of lookup plugins.

Requirements

• ansible-core >= 2.16
• Python 3.10+ on the controller node running the modules
• awxkit — only required by a handful of modules (notably export and import). The DOCUMENTATION block of each module states whether it needs awxkit; the rest have no extra Python dependencies.

Installation

From Galaxy

ansible-galaxy collection install ctrliq.ascender

From source

Build the collection from a checkout of this repository:

ansible-galaxy collection build
ansible-galaxy collection install ctrliq-ascender-*.tar.gz

Using the collection

Reference modules, the inventory plugin, and lookups by their fully qualified collection name, ctrliq.ascender.<name>:

- name: Create a project and launch a job
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Add a project
      ctrliq.ascender.project:
        name: My Project
        organization: Default
        scm_type: git
        scm_url: https://github.com/ansible/test-playbooks.git

    - name: Launch a job template
      ctrliq.ascender.job_launch:
        job_template: My Job Template
      register: job

    - name: Wait for it to finish
      ctrliq.ascender.job_wait:
        job_id: "{{ job.id }}"

To use the dynamic inventory plugin, add a *.controller.yml (or *.controller.yaml) inventory source:

plugin: ctrliq.ascender.controller
host: https://controller.example.com

Authentication

Every module accepts the same connection options. You can authenticate with either:

• host, username, and password, or
• host and an OAuth2 token (preferred).

Connection settings are resolved from highest to lowest precedence:

1. Direct module parameters (controller_host, controller_username, controller_password, controller_oauthtoken, controller_verify_ssl).
2. Environment variables (CONTROLLER_HOST, CONTROLLER_USERNAME, CONTROLLER_PASSWORD, CONTROLLER_OAUTH_TOKEN, CONTROLLER_VERIFY_SSL) — most convenient when targeting localhost.
3. A config file passed via the controller_config_file parameter.

The config file may be written as INI, YAML, or JSON. INI form:

[general]
host = https://localhost:8043
verify_ssl = true
oauth_token = LEdCpKVKc4znzffcpQL5vLG8oyeku6

Included content

• 45 modules covering controller resources (organizations, inventories, credentials, etc.).
• 39 roles for declarative controller configuration.
• 5 playbooks for common configuration workflows.
• Inventory plugin: ctrliq.ascender.controller.
• Lookup plugins: controller_api, controller_object_diff, schedule_rrule, schedule_rruleset.

Per-plugin documentation is available with ansible-doc, e.g. ansible-doc ctrliq.ascender.job_launch.

Testing

See TESTING.md for full details.

• Sanity — ansible-test sanity from an installed copy.
• Unit — py.test tests/unit/ against the Ascender Django models.
• Integration — ansible-test integration with a running controller.

Contributing

See CONTRIBUTING.md. Report bugs via GitHub Issues. Release notes are in the changelog.

Licensing

This collection is licensed under the GNU General Public License v3.0 or later. See COPYING for the full text.