Organizing and Distributing Ansible Code Using Collections

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.