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

koios.controller

automation controller

koios.platform

platform gateway: organizations, teams, users, authentication

koios.eda

Event-Driven Ansible

koios.hub

automation hub

koios.configuration

roles that apply a whole configuration (dispatch)

koios.configuration_extended

configuration read from a directory tree (filetree_read) and deletion of what was removed from it (object_diff)

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.yml publishes them there (see below).

  • Ansible Galaxy: ansible-galaxy collection install koios.configuration_extended installs 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

koios.controller

awx.awx

ansible.controller

koios.platform

— (AWX has no platform gateway)

ansible.platform

koios.eda

ansible.eda (with a standalone EDA server)

ansible.eda

koios.hub

ansible.hub (with a standalone Galaxy NG)

ansible.hub

koios.configuration

infra.controller_configuration

infra.aap_configuration

koios.configuration_extended

infra.controller_configuration (filetree_read, object_diff)

infra.aap_configuration_extended

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.awx needs CONTROLLER_OPTIONAL_API_URLPATTERN_PREFIX=/api/controller/ to reach automation controller through the platform gateway. The awx.awx 24.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.controller and ansible.platform are not on Ansible Galaxy; use the ones of the execution environment or of the platform automation hub.

  • With infra.aap_configuration, do not follow object_diff with the whole dispatch role: it runs a role that uses the ansible.controller.application module, which current automation controller no longer has. koios.configuration does not have that role, so dispatch can follow object_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, awx and ansible namespaces 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.