What is Ansible Collection?

Ansible Collections are a standardized packaging format for distributing Ansible content (roles, modules, plugins, playbooks, and documentation). Introduced in Ansible 2.9+, collections allow you to easily share, install, and manage sets of automation assets together.

• A collection organizes content under a common namespace and name (e.g., community.mysql).
• It may include:
  • Roles
  • Playbooks
  • Modules
  • Plugins (lookup, filter, callback, etc.)
  • Documentation and tests

Before Collections

Earlier, most content was shipped with Ansible or required to be managed separately as roles (via Ansible Galaxy). There was no simple, standard bundle for sharing custom modules, plugins, and roles together. Collections solve these challenges by grouping and versioning all content for modular use and distribution.

Why Do We Need Ansible Collections?

• Modularity: Package all automation content (plugins, modules, roles, playbooks, docs) together, decoupled from Ansible core.
• Versioning: Install and use specific versions, enabling more reliable dependency management for automations.
• Distribution: Distribute content via platforms like Ansible Galaxy, Automation Hub, or private repositories.
• Community & Vendor Content: Use well-defined namespaces (e.g., community.general, cisco.ios) for community- or vendor-created collections.
• Upgrades and Maintenance: Update collections independently of Ansible engine, making it easier to keep automation content up to date.

How to Use Ansible Collections

1. Installing a Collection

Install a collection from Galaxy or Automation Hub:

bashansible-galaxy collection install community.mysql

• By default, collections are installed to ~/.ansible/collections or globally if run as root.

Install a specific version:

bashansible-galaxy collection install community.mysql:==3.8.0

2. Listing Installed Collections

bashansible-galaxy collection list

3. Using Collection Content in Playbooks

• Modules/Plugins: Use the Fully-Qualified Collection Name (FQCN), e.g., community.mysql.mysql_db.

text- name: Create a MySQL database
  hosts: dbservers
  tasks:
    - name: Create database
      community.mysql.mysql_db:
        name: example
        state: present
        login_user: root
        login_password: s3cret

• Roles: Reference within roles section:

textroles:
  - role: community.mysql.mysql_role

• Plugins: Loaded automatically when present in installed collections.

4. Using Collections in the collections: Block

You can reduce boilerplate by declaring required collections at the playbook level:

text---
- hosts: all
  collections:
    - community.mysql
  tasks:
    - mysql_db:
        name: test
        state: present

• The task will now use community.mysql.mysql_db as just mysql_db.

5. Using Collections in Requirements

Declare project dependencies in a requirements.yml:

textcollections:
  - name: community.mysql
    version: ">=3.8.0,<4.0.0"
  - name: amazon.aws

Install all requirements:

bashansible-galaxy collection install -r requirements.yml

How to Create an Ansible Collection

1. Initialize a Collection Skeleton

bashansible-galaxy collection init my_namespace.my_collection

• Produces my_namespace/my_collection/ with directories for plugins, roles, docs, tests, etc.

2. Add Content

• Place modules in plugins/modules/
• Put roles in roles/
• Add filter plugins, lookup plugins, etc., in corresponding plugin directories.
• Add documentation in docs/
• Write tests in tests/

3. Edit galaxy.yml

Defines collection metadata, dependencies, authors, etc.

• Namespace and name
• Description
• License, etc.

4. Build the Collection Package

From the root collection directory:

bashansible-galaxy collection build

• Creates a .tar.gz distributable artifact.

5. Publish or Share

• Publish to Ansible Galaxy (requires account): bashansible-galaxy collection publish ./my_namespace-my_collection-*.tar.gz
• Or upload to Automation Hub/private repo.

Advanced: Developing & Testing a Collection

• Use ansible-test for unit and integration tests (tests/ directory).
• Use molecule for role/playbook scenario testing (see [previous suggestions]).

Other Important Details/Missing Info

• Namespace Conventions: Namespace must be unique (vendor, project, or username; lowercase, no spaces).
• Dependencies: List other collections as dependencies in galaxy.yml (dependencies: key).
• Documentation: Each module, role, or plugin should have YAML/Markdown docs for Galaxy rendering.
• Collection Path Precedence: Ansible resolves content in this order: playbook/project collections/ → user’s default location → system path.
• Backward Compatibility: Older content (roles, modules) should be refactored into collections for modern workflows.
• Private Collections: You can run your own Galaxy/Automation Hub server for internal sharing.

Summary Table

Action	Command/Step
Install a collection	ansible-galaxy collection install <namespace>.<name>
Use a module from a collection	namespace.collection.module or via collections: block
List installed collections	ansible-galaxy collection list
Initialize a collection skeleton	ansible-galaxy collection init ns.coll
Build collection for distribution	ansible-galaxy collection build
Publish to Galaxy	ansible-galaxy collection publish <tarball>
Add dependencies in collection	Edit galaxy.yml (dependencies section)
Use dependencies in project	Add to requirements.yml, then install

References

• [Official Ansible Collections Documentation]
• [Ansible Galaxy Collections Guide]
• [Red Hat Automation Hub Collection Info]

: https://docs.ansible.com/ansible/latest/dev_guide/collections_tech.html
: https://galaxy.ansible.com/docs/collections.html
: https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.5/html-single/getting_started_with_automation_hub/index

In summary:
Ansible Collections are a modern, standardized mechanism to organize, share, and version all types of Ansible content. You use them to install and consume content (modules, roles, plugins) with clear namespaces and manageable dependencies. You create them with ansible-galaxy collection init, add content, build, and (optionally) publish. They are essential for scale, modularity, and modern Ansible workflows.