Structuring Ansible Projects

Problem

In Dutch government organizations, teams often begin Ansible automation with limited knowledge and no clear structure for organizing project artifacts. This leads to disorganized inventories, duplicated efforts, difficulty in reusing code across environments, and challenges in scaling as projects grow more complex.

Context

Ansible projects can be categorized into types like inventory projects for managing hosts and desired state configurations, Ansible collection projects for packaging reusable content such as roles, and execution environment projects for bundling dependencies. Understanding these types helps teams start simply and progressively adopt more advanced structures. This is especially relevant in government contexts where security, compliance, and collaboration are key, often aligning with GitOps practices for version-controlled deployments.

Solution

Follow a phased approach to structure your Ansible projects, starting from basic setups and advancing as needs grow:

1. Begin with an Inventory Project: Create an inventory project as your starting point. Define hosts in an inventory file (e.g., hosts.ini) and write simple playbooks containing tasks directly. Use group variables and host variables to store configurations.

2. Introduce Roles Locally: As playbooks grow, extract reusable logic into Ansible roles. Place them in a roles/ directory within the inventory project for easy inclusion in playbooks.

3. Transition to Collections: Once roles mature, create a separate Ansible collection project. Move roles into the collection’s structure (e.g., roles/ inside the collection). Set up a dedicated release pipeline (e.g., via GitLab CI/CD) to publish versions to Ansible Galaxy or a private repository, separate from the inventory project’s GitOps pipeline.

4. Centralize Role Development: Shift all role development to the collection project(s). Remove the roles/ directory from the inventory project, referencing published collections instead via requirements.yml.

5. Optimize with Execution Environments: For further efficiency, create an execution environment project to package Python, Ansible Core, and dependencies into a container image. Progress in steps:

   • Start with just the Python and Ansible runtime.
   • Add community collections.
   • Include your own collections. This ensures consistent, isolated executions, especially in Ansible Automation Platform setups.

   Note: Integrating custom execution environments can challenge pure GitOps workflows. For solutions, refer to the following information

   • GitOps Pipeline for an Execution Environment (EE) with Ansible Collections

Adopt Git repositories for each project type, using merge requests for changes and ensuring documentation follows Ansible standards.

Benefits

• Scalability: Start simple and add complexity as needed, avoiding overwhelming beginners.
• Reusability: Collections enable sharing content across projects and teams, reducing duplication.
• Efficiency: Separate pipelines for releases and deployments streamline workflows.
• Consistency: Execution environments ensure reproducible runs, minimizing dependency issues.
• Collaboration: Structured projects facilitate teamwork in government settings with version control and clear guidelines.

Alternatives (Optional)

While standalone Ansible role projects exist, they are deprecated in favor of collections for better organization and versioning. Avoid scattering content across unstructured repositories; instead, consolidate into dedicated project types for maintainability.

Examples and Implementation

Example Inventory Project Structure

In the Ansible inventory project for C2 Platform  c2platform/c2/ansible-inventory there is a roles directory which contains a file requirements.yml. This file is used by Ansible Automation Platform to download Ansible roles from Galaxy

 roles/requirements.yml

---
- src: ajsalminen.hosts
# version: N.A.
- src: arillso.logrotate
  version: 1.6.1
- src: geerlingguy.apache
  version: 3.2.0
- src: geerlingguy.git
  version: 3.0.0
- src: galaxyproject.postgresql
  version: 1.1.0
- src: geerlingguy.docker
  version: 4.2.2
- src: lean_delivery.weblogic
  version: 1.0.0
- src: racqspace.microk8s
  version: 2.2.1
- src: geerlingguy.gitlab
  version: 3.2.0
- src: robertdebock.gitlab_runner
  version: 5.1.4

You can create Ansible roles inside this directory. For example, create a new Ansible role my_local_role. Then, include it in a sample playbook (e.g., plays/site.yml):

For more information on how to set up the Ansible inventory project refer to:

• 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.

Transitioning to a Collection

Refer to the C2 Platform Core collection  c2platform.core for an example. It includes, for example, the Linux role  c2platform.core.linux. This Core collection includes a GitLab CI/CD pipeline that publishes to Galaxy, as you can see in the example below.

 .gitlab-ci.yml

82
83publish:
84  stage: galaxy
85  needs: [prepare, build, yamllint, ansible-lint]
86  script:
87    - cat README-GALAXY.md > README.md  # readme property in galaxy.yml is ignored by galaxy website
88    - ansible-galaxy collection build . --force
89    - ansible-galaxy collection publish $C2_NAMESPACE-$C2_NAME-$C2_VERSION.tar.gz --api-key $GALAXY_API_KEY
90  when: manual

In the Ansible inventory project for C2 Platform  c2platform/c2/ansible-inventory there is also a collections/requirements.yml file, that includes a dependency on the Core collection.

 collections/requirements.yml

1---
2collections:
3  - name: c2platform.core
4    version: 1.0.24  # TODO 1.0.25

Execution Environment Example

Refer to the following for more information:

• Manage the RWS Ansible Execution Environment: This guide provides step-by-step instructions on how to manage the RWS Ansible Execution Environment, ensuring compatibility with the latest Python and Ansible versions, along with the required Ansible collections.
• GitOps Pipeline for an Execution Environment (EE) with Ansible Collections: Learn how to realize a GitOps Pipeline when using an EE that includes Ansible Collections.

Additional Information

• Ansible Projects: Ansible Inventory, Ansible Collection, Ansible Role, and Ansible Execution Environment are different types of projects related to Ansible. This section provides an overview of each project type and their significance in the Ansible ecosystem.
• 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.
• Ansible Mirror Inventory Project: An open-source specialized Ansible inventory project that integrates Vagrant functionality to simulate real-world infrastructure locally for development and testing.
• Ansible Collection Project: An Ansible Collection project is a comprehensive unit that combines modules, plugins, roles, and documentation to enhance the automation language and manage infrastructures. It serves as a reusable and distributable package of Ansible content.
• Ansible Execution Environment Project: The Ansible Execution Environment project provides a standardized environment for executing Ansible playbooks and roles.
• Ansible Role Project ( deprecated ): An Ansible Role project is a structured and reusable collection of tasks, variables, and configurations that provide specific functionality.
• Manage the RWS Ansible Execution Environment: This guide provides step-by-step instructions on how to manage the RWS Ansible Execution Environment, ensuring compatibility with the latest Python and Ansible versions, along with the required Ansible collections.
• GitOps Pipeline for an Execution Environment (EE) with Ansible Collections: Learn how to realize a GitOps Pipeline when using an EE that includes Ansible Collections.