This Ansible playbooks and roles allows for easy interaction with an Ansible Controller server via Ansible roles using the Controller collection modules.
⚠️ Important Note: AAP Version Dependency.Use the new collection
infra.aap_configurationfor AAP 2.5ansible.controller 4.6.x is for AAP 2.5.
Be sure to use
ansible.controller 4.5.12for AAP 2.4
- AAP installation Utilities: Ansible Automation Platform Utilities
- AAP Configuration Template: Configuration Template for this suite
Quick links:
ansible.platform(): This collection contains modules that can be used to automate the creation of resources on an install of Ansible Automation Platform.infra.ee_utilitiesAnsible Galaxy | GitHub: Execution Environment creation utilities
Table of Content
- Configuration as Code for Automation Automation Platform
- What is Configuration as Code (CaC) in Ansible Automation Platform?
- Requirements
- Ansible Automation Platform CaC Collections
- Other Configuration Collections for Ansible Automation Platform
- Configuring Credential
- How to use the playbooks for configuring AAP
- How to use the playbooks for Exporting content from AAP
- Using ngrok for exposing AAP and enable GitHub webhook
- Troubleshooting
- References
Configuration as Code (CaC or CasC) is the practice of managing configuration settings in source control, separate from your application logic or UI. The goal is simple: make configurations easy to version, share, audit, and deploy—just like code.
In the context of Ansible Automation Platform, you can bring this idea to life using automation controller features. Combine CaC with a GitOps workflow and you’ve got a solid setup for managing and replicating configurations across environments—whether it's dev, staging, or production.
This becomes especially useful when you're dealing with large or complex systems. Instead of manually tweaking settings, you define them once (in code), store them in Git, and let automation handle the rest. That means:
- Version control: Track every change, rollback when needed, and collaborate like you would with application code.
- Consistency: Avoid drift by applying the same configs across all your automation controller instances.
- Repeatability: Spin up identical environments without manual effort.
- Automation: Trigger deployments or updates directly from your Git repo.
- Auditing & compliance: Know exactly who made changes, when, and what changed.
Bottom line: CaC gives you control, clarity, and confidence when managing automation controller configurations—especially at scale.
awxkit >= 9.3.0
$ pip3 install awxkit --user-
Credential to access the Ansible Automation Platform
-
Ansible Automation Platform Collections
Install required collections as per requirements.yaml
---
collections:
- name: ansible.platform
- name: ansible.hub
- name: ansible.controller
- name: ansible.eda
- name: infra.aap_configuration
- name: infra.aap_configuration_extended$ ansible-galaxy collection install -r requirements.yaml(Or download and install for disconnected environment)
| Collection Name | Purpose | Resources |
|---|---|---|
infra.aap_configuration |
Main collection of roles to manage Ansible Automation Platform 2.5+ with code | Automation Hub, GitHub, Ansible Galaxy |
ansible.platform |
gateway/platform modules | Automation Hub (no public repo for this collection) |
ansible.hub |
Automation hub modules | Automation Hub , GitHub, |
ansible.controller |
Automation controller modules | Automation Hub, awx.awx on GtiHub, GitHub |
ansible.eda |
Event Driven Ansible modules | Automation HubGitHub |
| Collection Name | Purpose | Resources |
|---|---|---|
aap_configuration_extended |
Where other useful roles that don't fit here live | Automation Hub |
| EE Utilities | Execution Environment creation utilities | |
| AAP installation Utilities | Ansible Automation Platform Utilities | |
| AAP Configuration Template | Configuration Template for this suite | |
| Ansible Validated Gitlab Workflows | Gitlab CI/CD Workflows for ansible content | |
| Ansible Validated Github Workflows | Github CI/CD Workflows for ansible content | |
infra.ah_configuration |
Old collections (before AAP 2.5) | GitHub, Automation Hub |
When using ansible-playbook or ansible-navigator, the credential can be passed as environment variables; configure the credential as follows.
export CONTROLLER_USERNAME=admin
export CONTROLLER_PASSWORD=secretpassword
export CONTROLLER_HOST=https://aap25.lab.iamgini.comThe playbooks/configure-aap.yaml can be executed using ansible-playbook, ansible-navigator or using a Job template from Ansible controller itself.
For flattened configuration
$ ansible-playbook playbooks/configure-aap.yamlFor filetree configuration
$ ansible-playbook playbooks/configure-aap-using-filetree.yaml \
-e "{orgs: ${AAP_ORGANIZATION}, dir_orgs_vars: ../cac_filetree, env: ${AAP_ENVIRONMENT} }" \
-e @orgs_vars/env/${ENVIRONMENT}/configure_connection_controller_credentials.yml \
--tags ${CONTROLLER_OBJECT} \
--vault-password-file ./.vault_pass.txtCheck 'collections/ansible_collections/infra/aap_configuration_extended/roles/filetree_read/defaults/main.yml`
$ ansible-navigator run playbooks/configure-aap.yaml \
--penv CONTROLLER_USERNAME \
--penv CONTROLLER_PASSWORD \
--penv CONTROLLER_HOSTLogin to the automation controller (from where you are going to execute the CaC operation),
-
Step 1. A Git repo for Configuration as Code - Store this content in a Git repo as it is.
-
Step 2: Create the Project in Automation controller with the CaC repo as source and add Git credential if required.
-
Step 3: Create a
Red Hat Ansible Automation Platformtype credential and enter the controller host, username and password for the controller. -
Step 4: Create a Job template (eg:
CaC-Controller-Configuration) using the playbookcontroller_configure.yaml- Step 4.1: Attach the previously created
Red Hat Ansible Automation Platformtype credential. - Step 4.2: Enable
Prompt on Launchfor theJob Tagsas we need to control the execution. - Step 4.3: Add a tag
nonein theJob Tagstext box. (This is to avoid any accidental execution.)
- Step 4.1: Attach the previously created
-
Step 5: Execute the playbook with appropriate tags as explained in the next section.
- If the credential sources are enabled (automated password and token input), all of the resources can be created in a one batch.
- If the credential input (password, token and so on) needs to enter manually, then break the job execution as follows.
Step 1: Launch the job template CaC-Controller-Configuration with the following tags: settings, organizations, credential_types, credentials
Step 2: Login to the target automation controller (if this is a different controller), edit the source control credentials with correct password (this is for syncing the project with correct credentials). You can also update other credential passwords and tokens at this time.
Step 3. Continue the CaC configuration with the remaining tags: projects, inventories, hosts, templates, workflows etc.
$ ansible-playbook playbooks/controller_export.yamlRefer to the Automation Controller Export Documentation and export module documentation
If the Ansible Automation Platform is running locally (e.g: on workstation or without a public IP), we need to create tunnel (using ngrok here) so that GitHub can reach the Ansible Automation Platform over internet.
export NGROK_AUTH_TOKEN=Your-Authtoken
export NGROK_CUSTOM_DOMAIN=Your-custom-domain
$ podman run --net=host -it \
-e NGROK_AUTHTOKEN=$NGROK_AUTH_TOKEN \
ngrok/ngrok:latest \
http https://aap-rhel-92-1.lab.local \
--domain=$NGROK_CUSTOM_DOMAINNote:
- Using Podman container to run ngrok, but you can install ngrok locally and use it.
- Using
guiding-immortal-sunbeam.ngrok-free.appas pre-configured domain name. https://aap-rhel-92-1.lab.localis my local URL of Ansible controller.
(If any)