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.
| Collection | Namespace | Content |
|---|---|---|
| ansible.builtin | ansible | Core modules such as copy, file, and service |
| community.general | community | Hundreds of general purpose modules |
| amazon.aws | amazon | AWS resources |
| kubernetes.core | kubernetes | Kubernetes objects |
| ansible.posix | ansible | POSIX 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
| Feature | Role | Collection |
|---|---|---|
| Holds tasks and templates | Yes | Yes, through bundled roles |
| Holds modules and plugins | Limited | Yes |
| Versioned namespace | Loose | Strict |
| Best for | One automation job | Shared 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.
