Ansible Collections

What are Collections? Collections are Ansible's distribution format for bundled content including playbooks, roles, modules, and plugins. They provide a way to package and distribute related automation content with proper versioning and namespacing.

Understanding Collections

What is a Collection?

Collections represent the modern way to distribute Ansible content. A collection can include:

Modules - Task plugins for automation
Roles - Reusable automation units
Playbooks - Complete automation workflows
Plugins - All plugin types (callback, inventory, lookup, filter, etc.)
Documentation - Integrated docs for all content

Collection Namespace

Collections use a two-part namespace format: namespace.collection_name

Namespace: The organization or author (e.g., ansible, community, amazon)
Collection Name: The specific collection (e.g., builtin, general, aws)
Example: community.general, ansible.posix, amazon.aws

Installing Collections

Basic Installation

Install collections using the ansible-galaxy collection install command:

# Install from Ansible Galaxy
ansible-galaxy collection install community.general

# Install specific version
ansible-galaxy collection install community.general:==5.0.0

# Install with version range
ansible-galaxy collection install 'community.general:>=5.0.0,<6.0.0'

# Install to specific path
ansible-galaxy collection install community.general -p ./collections

Default Installation Location

Collections are installed to ~/.ansible/collections by default. You can customize this with:

-p or --collections-path option
COLLECTIONS_PATHS in ansible.cfg
ANSIBLE_COLLECTIONS_PATH environment variable

Version Constraints

Supported version operators:

== - Exact version
>= - Greater than or equal
> - Greater than
<= - Less than or equal
< - Less than
!= - Not equal
* - Latest version

Pre-release Versions: ansible-galaxy ignores pre-release versions by default. To install a pre-release, use the == operator with the exact version.

Using Requirements Files

requirements.yml Format

Manage multiple collections with a requirements file:

---
collections:
  # Install latest version
  - name: community.general

  # Install specific version
  - name: ansible.posix
    version: "1.4.0"

  # Install version range
  - name: amazon.aws
    version: ">=5.0.0,<6.0.0"

  # Install from custom source
  - name: my_namespace.my_collection
    source: https://galaxy.example.com
    version: "1.0.0"

  # Install from Git repository
  - name: namespace.collection
    source: git+https://github.com/organization/repo.git
    type: git
    version: main

Installing from Requirements File

# Install all collections in requirements.yml
ansible-galaxy install -r requirements.yml

# Force reinstallation
ansible-galaxy install -r requirements.yml --force

# Install to specific path
ansible-galaxy install -r requirements.yml -p ./collections

Using Collections in Playbooks

Fully Qualified Collection Names (FQCN)

Reference collection content using FQCN format:

---
- name: Using FQCN for modules
  hosts: localhost
  tasks:
    - name: Ensure package is installed
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Use community module with FQCN
      community.general.docker_container:
        name: my_container
        image: nginx:latest
        state: started

Using the collections Keyword

Simplify references with the collections keyword:

---
- name: Using collections keyword
  hosts: all
  collections:
    - community.general
    - ansible.posix

  tasks:
    - name: Module without FQCN (searches collections list)
      docker_container:
        name: web_server
        image: nginx
        state: started

    - name: Another module from the collection
      selinux:
        policy: targeted
        state: enforcing

Important: If your playbook uses both the collections keyword and roles, the roles do NOT inherit the collections set by the playbook. Roles must define their own collection search order.

Collections in Roles

Roles can define collections in meta/main.yml:

# roles/myrole/meta/main.yml
---
collections:
  - community.general
  - ansible.posix

dependencies: []

Running Playbooks from Collections

Since Ansible 2.11, you can distribute and run playbooks directly from collections:

# Run playbook from collection
ansible-playbook my_namespace.my_collection.deploy_app -i inventory.ini

# List playbooks in a collection
ansible-playbook my_namespace.my_collection --list

Naming Rules: Playbook names in collections must contain only lowercase letters, numbers, and underscores, and must start with a letter. Dashes are not allowed.

Collection Structure

A typical collection directory structure:

my_namespace/
└── my_collection/
    ├── README.md
    ├── galaxy.yml              # Collection metadata
    ├── plugins/
    │   ├── modules/
    │   │   └── my_module.py
    │   ├── inventory/
    │   ├── lookup/
    │   ├── filter/
    │   └── callback/
    ├── roles/
    │   ├── role1/
    │   └── role2/
    ├── playbooks/
    │   └── deploy.yml
    ├── docs/
    ├── tests/
    └── meta/
        └── runtime.yml          # Plugin routing

Alternative Installation Sources

Install from Git Repository

# Install from Git
ansible-galaxy collection install git+https://github.com/organization/collection_repo.git

# Install specific branch or tag
ansible-galaxy collection install git+https://github.com/org/repo.git,main
ansible-galaxy collection install git+https://github.com/org/repo.git,v1.0.0

