What Are Ansible Collections? Modules, Roles & Plugins Packages (Guide)

Ansible collections are a key feature that enhances modularity and reusability in automation workflows. They bundle content such as modules, plugins, roles, and documentation into a standardized format. This article explains what Ansible collections are, their structure, and how to use them.

What Are Ansible Collections?

Ansible collections are distributable packages of Ansible content, designed to organize and share automation resources. They are hosted in repositories like Ansible Galaxy or private registries, making it easier to manage and reuse automation code.

Key Features of Collections:

• Modularity: Collections group related content, simplifying distribution and use. • Organization: Provide a structured way to manage custom and community-contributed content. • Standardization: Use a consistent directory layout for easy integration.

See also: Where Are Ansible Collections Installed? Default Paths & Management

Structure of an Ansible Collection

A collection has a predefined directory structure:

my_collection/
├── docs/
├── plugins/
│   ├── modules/
│   ├── inventory/
│   ├── lookup/
│   └── filter/
├── roles/
├── playbooks/
├── tests/
└── galaxy.yml

Key Components:

plugins/: Contains custom modules, inventory plugins, lookup plugins, and filters. roles/: Stores roles for task execution. playbooks/: Includes example playbooks for using the collection. docs/: Provides documentation for the collection. galaxy.yml: Metadata file defining the collection name, description, dependencies, and version.

Benefits of Using Ansible Collections

Reusable Content: Collections allow teams to package and share automation resources, reducing redundancy. Scalability: Modular content simplifies scaling automation across projects. Community Contributions: Access thousands of collections in Ansible Galaxy to accelerate development. Versioning and Dependencies: Manage specific versions and dependencies to ensure compatibility.

See also: Ansible Collections: What They Are & How to Use Them (2026 Guide)

How to Use Ansible Collections

1. Installing a Collection

Use the ansible-galaxy command to install collections from Ansible Galaxy or private repositories.

   ansible-galaxy collection install community.general
   

2. Using Modules from a Collection

Reference modules within a collection in your playbooks:

   - name: Use a module from a collection
     community.general.ping:
   

3. Specifying Collections in Playbooks

Define required collections at the beginning of your playbook:

   ---
   collections:
     - community.general
   

4. Creating Your Own Collection

Generate a new collection using the ansible-galaxy command:

   ansible-galaxy collection init my_namespace.my_collection
   

Customize the structure and add your content.

Popular Collections on Ansible Galaxy

community.general: A collection of common modules and plugins. amazon.aws: Modules and plugins for managing AWS resources. vmware.vmware_rest: Tools for automating VMware infrastructure. kubernetes.core: Modules for managing Kubernetes clusters.

See also: What Are Ansible Roles: Complete Guide to Role Structure (2026)

Best Practices for Ansible Collections

• Use Namespaces: Prefix collections with unique namespaces to avoid conflicts. • Document Thoroughly: Provide clear documentation in the docs/ directory. • Follow Standards: Adhere to the collection directory structure for compatibility. • Version Control: Maintain versioning to track updates and dependencies.

Conclusion

Ansible collections streamline modular automation by bundling related content into reusable packages. Whether you're building custom automation workflows or leveraging community resources, collections enhance collaboration, scalability, and efficiency.

Explore Ansible Collections on Ansible Galaxy

What's in a Collection?

namespace.collection_name/
  plugins/
    modules/          # Ansible modules
    inventory/        # Inventory plugins
    lookup/           # Lookup plugins
    filter/           # Jinja2 filter plugins
    callback/         # Callback plugins
    connection/       # Connection plugins
  roles/              # Bundled roles
  playbooks/          # Example playbooks
  docs/               # Documentation
  MANIFEST.json       # Metadata

Popular Collections

| Collection | Purpose | |-----------|---------| | ansible.builtin | Core modules (included) | | community.general | 1000+ community modules | | amazon.aws | AWS automation | | azure.azcollection | Azure automation | | community.docker | Docker management | | containers.podman | Podman management | | ansible.posix | POSIX systems (firewalld, etc.) | | ansible.windows | Windows automation | | kubernetes.core | Kubernetes management |

Install Collections

# From Galaxy
ansible-galaxy collection install community.general
# Specific version
ansible-galaxy collection install amazon.aws:==7.0.0
# From requirements file
ansible-galaxy collection install -r requirements.yml
# To custom path
ansible-galaxy collection install community.docker -p ./collections

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: amazon.aws
  - name: community.docker

Use Collections

Fully Qualified Collection Name (FQCN)

- name: Install package
  ansible.builtin.apt:
    name: nginx
- name: Manage Docker container
  community.docker.docker_container:
    name: myapp
    image: nginx:latest
- name: Create S3 bucket
  amazon.aws.s3_bucket:
    name: my-bucket
    region: us-east-1

collections keyword

- hosts: all
  collections:
    - community.general
    - ansible.posix
  tasks:
    - timezone:  # Short name (community.general.timezone)
        name: UTC

Collections vs Roles

| Feature | Collection | Role | |---------|-----------|------| | Contains | Modules + roles + plugins | Tasks + files + templates | | Scope | Extend Ansible capabilities | Reusable task bundles | | Install | ansible-galaxy collection | ansible-galaxy role | | Namespace | namespace.name | author.rolename | | Distribution | Galaxy / Automation Hub | Galaxy / Git |

List Installed Collections

ansible-galaxy collection list
ansible-galaxy collection list community.general

Create a Collection

ansible-galaxy collection init myorg.mytools

# galaxy.yml
namespace: myorg
name: mytools
version: 1.0.0
dependencies:
  ansible.builtin: ">=2.15"

# Build and publish
ansible-galaxy collection build
ansible-galaxy collection publish myorg-mytools-1.0.0.tar.gz

FAQ

Do I need to install ansible.builtin?

No — it's included with Ansible. All ansible.builtin.* modules are always available.

What's the difference between Galaxy and Automation Hub?

Galaxy is the public community repository. Automation Hub is Red Hat's certified, supported collection source for AAP subscribers.

Should I use FQCN or short names?

Always use FQCN in production. Short names can conflict between collections and make debugging harder.

Related Articles

• the Ansible Galaxy reference • building an Ansible inventory • AWS automation with Ansible • role variables and defaults in Ansible