Ansible Roles vs Collections

Roles organize tasks within a project into reusable units (tasks/handlers/templates/vars/defaults/files). Collections are distributable packages containing roles + modules + plugins + playbooks + documentation. Role = small reusable component inside a project. Collection = complete automation package shared across projects and teams.

Overview

Two levels of reuse

Ansible provides two levels of reuse: Roles within a project and Collections across projects and teams. The hierarchy is simple: Collections contain Roles, which contain Tasks.

Roles

A Role organizes related tasks, handlers, templates, files, variables and defaults into a named directory structure. Roles move complexity out of playbooks into reusable, testable units. A "webserver" role encapsulates everything needed to install, configure and manage Nginx, so the playbook simply says "apply role webserver to these hosts."

Collections

A Collection is a distributable package that bundles roles, modules, plugins, playbooks and documentation. Collections are the modern standard for sharing automation across organizations. Published on Ansible Galaxy or Automation Hub, they are versioned, can declare dependencies, and hold custom Python modules and filter plugins under a namespace.

Real-world example

"webserver" Role — Installs and configures Nginx
"infra" Collection — The Nginx role, custom AWS modules, monitoring playbooks and deployment documentation, packaged as a single installable unit

When to use each

Roles — Organizing automation within a single project
Collections — Sharing automation across multiple projects, teams or the community

> [!IMPORTANT] Modern Ansible heavily emphasizes Collections; all official Ansible content ships as Collections.

Key concepts

Role: A named directory structure (tasks/handlers/templates/vars/defaults/files) that encapsulates a piece of automation. Used within a playbook via the roles: keyword. Copied manually or installed via ansible-galaxy role install.
Collection: A distributable package installed via ansible-galaxy collection install . Can contain roles, modules, plugins, playbooks, and docs. Versioned with semantic versioning. The standard for sharing Ansible content in Ansible 2.10+.
ansible-galaxy: CLI tool for installing roles and collections. ansible-galaxy role install , ansible-galaxy collection install . requirements.yml can list all dependencies for a project.
tasks/main.yml: Entry point for a Role's task list. Ansible automatically looks for this file when the role is applied. Can include other task files with include_tasks or import_tasks.
defaults vs vars: defaults/main.yml has the lowest variable precedence — easily overridden by the playbook or inventory. vars/main.yml has higher precedence. Use defaults for values users should be able to override; use vars for values the role needs to enforce.
FQCN (Fully Qualified Collection Name): The format namespace.collection.module for referencing modules in Collections (e.g., amazon.aws.ec2_instance). Required when multiple collections have modules with the same short name. Recommended practice in all modern playbooks.

When to use it

Structuring a new Ansible project — always use Roles to keep playbooks clean
Building reusable automation for multiple teams — package as a Collection
Installing community automation from Galaxy (ansible-galaxy collection install community.general)
Building custom Python modules that multiple projects need — ship in a Collection
Versioning and releasing automation as an artifact — Collections support semantic versioning

Interview questions

What is the difference between an Ansible Role and a Collection?
How do you structure an Ansible project for a multi-tier application?