Install from Local Tarball

# Install from downloaded tarball
ansible-galaxy collection install /path/to/my_namespace-my_collection-1.0.0.tar.gz

# Install from directory
ansible-galaxy collection install /path/to/my_namespace/my_collection/

Install from Custom Galaxy Server

# Install from custom server
ansible-galaxy collection install my_namespace.my_collection \
  --server https://galaxy.example.com

# Configure in ansible.cfg
[galaxy]
server_list = my_galaxy

[galaxy_server.my_galaxy]
url=https://galaxy.example.com
token=my_api_token

Managing Collections

List Installed Collections

# List all installed collections
ansible-galaxy collection list

# List collections in specific path
ansible-galaxy collection list -p ./collections

# Show collection details
ansible-galaxy collection list community.general

Download Collections

# Download without installing (for offline use)
ansible-galaxy collection download community.general

# Download specific version
ansible-galaxy collection download community.general:5.0.0

# Download with dependencies
ansible-galaxy collection download -r requirements.yml -p ./collection-tarballs

Verify Collections

# Verify collection integrity
ansible-galaxy collection verify community.general

# Verify all installed collections
ansible-galaxy collection verify --collections-path ~/.ansible/collections

Collection Signatures

Verify signed collections for security:

# Install with signature verification
ansible-galaxy collection install community.general \
  --keyring ~/.ansible/pubring.kbx

# Configure in ansible.cfg
[galaxy]
gpg_keyring = ~/.ansible/pubring.kbx
required_valid_signature_count = 1

Creating Your Own Collection

Initialize Collection Structure

# Create collection skeleton
ansible-galaxy collection init my_namespace.my_collection

# Creates directory structure:
# my_namespace/
# └── my_collection/
#     ├── README.md
#     ├── galaxy.yml
#     ├── plugins/
#     ├── roles/
#     ├── playbooks/
#     └── docs/

galaxy.yml Metadata

---
namespace: my_namespace
name: my_collection
version: 1.0.0
readme: README.md
authors:
  - Your Name 
description: Collection for managing applications
license:
  - GPL-3.0-or-later
tags:
  - automation
  - deployment
dependencies: {}
repository: https://github.com/my_namespace/my_collection
documentation: https://docs.example.com
homepage: https://example.com
issues: https://github.com/my_namespace/my_collection/issues

Building and Publishing

# Build collection tarball
ansible-galaxy collection build

# Publish to Galaxy (requires API token)
ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz \
  --api-key=your_galaxy_api_token

Best Practices

Collection Best Practices:

Use FQCN: Always use fully qualified names for clarity and to avoid conflicts
Pin Versions: Specify exact versions in requirements.yml for reproducibility
Local Installation: Install collections in project directory for portability
Document Dependencies: Clearly document required collections in your README
Test Collections: Test with multiple Ansible versions before publishing
Semantic Versioning: Follow semantic versioning (MAJOR.MINOR.PATCH)
Changelog: Maintain a changelog for your collections
Verify Signatures: Use signature verification for security-critical environments

Common Issues

Collection Not Found

If Ansible can't find your collection:

Check COLLECTIONS_PATHS in ansible.cfg
Verify installation with ansible-galaxy collection list
Ensure correct namespace and collection name
Check file permissions on collection directory

Module Not Found

If a module from a collection isn't found:

Use FQCN: namespace.collection.module_name
Verify collection is installed
Check the collections keyword is in the correct scope
For roles, verify collections are set in meta/main.yml

Version Conflicts

When multiple collections have dependencies:

Use --force to reinstall specific versions
Check dependency tree with ansible-galaxy collection list
Pin exact versions in requirements.yml
Consider using separate collection paths for different projects

Popular Collections

Collection	Description	Common Use Cases
`ansible.builtin`	Core Ansible modules	Basic operations, files, packages, services
`community.general`	General community modules	Docker, system tools, cloud utilities
`ansible.posix`	POSIX system modules	SELinux, ACLs, authorized_keys, firewall
`amazon.aws`	AWS cloud modules	EC2, S3, RDS, Lambda management
`azure.azcollection`	Microsoft Azure modules	Azure resource management
`google.cloud`	Google Cloud Platform	GCP resource management
`kubernetes.core`	Kubernetes management	K8s resources, Helm charts
`community.docker`	Docker management	Containers, images, networks, volumes
`community.postgresql`	PostgreSQL database	Database and user management
`community.mysql`	MySQL/MariaDB database	Database operations

Next Steps

Ansible Galaxy - Discover and share collections
Roles - Create reusable role content
Custom Modules - Build your own modules
Best Practices - Collection development patterns

Try in Playground Practice in Labs

Getting Started

Content Distribution

Core Concepts

Platforms

Development

Infrastructure

Operations

Security

Enterprise