Ansible: What's the difference between task, role, play and playbook?

Question

Ansible has tasks, roles, plays and playbooks.

Are those just names for different levels in a playbook organization?

If not, how, exactly, do they differ from and relate to each other?

Answer 1

No, each has a different role and way of working.

Starting with the easy ones:

A playbook is simply a list of plays. The highest level of a playbook YAML is a list, and on that list only two things are accepted: a play definition or the keyword import_playbook, which imports a list of plays from another playbook file, as if they were defined in that place of the calling file.

The playbook is also the only thing that can be called directly from ansible-playbook.

A task is, paraphrasing the manual, 'nothing more than a call to an ansible module'. That call definition, however, knows nothing of on which hosts it is supposed to run on.

The play is the element that ties tasks to the servers where they'll run. The key element here is the mandatory keyword hosts. This is the part of Ansible that tells which hosts are being affected and how.

So, the structure and behavior is as follows:

• Playbook: the highest level, just a list of plays
  • Play: ties tasks to host lists
    • Tasks: definition of a call to a module
    • Besides tasks, a play may have pre-tasks, post-tasks and handlers, which are all task-like, and roles.

A role is a different thing, as it is not defined within a playbook. Instead, they each have their own subdirectory under the directory roles. The objective of roles is to organize things. So, under the role's subdir, you can find tasks, handlers, files and templates, variables and defaults. All of these related to that specific role.

So, roles are an easy way to encapsulate and share Ansible information. You could have a subdir in templates per task, for example. But if you wanted to share that task, you'd have to pick the template as well. With roles, you can just zip the role dir and (almost) everything should be there.

Like a play, the role defines tasks and handlers. However, roles do not define on which hosts the role will be run. So roles must be referenced to from a play.

Roles can also declare dependencies (that is, references to other roles that need to be run before the declaring one).

---

PS1. Most of this information is available piecemeal on SO (except for playbooks, I couldn't find a proper definition of that on the documentation or elsewhere in the Internet), but I haven't found a comparison between them all, and it took me some time to figure this all out, so I'm sharing that by answering my own question.

PS2. I really don't like the fact that roles are named 'roles'. It sounds a bit counter intuitive to me. The word 'role' alone alludes to user roles or server roles, to me. So something more related to Tower (users) or inventory (servers). I think the rationale for that naming is that they define 'one of the roles that a server functions'. Same could be said of plays, but roles are more abstract as they're not tied to specific hosts. Still, I find that naming confusing.

Edit

A handler functions for the most part just like a task. However, it is not executed by default, with the other tasks, during the playbook run. Instead, each individual handler will be executed only if notified by a task.

On a task definition, the keyword notify identifies the handlers the task wants to notify. If the task is executed and reports a changed state (not ok nor failed), then the handler will be marked for execution.

After all roles and tasks have run, each notified handler will be executed, in the order they appear in the file. Check the docs for details.

Tasks will always run (unless skipped with when), and are responsible for the actual changes you want to implement. Handlers will be run only in response to tasks making changes, and are generally responsible for finalization steps (restart or reload a service that has had its configuration changed to make it effective, for example).

You could probably replicate handlers behavior with tasks, but it is such a recurring pattern that Ansible provides handlers as a helper.