An Ansible Collection is a packaged distribution format for Ansible content. It groups related components together so they can be installed, versioned, and shared as a single unit.
A collection can include:
- Modules
- Roles
- Playbooks
- Plugins (lookup, filter, callback, inventory, connection, etc.)
- Documentation
- Tests
Why use collections?
Collections help you:
- Organize automation code into reusable packages.
- Install functionality independently of Ansible itself.
Collection structure
A typical collection looks like this:
ansible_collections/
└── my_namespace/
└── my_collection/
├── docs/
├── plugins/
│ ├── modules/
│ ├── filter/
│ └── lookup/
├── roles/
├── playbooks/
├── tests/
├── galaxy.yml
└── README.md
Installing a collection
Install from Ansible Galaxy:
ansible-galaxy collection install community.general
Install a specific version:
ansible-galaxy collection install community.general:8.5.0
List installed collections:
ansible-galaxy collection list
Using a collection
Reference modules with their fully qualified collection name (FQCN):
- hosts: localhost
tasks:
- name: Create a file
ansible.builtin.file:
path: /tmp/test.txt
state: touch
Or use modules from another collection:
- hosts: localhost
tasks:
- name: Install package
community.general.homebrew:
name: wget
state: present
Creating a new collection
Generate a skeleton:
ansible-galaxy collection init my_namespace.my_collection
This creates:
my_namespace/
└── my_collection/
├── galaxy.yml
├── README.md
├── plugins/
├── roles/
└── docs/
Building a collection
Package it into a tarball:
ansible-galaxy collection build
Example output:
my_namespace-my_collection-1.0.0.tar.gz
Installing a local collection
ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz
Popular collections
Some commonly used collections include:
ansible.builtin– Core modules included with Ansible.community.general– A large set of community-maintained modules.community.docker– Docker automation.kubernetes.core– Kubernetes management.amazon.aws– AWS cloud automation.azure.azcollection– Microsoft Azure automation.google.cloud– Google Cloud automation.
Example playbook
- hosts: localhost
gather_facts: false
tasks:
- name: Create directory
ansible.builtin.file:
path: /tmp/demo
state: directory
- name: Copy file
ansible.builtin.copy:
content: "Hello Ansible"
dest: /tmp/demo/hello.txt
TASK:
- Download WAR file into the /tmp directory.
- Copy WAR file to /opt/tomcat/webapps/.
- Set permissions to 755 for the WAR file.
- Change ownership to tomcat:tomcat.
- Restart Tomcat service to apply changes.
