Skip to content

Roles

What You'll Learn

  • Why roles exist, and what breaks without them
  • The standard role directory structure, and what each part is for
  • The line between a role and "just splitting a playbook into files"

Why Roles Exist

Without roles, teams end up copy-pasting the same task blocks (install nginx, configure firewall rules, create app users) across every playbook that needs them. A role packages that logic — tasks, handlers, default variables, templates, files, and metadata — into one reusable unit that can be dropped into a different project unmodified.

A role is the unit of reuse and distribution. Splitting one long playbook into multiple files with include_tasks/import_tasks is a different, smaller problem — see Module Decision Trees: Role vs. Task Include for exactly where that line is.

Read in this order

  1. Role Structure — the standard directory layout, and what auto-wires without any extra config
  2. Role Variables and Interfaces — designing a role's public "API" via defaults/
  3. Production Role Design — single-responsibility roles, testing, dependency management

Next

Continue to Collections — the mechanism for packaging and distributing roles (and modules, and plugins) together.