Configuration as code
Koios Automation Platform can be configured from Git with Ansible collections: organizations, teams and users in the platform gateway; credentials, projects, inventories, job templates and their roles in automation controller; projects, decision environments and activations in Event-Driven Ansible; and namespaces and collections in automation hub.
From 2026.11.13 the platform has its own collections in the koios namespace, built from the upstream sources of the
collections used with AWX and the reference platform, with the platform release as their version. Repositories that use
the current collections of those platforms keep working with the notes below; the operations described on this page were
tested with both.
Koios collections
Collection |
What it manages |
|---|---|
|
automation controller |
|
platform gateway: organizations, teams, users, authentication |
|
Event-Driven Ansible |
|
automation hub |
|
roles that apply a whole configuration ( |
|
configuration read from a directory tree ( |
Where to get them:
Koios execution environment: all six are installed, and their tarballs are in
/opt/koios-collections/casc.Platform automation hub:
casc/hub-collections.ymlpublishes them there (see below).Ansible Galaxy:
ansible-galaxy collection install koios.configuration_extendedinstalls it with the five others it depends on.
They are community builds of the upstream sources (each README names its source and commit), not supported by Red Hat.
The collections connect through the platform gateway with aap_hostname, aap_username, aap_password and
aap_validate_certs (or the AAP_HOSTNAME, AAP_USERNAME, AAP_PASSWORD and AAP_VALIDATE_CERTS environment
variables); koios.controller uses the controller API path behind the gateway without extra settings.
Coming from AWX or the reference platform
Koios collection |
With AWX |
With the reference platform |
|---|---|---|
|
|
|
|
— (AWX has no platform gateway) |
|
|
|
|
|
|
|
|
|
|
|
|
|
From the current collections of the reference platform (ansible.*, infra.aap_configuration and
infra.aap_configuration_extended), modules, roles and variables are the same: moving a repository is a matter of changing
the prefix of the fully qualified names, for example ansible.controller.job_template to koios.controller.job_template
or infra.aap_configuration.dispatch to koios.configuration.dispatch; the variables (controller_templates,
aap_hostname and the rest) do not change. From the older infra.controller_configuration, some variables also change
(for example controller_hostname to aap_hostname, controller_organizations to aap_organizations); follow the
conversion guide of the
upstream collection first.
The Koios execution environment also ships awx.awx, ansible.controller and ansible.platform built from the sources
of the platform release, for repositories that keep the upstream names. Notes for those collections:
awx.awxneedsCONTROLLER_OPTIONAL_API_URLPATTERN_PREFIX=/api/controller/to reach automation controller through the platform gateway. Theawx.awx24.6.1 on Ansible Galaxy cannot authenticate with a user name and password against the platform (or the reference platform): use the one of the execution environment.ansible.controllerandansible.platformare not on Ansible Galaxy; use the ones of the execution environment or of the platform automation hub.With
infra.aap_configuration, do not followobject_diffwith the wholedispatchrole: it runs a role that uses theansible.controller.applicationmodule, which current automation controller no longer has.koios.configurationdoes not have that role, sodispatchcan followobject_diff.
The collection that installs the platform is koios.installer (see Install with Ansible); it
is not a configuration-as-code collection.
Publish the collections to automation hub
The casc/ directory of koios-installer has hub-collections.yml, which publishes the collections of the execution
environment (the six Koios collections and awx.awx, ansible.controller and ansible.platform) to the platform
automation hub so that any client can install them from there:
it creates the
koios,awxandansiblenamespaces if they do not exist and never modifies existing namespaces;it checks every version before writing: if the hub already holds one of them with different content, it stops without writing anything;
it uploads the missing versions, waits for the import, approves them and checks that the hub holds exactly the same tarballs (SHA-256).
Run it again after upgrading the platform to publish the collections of the new release. casc/requirements.yml
installs ansible.hub from Ansible Galaxy.
To install from the hub, add it as a Galaxy server, for example in ansible.cfg:
[galaxy]
server_list = koios
[galaxy_server.koios]
url = https://<platform>/api/galaxy/content/published/
username = <user>
and give the password in the ANSIBLE_GALAXY_SERVER_KOIOS_PASSWORD environment variable.
Run the configuration
As a job template
: Create a project with your configuration repository, select the Koios execution environment (it has the Koios
collections; a collections/requirements.yml in the project is installed when the project is updated) and add a
Red Hat Ansible Automation Platform credential: it sets the AAP_* and CONTROLLER_* variables for the platform.
With ansible-navigator
: ansible-navigator runs the playbook inside the Koios execution environment, so a workstation or a CI job uses the
same collections as the platform. casc/ansible-navigator.yml in koios-installer selects the image of the release
and passes the AAP_* variables:
export AAP_HOSTNAME=https://<platform> AAP_USERNAME=<user> AAP_PASSWORD=<password> AAP_VALIDATE_CERTS=true
ansible-navigator run site.yml
During this phase, the images in ghcr.io/koiosplatform and the koios-installer repository are
private. The project must grant registry read access and repository read access separately;
a registry token alone does not grant access to the repository. Once authorized, log in to the
registry with a read-only token; see Access prerequisites.
To request access, write to the Koios project at asield03@gmail.com.
With ansible-playbook : Install the Koios collections from Ansible Galaxy or the platform automation hub and run the playbook as usual.
Example: one repository, several environments
A common layout keeps the configuration of each organization in a directory tree, with the objects shared by every
environment in common and the ones that change per environment (credentials, hosts) in a directory per environment.
An inventory with one group per environment selects the platform and the environment:
orgs_vars/
Engineering/
env/
common/
aap_organizations.d/org.yml
controller_projects.d/projects.yml
controller_inventories.d/inventories.yml
controller_job_templates.d/web.yml
controller_job_templates.d/db.yml
dev/
controller_credentials.d/credentials.yml
controller_hosts.d/hosts.yml
pro/
controller_credentials.d/credentials.yml
controller_hosts.d/hosts.yml
group_vars/
dev/connection.yml
pro/connection.yml
inventory
apply.yml
drop_diff.yml
inventory has one host per platform:
[dev]
platform-dev
[pro]
platform-pro
[all:vars]
ansible_connection=local
group_vars/pro/connection.yml sets the environment and the connection of that platform. The password comes from Ansible
Vault (vault_aap_password) when it is defined, or from the AAP_PASSWORD variable that the credential of a job template
sets:
env: pro
aap_hostname: https://platform-pro.example.com
aap_username: casc
aap_password: "{{ vault_aap_password | default(lookup('ansible.builtin.env', 'AAP_PASSWORD')) }}"
aap_validate_certs: true
Each .d directory holds YAML files with the variables of koios.configuration; filetree_read merges them. For
example env/pro/controller_hosts.d/hosts.yml:
controller_hosts:
- name: web-pro-1
inventory: Engineering servers
apply.yml reads the tree of the selected environment and applies it:
- hosts: all
gather_facts: false
vars:
dir_orgs_vars: orgs_vars
orgs: Engineering
roles:
- koios.configuration_extended.filetree_read
- koios.configuration.dispatch
ansible-playbook -i inventory apply.yml -l pro
Changing a value in the tree and running the playbook again updates the object; for example, a different user name in
env/pro/controller_credentials.d/credentials.yml updates the credential.
Delete what is no longer in the repository
Applying the tree creates and updates objects but does not delete the ones whose files were removed. object_diff
compares the tree with the platform and marks the objects of the organization that are no longer defined as
state: absent; applying those lists deletes them. Limit it to the object types that belong to the organization:
- hosts: all
gather_facts: false
vars:
dir_orgs_vars: orgs_vars
orgs: Engineering
controller_configuration_object_diff_tasks:
- {name: controller_credentials, tags: credentials}
- {name: controller_projects, tags: projects}
- {name: controller_inventories, tags: inventories}
- {name: controller_hosts, tags: hosts}
- {name: controller_job_templates, tags: job_templates}
roles:
- koios.configuration_extended.filetree_read
- koios.configuration_extended.object_diff
- koios.configuration.dispatch
object_diff compares the platform of the selected group with the tree of its environment (common and, for example,
pro). Deleting env/common/controller_job_templates.d/db.yml and running ansible-playbook -i inventory drop_diff.yml -l pro deletes that job template from the pro platform; a host removed from env/pro/controller_hosts.d/ is deleted
the same way. If two groups point to the same platform, the objects of the other environment that are not in the selected
tree are deleted too.
Warning
object_diff deletes every object of the compared types that is not in the tree. Review the lists it computes before
applying them (for example with a task that prints the items with state: absent), and do not include object types
that are shared between organizations, such as organizations, users, teams, credential types or instance groups,
unless the repository describes all of them.