Organizing and Distributing Ansible Code Using Collections

Initially, the administrator needs to configure Apache on Linux systems running RedHat. The playbook uses two basic Ansible modules and runs in root mode.

The playbook looks straightforward. It’s easy to read and use. Full control over configuration steps is exposed to the user, who can define target servers, root operations, and other low-level technical details.

Another system required handling Debian packages, so this new playbook was created.

Again, it’s a trivial playbook with just a change to the package manager and the Apache package name. Let’s combine both to maintain only one playbook with universal Debian/RedHat logic.

The combined version is a little more complex, harder to read, and more fragile. However, it is still a very simple example. In real life, the code will be much more complex, and exposing such code to others becomes risky.

In the next step, I’ll present how to encapsulate the code in a fundamental Ansible element — the Role. For the price of a few additional development steps, an Ansible Role provides more benefits in enterprise environments.

The initial code directly used Ansible Modules - atomic Ansible steps, used to build playbooks. Now the code will be refactored to utilize Ansible Roles.

Ansible Modules and Roles serve different purposes in the automation ecosystem. A module is a single, self-contained unit of work that performs a specific task, such as installing a package (yum, apt), or copying files (copy). Modules are the fundamental building blocks in Ansible; each task in a playbook typically invokes a module to carry out a particular action on the managed hosts.

In contrast, a role is a higher-level organizational structure that groups together multiple related tasks, along with their defaults, handlers, templates, files, and variables. Roles provide a standardized way to package and reuse automation logic, making it easy to share and apply complex configurations across different projects or environments. By organizing content into roles, you can separate concerns, promote consistency, and reduce duplication in your automation code.

As Ansible role requires specific directory structure it’s handy use ansible tool to initialize the directory.

This creates a full role skeleton in roles/apache/ with the standard Ansible structure for the role:

It’s important to understand each place in a role hierarchy, however not all of them are critical for regular use. Here is a list of critical directories:

Role delivers multiple features, however on this stage we are interested in roles/apache/tasks/main.yml file to move playbook’s core logic to this place.

Now the complexity is encapsulated in Ansible Role, and the user see only top level technical function - make apache up and running.

Having above Role ready, the playbook may be super simple. It’s even more simple that the initial one. All the complexity is hidden now in Role and the administrator calls pure business need to activate apache.

Note that one more element should be simplified - the root control, by moving Ansible’s "become" to the lower level. It will be done later during refactoring supported by Molecule testing.

The examples above show a natural evolution: starting from a simple RedHat-only playbook, extending it to support Debian systems, and finally moving the complexity into an Ansible Role. While using roles helps organize and encapsulate the automation logic, the traditional approach of copying playbooks and roles between multiple projects remains problematic.

Duplicating these playbooks and roles across projects leads to multiple copies that can diverge over time, causing version drift and inconsistencies. This fragmentation makes it difficult to maintain and update automation content effectively, as changes applied in one place are not automatically reflected elsewhere. Let’s imagine that tha playbook was used by multiple users, who copied it to their environments. Does not smell good.

As a result, version control becomes scattered, and managing updates requires significant manual effort and coordination. Although this approach may work for small environments, enterprise-scale automation demands better separation of concerns, strict versioning, and mechanisms that prevent code duplication to ensure maintainability and consistency across teams.

One may argue that a role can be stored in its own Git repository and then included in a project. This approach indeed solves some challenges, such as version control and reuse across multiple playbooks. However, it still leaves other problems unresolved — for example, potential naming clashes, the lack of a consistent packaging format, and difficulties in managing dependencies.

Using just Ansible Roles is a partial solution, as role was introduced for soke purposes, Ansible community noticed a need to make next step. Finally as for today all aspects of domain specific logic are packaged in Ansible Collection.

Collections are top level distribution components used world-wide by all small and corporate size providers. On the other hand collection are super easy to use and maintain, giving enterprise level capabilities to Ansible adopters.

As discussed earlier, modules are the smallest building blocks in Ansible, performing atomic actions within tasks. Roles group tasks and related content into reusable units, sitting one level above modules. Collections extend this concept further by packaging roles, modules, plugins, and documentation together into a single, distributable format.

Collections sit at the top of the hierarchy as the primary packaging layer. They address challenges around sharing, versioning, and dependency management across projects—problems that roles alone cannot fully solve. Collections are therefore essential for maintaining consistency and scalability in larger automation environments.

Like roles, collections are based on a strict directory structure. Ansible provides tooling to scaffold the initial directory layout.

The ansible-galaxy utility creates the directory structure for a collection. Unlike role creation, you must provide both a namespace and a collection name. For example, using myorg.unix (myorg as the namespace, unix as the collection name):

This command creates a full collection skeleton in the myorg/unix/ directory with the standard structure. Note the roles directory, which will contain all roles belonging to the collection.

The previously created apache role can be moved into the collection under myorg/unix/roles/apache/. The role structure remains the same, and the tasks will continue to function without modification.

In this tutorial, the collection is kept in the Ansible-aware collections/ansible_collections directory to make it directly available for playbooks. This works for special cases but is not suitable for regular enterprise usage. Before use, the collection should be installed to the proper location.

The installation location is configurable, but for now, we will use the default (~/.ansible). Ansible defines a standard way to bring a collection from any location into the local execution environment, supporting sources such as Galaxy, Git, URL, file directory, or subdirectories.

Typically, collection installation is managed via a requirements.yml file that specifies dependencies:

With requirements.yml ready, install the dependencies using the ansible-galaxy tool:

You can verify that the collection is available:

With the role now inside the collection and the collection installed, you can reference it in your playbook:

Note the namespace prefix (myorg.unix). This allows you to use an apache role supplied by different authors, as collections use namespaces to avoid naming conflicts.

Roles already provide organization and reusability, but collections extend these advantages significantly. A collection can bundle roles together with modules, plugins, and documentation in one package. You no longer need to manage these elements separately across projects.

While roles can be versioned (e.g., via Git tags or Galaxy releases), the mechanism is mostly ad hoc and external. Collections, by contrast, make versioning a first-class feature: every collection carries a version in its galaxy.yml, and dependencies on other collections can be declared in a structured way. This makes it easier to control upgrades, avoid incompatibilities, and ensure consistency across environments.

Another key benefit is unified distribution. While roles can be shared via Galaxy, GitHub, or private repositories, collections package multiple content types (roles, modules, plugins, documentation) together. This makes installation, versioning, and sharing more consistent and predictable, especially in larger environments.

In summary, collections are the natural next step after roles: they enhance reusability, standardize version control, and provide the dependency management needed for automation at scale.