What is an Ansible collection?

An Ansible collection is a standardized, shareable package that bundles various types of Ansible content, designed to streamline the organization, distribution, and consumption of automation.

What is an Ansible Collection?

An Ansible collection serves as a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. It's essentially a structured directory containing all the necessary components for a specific automation domain or vendor. This packaging method significantly enhances the reusability and maintainability of Ansible automation across different projects and teams.

Prior to collections, Ansible content was often distributed as separate roles on Ansible Galaxy or individual playbooks. Collections bring a cohesive approach by grouping related components, such as a set of modules for managing a cloud provider, alongside their corresponding roles, plugins, and documentation, into a single, versioned unit.

Key Components Within an Ansible Collection

A collection can encompass a wide array of Ansible content, making it a powerful packaging mechanism. These are the primary types of content you'll find:

Modules: Custom action plugins that extend Ansible's capabilities to manage specific resources or interact with APIs.
Plugins: Various types of plugins, including:
- action plugins (for custom actions)
- cache plugins (for fact caching)
- callback plugins (for custom output)
- filter plugins (for Jinja2 templating)
- lookup plugins (for data retrieval)
- connection plugins (for managing connection types)
Roles: Reusable, self-contained units of automation that organize tasks, handlers, and variables.
Playbooks: Files that define the automation workflow, orchestrating tasks using modules and roles.
Module Utilities: Python code shared by multiple modules within the collection.
Documentation: User guides, examples, and module documentation.
Tests: Automation tests for the collection's content.

Why Use Ansible Collections?

Collections offer several compelling advantages for managing and sharing Ansible content:

Improved Organization: They provide a clear, standardized structure for related content, making it easier to find and manage specific automation components.
Enhanced Reusability: By packaging modules, roles, and plugins together, collections promote consistent reuse across multiple projects, reducing duplication of effort.
Simplified Distribution: Collections are easily distributed and installed from centralized repositories like Ansible Galaxy or private Pulp 3 Galaxy servers.
Better Versioning: Collections can be versioned independently, allowing users to depend on specific versions of automation content without impacting other parts of their Ansible environment.
Modularity and Scoping: They allow for better isolation of content, enabling developers to build, test, and release specific automation components independently.
Community and Vendor Support: Many vendors and the Ansible community actively develop and maintain official collections, providing robust and well-supported automation.

How to Work with Collections

Working with Ansible collections involves installation and then referencing their content using a Fully Qualified Collection Name (FQCN).

Installation

You can install and use collections through a distribution server, such as Ansible Galaxy, or a Pulp 3 Galaxy server. The primary tool for this is ansible-galaxy:

ansible-galaxy collection install <namespace>.<collection_name>[:<version>]
# Example: Installing the latest version of the community.general collection
ansible-galaxy collection install community.general
# Example: Installing a specific version
ansible-galaxy collection install community.general:1.3.0

This command downloads the specified collection and makes its content available for use by your Ansible environment.

Usage

When using content from a collection, you typically refer to it using its FQCN, which follows the format <namespace>.<collection_name>.<content_name>.

For example, to use the ini_file module from the community.general collection:

---
- name: Configure an INI file using a collection module
  hosts: localhost
  tasks:
    - name: Ensure example.ini has a specific setting
      community.general.ini_file:
        path: /tmp/example.ini
        section: database
        option: host
        value: db.example.com
        state: present

You can also specify a collections key in your playbook or role to define a search path for collections, which can reduce the need for FQCNs for modules within those listed collections, improving readability.

Collection Structure (Anatomy)

A typical Ansible collection directory structure looks like this:

Directory	Description
`galaxy.yml`	Metadata file for the collection (name, version, authors).
`docs/`	Collection-specific documentation and examples.
`plugins/`	Contains various plugin types (e.g., `modules/`, `action/`, `filter/`, `lookup/`).
`roles/`	Contains Ansible roles specific to the collection.
`playbooks/`	Example playbooks or playbooks meant for direct use.
`module_utils/`	Python files that can be imported and shared by modules.
`tests/`	Unit and integration tests for the collection's content.

Distribution and Sharing of Collections

Collections are primarily shared and discovered via Ansible Galaxy, which acts as a central hub for the Ansible community to share their automation content. Organizations can also set up private Galaxy servers (e.g., using Pulp 3) to host and manage their internal collections, ensuring control over their automation supply chain. This distributed nature allows for rapid deployment and updates of specialized automation across various environments.

An Ansible collection fundamentally revolutionizes how Ansible content is organized, distributed, and consumed, making automation more modular, reusable, and manageable for both individual users and large enterprises.