Ansible Playbooks vs Roles

Playbook vs Role vs [databases] and similar entries in /etc/ansible/hosts

[databases] is a single name for a group of hosts. It allows you to reference multiple hosts by a single name.

Role is a set of tasks and additional files to configure host to serve for a certain role.

Playbook is a mapping between hosts and roles.

Example from documentation describes example project. It contains two things:

• Playbooks. site.yml, webservers.yml, fooservers.yml are playbooks.
• Roles: roles/common/ and roles/webservers/ contain definitions of common and webservers roles accordingly.

Inside playbook (webservers.yml) you have something like:

---
- hosts: webservers <- this group of hosts defined in /etc/ansible/hosts, databases and mail_servers in example from your question
  roles: <- this is list of roles to assign to these hosts
     - common
     - webservers

If Playbooks are defined inside of YAML files, then where are Roles defined?

They are defined inside roles/* directories. Roles are defined mostly using YAML files, but can also contain resources of any types (files/, templates/). According to documentation role definition is structured this way:

• If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play
• If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play
• If roles/x/vars/main.yml exists, variables listed therein will be added to the play
• If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles (1.3 and later)
• Any copy tasks can reference files in roles/x/files/ without having to path them relatively or absolutely
• Any script tasks can reference scripts in roles/x/files/ without having to path them relatively or absolutely
• Any template tasks can reference files in roles/x/templates/ without having to path them relatively or absolutely
• Any include tasks can reference files in roles/x/tasks/ without having to path them relatively or absolutely

The most important file is roles/x/tasks/main.yml, here you define tasks, which will be executed, when role is executed.

Aside from the ansible.cfg living on the Ansible server, how do I add/configure Ansible with available Playbooks/Roles? For instance, when I run ansible-playbook someplaybook.yaml, how does Ansible know where to find that playbook?

$ ansible-playbook someplaybook.yaml

Will look for a playbook inside current directory.

$ ansible-playbook somedir/somedir/someplaybook.yaml

Will look for a playbook inside somedir/somedir/ directory.

It’s your responsibility to put your project with all playbooks and roles on server. Ansible has nothing to do with that.