Ansible Inventory Project

A structured collection of files used for managing hosts and configurations. It typically includes inventory files, playbooks, host configurations, group variables, and Ansible vault files.
Categories:
Tags:

An inventory project, also known as an Ansible inventory project, is a structured collection of files used in Ansible for managing hosts and configurations. It typically includes inventory files, playbooks, host variables, group variables, and secret variables ( Ansible vault files). This type of project is sometimes referred to as a playbook project or configuration project.

These projects are structured to be used and consumed by Ansible Automation Platform ( AAP) or AWX.

The inventory strategy of C2 Platform projects can be described as group-based environments with dictionary merging. This approach helps manage multiple environments efficiently, promotes a GitOps workflow, and enables flexible variable handling. The sections below explore the key components, examples, and core concepts of this strategy in detail.

Structure of an Inventory Project

Examples of such projects include  c2platform/ansible,  c2platform/rws/ansible-gis,  c2platform/phx/ansible.

Within  c2platform/rws/ansible-gis you can find:

  1. hosts.ini: The inventory file containing host configurations. It defines Ansible groups including the environment groups and supports allowing organization of hosts by roles, environments (e.g., development, test, staging, production), or attributes.

  2. group_vars: A directory that stores group variables for the Ansible groups defined in the inventory file.

  3. plays: directory that contains Ansible playbooks, for example the play that manages the Geoweb sub-system of the GIS Platform which is based on Vertigis Studio:

     plays/gis/geoweb.yml

    ---
- name: Geoweb
  hosts: geoweb

  roles:
    - { role: c2platform.wincore.win, tags: ["windows"]}
    - { role: c2platform.gis.vertigis_studio, tags: ["geoweb", "vertigis", "studio", "reporting"]}

  4. secret_vars: A dedicated location for storing secrets. For further details see Managing Secrets with Ansible Vault in AAP / AWX .

  5. collections/requirements.yml: File used by Ansible Automation Platform AAP (or AWX) to install Ansible collections from Ansible Galaxy.

     collections/requirements.yml

    ---
collections:
  - name: community.postgresql
    version: 2.4.3
  - name: ansible.windows
    version: 1.14.0
  - name: community.windows
    version: 2.0.0
  - name: c2platform.gis
    version: 1.0.21
  - name: c2platform.mgmt
    version: 1.0.4
  - name: https://gitlab.com/c2platform/ansible-collection-mw.git
    type: git
    version: master
  # - name: c2platform.mw
  #   version: 1.0.4  # TODO 1.0.5
  - name: c2platform.dev
    version: 1.0.4

  6. roles/requirements.yml: Similar to collections/requirements.yml, also used by AAP (or AWX) to install Ansible roles, from Galaxy.

  7. ansible.cfg: This file contains configuration settings for Ansible, including defaults for module behavior, inventory paths, and roles. You can also configure a private Galaxy Server here.

     ansible.cfg

    [defaults]
hash_behaviour = merge
collections_path=../ansible-dev-collections:./
roles_path=./roles/external:./roles/internal
ansible_managed = This file is managed by Ansible, all changes will be lost.
display_skipped_hosts = no
stdout_callback = yaml
# callbacks_enabled=ansible.posix.profile_tasks, ansible.posix.timer
# callbacks_enabled=ansible.posix.profile_roles, ansible.posix.timer

Group-based Environments

As part of the group-based environments approach, for each environment (development, test, staging, production) there is a corresponding Ansible group, also known as an Ansible environment group. For example, in hosts.ini on lines 32 to 37 an Ansible group test (for the test environment) is defined with 5 nodes in it. The group-based environments approach makes it possible to manage environment differences much more effectively. For more information about group-based environments:

  • Group-based Environments: Use a group-based approach to organize your Ansible inventory and variables for different environments.

 hosts.ini

32[test]
33gst-rproxy1         ansible_host=1.1.5.209
34gst-awx1            ansible_host=1.1.5.164
35gst-db1             ansible_host=1.1.5.210
36gst-fme-core        ansible_host=1.1.8.118
37gst-ad              ansible_host=1.1.8.119

GitOps

The term GitOps is typically used in the context of cloud-native applications but also applies to Ansible automation projects. The setup enables a pure GitOps approach by treating Ansible playbooks, inventories, and variables as declarative code stored in Git, providing a complete definition and single source of truth. For each environment a branch is created, an environment branch, that is the single source of truth for a specific environment.

Key principles of GitOps include:

  • Declarative Configuration: Configurations describe the desired state of the system, rather than imperative steps to achieve it.
  • Single Source of Truth: The Git repository serves as the canonical source for all configurations and desired states.
  • Automation / Reconciliation: Tools continuously observe changes in the Git repository and automatically apply them, reconciling the current state with the desired state.

Pure GitOps

In a pure GitOps approach, avoid storing desired state anywhere outside the Git repository, as this can lead to inconsistencies and deviations from the single source of truth. Instead, maintain the complete definition of all environments—including nodes, roles, and configurations—solely within the inventory project in Git. For example, do not pass desired state via Azure DevOps or GitLab CI/CD pipeline variables, and avoid defining inventories or variables directly in AAP/ AWX; these should reference the Git repository to ensure all state is managed declaratively through Git.

GitOps Pipeline

A key concept in GitOps with Ansible (with environment branches) is the GitOps pipeline, which leverages group-based environments (with Ansible environment groups) and environment branches to promote changes safely. For example, changes can be promoted across environments (e.g., from development to production) using merge requests (MRs) in tools like GitLab and Azure DevOps with approval processes. This process ensures that updates are reviewed, tested, and reconciled automatically, maintaining consistency and reducing manual intervention.

The GitOps pipeline is not a GitLab CI/CD pipeline, but it can be part of one. The GitOps pipeline consists of MRs and a tool that takes care of the automation/reconciliation part. Typically projects use Ansible Automation Platform ( AAP) but if that is not available a GitLab Runner for example can be used as is the case in the PHX project.

For more information on using a GitLab Runner as a control node see:

For more information on branching and merging see:

Dictionary Merging

The term dictionary merging refers to a well-known but very powerful feature of Ansible to merge dictionaries. Note that we are not referring to explicit merging using the Ansible Jinja filter ansible.builtin.combine. We are referring to the global feature to merge dictionaries always. It is turned off by default and can be enabled by configuring hash_behaviour as merge in ansible.cfg as shown in the example below:

 ansible.cfg

hash_behaviour = merge

For more information:

Additional Information

For further reference, explore the following guidelines:


Last modified September 30, 2025: concept inventory project PHX-199 (087baca)