Ascender Ansible collection

blaipr

Hi all,

I think it's about time that Ascender moves away from the AWX collection (awx.awx) onto a dedicated collection.

The fully qualified collection name (FQCN) I've gone with is ctrliq.ascender.

Why

Riding on awx.awx made sense early on, but a dedicated namespace gives Ascender a clean home of its own. It lets us:

Keep Ascender-specific modules, roles, and plugins under a name that actually reflects the project.
Diverge from upstream AWX where it makes sense without fighting the awx.awx naming.
Make installs and playbook references unambiguous about what people are actually pulling in.

What changes for users

The install command:

ansible-galaxy collection install ctrliq.ascender

And module/role references move from the awx.awx.* prefix to ctrliq.ascender.*, for example:

- name: Example task
  ctrliq.ascender.<module>:
    ...

Hope everyone is okay with the naming convention?

If so, CtrlIQ should claim their namespace:

https://forum.ansible.com/t/ansible-galaxy-how-to-request-a-custom-namespace/45689

cigamit

I have applied for a namespace.
https://forum.ansible.com/t/namespace-ctrliq/45925

blaipr

cigamit thanks @cigamit !

I've just opened PR #432 (ctrliq/ascender432), which renames the bundled collection from awx.awx to ctrliq.ascender and brings it up to current Ansible Galaxy standards + upstream fixes.

What changed

Rename: awx.awx → ctrliq.ascender, and the source folder awx_collection/ → ascender_collection/. Every FQCN across the 44 modules, the inventory/lookup plugins, doc fragments, meta/runtime.yml redirects, and the integration tests is updated, along with the build wiring (Makefile, tox.ini, pyproject.toml, the promote workflow).
Modernized for current ansible-core: minimum raised to 2.16, Python 3 only (dropped the legacy six / text shims), and removed the long-dead tower* redirects.
Galaxy standards: RETURN docs on all 44 modules, a changelogs/ setup with per-change fragments, sanity ignore files for cores 2.16–2.21, and the dev test harness excluded from the shipped artifact.
Rewrote the collection README for Ascender (real ctrliq.ascender examples, the controller_* auth parameters, included-content listing, correct GPL-3.0 license).
Fixed the controller version check for the new collection type: it was warning on every task and skipping the real version comparison; it now correctly maps to the AWX product name the server reports.
Dev tooling now uses ctrliq.ascender (the docker-compose plumb/smoke-test playbooks), and the stale awx.awx references in the repo docs are corrected.

Upstream additions

I back-ported a set of fixes and features straight from upstream ansible/awx (ansible/awx)'s awx_collection, each with its upstream tests where they existed. Credit to the AWX maintainers for these:

Bug fixes

credential: allow clearing a description with an empty string (567f5a2)
credential: resolve and remove user-owned credentials (1d57f1c)
application: actually apply the skip_authorization parameter (it was a no-op) (1b8d409)
role: resolve teams across organizations under lookup_organization (8fb5862)
constructed inventory: preserve input_inventories ordering (3268c9b)
job waits: wait on event_processing_finished so events fully flush (4754819)
schedule_rrule / schedule_rruleset: return a list, as lookup plugins should (c9f8804)

Features

application: return the OAuth2 client_id / client_secret on create (1559c21)
job_template / workflow_job_template: accept the bitbucket_dc webhook service (a8afbd1)
inventory_source: accept the terraform source (a711354)
workflow_launch: add tags / skip_tags prompt support (c061f59)

