Ansible Collections

Ansible started as one big package that held every module. The package grew too large and slow to update. Collections solved the problem by splitting content into smaller bundles. A collection packages modules, plugins, roles, and documentation under one name. Compare a music streaming service with a giant CD box set: a listener subscribes to the albums wanted rather than carrying every disc.

Naming with Namespaces

Every collection name has two parts, a namespace and a collection name, separated by a dot.

CollectionNamespaceContent
ansible.builtinansibleCore modules such as copy, file, and service
community.generalcommunityHundreds of general purpose modules
amazon.awsamazonAWS resources
kubernetes.corekubernetesKubernetes objects
ansible.posixansiblePOSIX tools such as firewalld and mount

A fully qualified collection name (FQCN) combines the collection and the module, such as ansible.builtin.copy. Using the full name removes any doubt about which module runs.

Diagram: What a Collection Contains

  community.general
  ┌───────────────────────────────┐
  │ plugins/                      │
  │   ├── modules/    (ufw, ...)  │
  │   ├── filters/                │
  │   ├── lookup/                 │
  │   └── inventory/              │
  │ roles/                        │
  │ playbooks/                    │
  │ docs/                         │
  │ galaxy.yml  (name, version)   │
  └───────────────────────────────┘

Install a Collection

ansible-galaxy collection install community.general
ansible-galaxy collection install amazon.aws:==7.2.0
ansible-galaxy collection list

Collections download to ~/.ansible/collections by default. The setting collections_path in ansible.cfg moves them into the project, which keeps projects self-contained.

Install from a Requirements File

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: amazon.aws
  - name: kubernetes.core
ansible-galaxy collection install -r requirements.yml

Use a Collection in a Playbook

Call a module through its full name.

- name: Open the firewall for web traffic
  hosts: webservers
  become: true
  tasks:
    - name: Allow HTTP through UFW
      community.general.ufw:
        rule: allow
        port: '80'
        proto: tcp

Declare a search list at play level to shorten names.

- hosts: webservers
  collections:
    - community.general
  tasks:
    - name: Allow HTTP
      ufw:
        rule: allow
        port: '80'

The full name remains the safer habit, since it prevents clashes when two collections ship a module with the same name.

Browse Documentation

ansible-doc community.general.ufw
ansible-doc -l community.general

Create Your Own Collection

Companies bundle internal modules and roles into a private collection.

ansible-galaxy collection init mycompany.tools
cd mycompany.tools
ansible-galaxy collection build

The build command produces a .tar.gz archive. Upload it to Ansible Galaxy, a private Automation Hub, or any file server, and teammates install it with the same ansible-galaxy collection install command.

mycompany.tools/
├── galaxy.yml
├── README.md
├── plugins/
│   └── modules/
└── roles/

Collections Versus Roles

FeatureRoleCollection
Holds tasks and templatesYesYes, through bundled roles
Holds modules and pluginsLimitedYes
Versioned namespaceLooseStrict
Best forOne automation jobShared toolkit for many jobs

Try This

Install community.general with the galaxy command. Run ansible-doc community.general.timezone and read the options. Write a playbook that sets the time zone of a lab machine with the fully qualified module name.

Summary

Collections package modules, plugins, roles, and documentation into versioned bundles with namespaces. The ansible-galaxy collection commands install and list them, and a requirements file pins versions. Fully qualified names prevent module clashes. Teams build private collections to share internal automation.