Each was verified against the Ascender backend before inclusion (e.g. bitbucket_dc and terraform are supported by our API; a couple of others that needed backend support they don't have yet were deliberately left out - see below).

Testing

ansible-test sanity clean on ansible-core 2.17 (min) and 2.21 (latest): 24/24 each
Collection unit suite: 148 passed
antsibull-changelog lint clean; ansible-galaxy collection build produces a clean artifact

Deferred to a follow-up

Two upstream features need their controller-side backend (model + migration + UI) before the collection options can be added: AWS SNS notifications (awx#15184) and the OpenShift Virtualization inventory source (awx#15047). I've scoped those separately.

Notes

The collection should be built via make so the version substitution runs.

cigamit

Namespace has been created, so we can proceed.

blaipr

Nice!

@cigamit what do you think about moving the Ansible collection to a standalone repo ? e.g. ascender-collection

Since the Ascender install, operator, ee... have their own repos, it makes sense to create a dedicated repo for the collection.

I will decouple Ascender's code from the collection once the collection has been moved. Just ping me here when it's done.

cigamit

The collection itself has been migrated to the new repo, so we can kill it in the old. Will still need to separate out the build and publish actions.
ctrliq/ascender-collection

blaipr

cigamit Thanks

The ascender_collection/ directory has been removed from the main Ascender repo and all coupling points cleaned up.

Done in PR #517.

What was decoupled in the main repo

`Makefile`

Removed 13 COLLECTION_* variables:

COLLECTION_VERSION
COLLECTION_SANITY_ARGS
COLLECTION_TEST_DIRS
COLLECTION_TEST_TARGET
COLLECTION_PACKAGE
COLLECTION_NAMESPACE
COLLECTION_INSTALL
COLLECTION_TEMPLATE_VERSION

Removed 8 Make targets:

test_collection
test_collection_all
symlink_collection
ascender_collection_build
build_collection
install_collection
test_collection_sanity
test_collection_integration

Also removed ascender_collection from the Black formatting target so the linter no longer scans the deleted directory.

`pyproject.toml`

Removed:

extend-exclude = "ascender_collection"

from the [tool.black] section, as it is no longer needed.

`tox.ini`

Removed:

ascender_collection from the flake8 command in [testenv:linters]
ascender_collection_build from the [flake8] exclude list

`.gitignore`

Removed the following collection-related ignore patterns:

/ascender_collection_test_venv/
/ascender_collection/*.tar.gz
/ascender_collection_build/

`.github/workflows/promote.yml`

Removed the commented-out Galaxy publish job:

Collection build step
ansible-galaxy collection publish step

`.github/PULL_REQUEST_TEMPLATE.md`

Removed "Collection" from the component name checklist.

`.github/copilot-instructions.md`

Removed:

The ascender_collection/ row from the directory table
References to it in the Black and Flake8 example commands

Intentionally kept

The following entry remains in place:

('ascender', 'awx.awx.controller')

in:

awx/main/tests/functional/models/test_inventory.py

This test validates the inventory source plugin FQCN mapping at runtime, which depends on the installed collection, not on the former in-tree copy.

Impact

176 files deleted
27,000 lines removed

blaipr

Following the removal of ascender_collection/ from the main Ascender repo (PR #517), the collection repository at ctrliq/ascender-collection has been updated to function as a fully standalone, Galaxy-publishable collection (PR #2).

What changed

Standard versioning

galaxy.yml now carries the real version (25.4.0) instead of the previous 0.0.1-devel placeholder.

The collection now follows the same CalVer scheme as the Ascender product, matching the upstream awx.awx approach.

The collection can now be built directly from the repository root:

ansible-galaxy collection build

No Makefile or template playbook is required for standard builds.

Galaxy install path

Once published, the collection will be installable with:

ansible-galaxy collection install ctrliq.ascender

All references decoupled

Removed or replaced:

Every ascender_collection/ path reference
make build_collection
make test_collection
References to the old repository URL

The template build system (tools/template_galaxy.yml) remains available as an optional mechanism for:

Injecting versions into Python source files
Building non-default namespace variants

Deprecated references cleaned up

Updated documentation and examples:

TOWER_* environment variables → CONTROLLER_*
~/.tower_cli.cfg → ~/.controller_cli.cfg
Environment variable examples updated accordingly

License clarified

Removed a conflicting AGPLv3 LICENSE file inherited from the AWX upstream project.

The collection is licensed under:

GPL-3.0-or-later

as declared consistently in:

galaxy.yml
COPYING
README.md

Test infrastructure updated

conftest.py now handles awxkit path resolution at module level, including sys.modules cache invalidation.

This allows unit tests to run inside the Ascender development container without requiring:

pip install awxkit

All unit tests are currently passing:

148/148 tests passed

README streamlined

Removed:

Legacy tower_* migration notes
Historical origin text

The README is now focused on:

Installation
Usage
Authentication
Included content

Detailed testing instructions have been moved to:

TESTING.md

Additional work

A pull request (PR) template ( .github/PULL_REQUEST_TEMPLATE.md) was also added in a separate PR (#3), adapted from the main repository and tailored for collection development.

Available component names now include:

Module
Plugin
Role
Test
Build/Tooling

Result

The ctrliq.ascender collection is now fully independent from the main Ascender repository and can be:

Built directly with ansible-galaxy
Published to Galaxy as a standalone collection
Installed independently of the main project
Developed and tested without relying on an in-tree copy of ascender_collection/

blaipr

I added a CI pipeline that runs automatically on every push and pull request to main (and future stable-* branches). Since the repository is public, GitHub Actions runs at no cost to the project.

Pipeline jobs

Sanity tests

Runs ansible-test sanity across a matrix of:

ansible-core versions: 2.16 through devel
Python versions: 3.10 through 3.13

This catches issues such as:

Documentation errors
Bad imports
PEP8 violations
Missing or incorrect GPL headers
Module argument specification mismatches

All of these checks run without requiring a live server.

Build & Galaxy import

Builds the collection:

ansible-galaxy collection build

and validates the resulting artifact with galaxy-importer, the same tool used by Ansible Galaxy during collection uploads.

This catches issues before a release or review, including:

Invalid version formats
Missing metadata fields
Invalid SPDX license identifiers
Other Galaxy metadata problems

Lint

Runs:

flake8 against all plugin code
yamllint against:
- galaxy.yml
- meta/runtime.yml

Changelog

Runs:

antsibull-changelog lint

on pull requests to ensure changelog fragments are present and correctly formatted.

Scheduled testing

A weekly scheduled run executes every:

Monday at 06:00 UTC

This job tests against the latest ansible-core development branch to detect upstream breakage as early as possible.

Resource optimization

Concurrency groups are enabled so that when multiple commits are pushed to the same pull request:

Superseded workflow runs are automatically cancelled.
CI resources are not wasted on obsolete builds.

Unit tests

Unit tests are intentionally not part of this pipeline.

They require:

Django
The full Ascender application models
A dedicated containerized environment

As a result, unit tests remain a manual contributor step and are documented in:

TESTING.md

Summary

The CI pipeline now provides:

Multi-version ansible-core sanity testing
Collection build and Galaxy validation
Python and YAML linting
Changelog verification
Scheduled upstream compatibility testing
Automatic cancellation of redundant workflow runs

while keeping the heavier Django-dependent unit tests outside of the standard CI path.

blaipr

@cigamit I think the collection is ready to be released. In order to do so:

1) Galaxy namespace

The ctrliq namespace needs to exist (done)

2) Galaxy API key as a GitHub secret

The release workflow (.github/workflows/release.yml) publishes to Galaxy using a secret called GALAXY_API_KEY.

To set it up:

Go to https://galaxy.ansible.com/ui/token/ and generate an API token
In the ctrliq/ascender-collection repo, go to Settings > Secrets and variables > Actions
Create a repository secret named GALAXY_API_KEY with the token value

3) Release

Once the namespace and API key are in place, the actual release is:

Make sure galaxy.yml says the version you want (currently 25.4.0):

grep 'version:' galaxy.yml

Generate changelog, commit it:

antsibull-changelog release --version 25.4.0
git add changelogs/ CHANGELOG.rst
git commit -m "Generate changelog for 25.4.0"

Tag and push:

git tag 25.4.0
git push origin main --tags

Create a Release from the 25.4.0 tag:

gh release create 25.4.0 --title "25.4.0" --notes "First release of ctrliq.ascender"

The release workflow fires automatically and publishes to Galaxy.

4) After the release

Verify it landed:

ansible-galaxy collection install ctrliq.ascender --force
ansible-galaxy collection list | grep ctrliq

And check https://galaxy.ansible.com/ui/repo/published/ctrliq/ascender/ to confirm it shows up.

Annex: How the release workflow works

The file .github/workflows/release.yml triggers when a GitHub Release is published and does the following:

Checks that the release tag matches the version in galaxy.yml (supports both 25.4.0 and v25.4.0)
Builds the collection with ansible-galaxy collection build
Publishes to Galaxy with ansible-galaxy collection publish using the GALAXY_API_KEY secret
Uploads the .tar.gz as a release artifact (kept 90 days)

No manual publishing step needed -- creating the GitHub Release is the trigger.

fernandorocagonzalez

Hey @cigamit that collection would be an awesome contribution in order to use ascender as code

cigamit

I was going to wait until I released Ascender 25.5.0, since we have features in the devel branch of Ascender that the collection is already using. Should be this week, just running through regression and full manual testing of the UI to ensure no issues are found.

blaipr

Nice! Looking forward to Ascender 25.5.0.

I have added some last-minute fixes and new API features from upstream Ascender to the collection for its first release.

fernandorocagonzalez

cigamit that's awesome!

cigamit

It is live! A huge thanks for all the work you have done on this @blaipr
https://galaxy.ansible.com/ui/repo/published/ctrliq/ascender/

blaipr

Nice !!

Thanks for the shoutout ^^