Ansible Playbooks vs Roles

ansible

According to the Ansible docs, a Playbook
is:

…the basis for a really simple configuration management and multi-machine deployment system, unlike any that already exist, and one that is very well suited to deploying complex applications.

And, again, according to those same docs, a Role
are:

…ways of automatically loading certain vars_files, tasks, and handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.

However the distinction between these and their different use cases is not immediately obvious to me. For instance, if I configure my /etc/ansible/hosts file to look like:

[databases]
mydb01.example.org
mydb02.example.org

[mail_servers]
mymail01.example.org
mymail_dr.example.org

…then what is this "[databases]" entry…a role? Or the name of a playbook YAML file somewhere? Or something else?!?

If someone could explain to me the differences on these, my understanding of Ansible would be greatly enhance!

Playbook vs Role vs [databases] and similar entries in /etc/ansible/hosts
If Playbooks are defined inside of YAML files, then where are Roles defined?
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?

Best Answer

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.

Related Solutions

Safely limiting Ansible playbooks to a single machine

Turns out it is possible to enter a host name directly into the playbook, so running the playbook with hosts: imac-2.local will work fine. But it's kind of clunky.

A better solution might be defining the playbook's hosts using a variable, then passing in a specific host address via --extra-vars:

# file: user.yml  (playbook)
---
- hosts: '{{ target }}'
  user: ...

Running the playbook:

ansible-playbook user.yml --extra-vars "target=imac-2.local"

If {{ target }} isn't defined, the playbook does nothing. A group from the hosts file can also be passed through if need be. Overall, this seems like a much safer way to construct a potentially destructive playbook.

Playbook targeting a single host:

$ ansible-playbook user.yml --extra-vars "target=imac-2.local" --list-hosts

playbook: user.yml

  play #1 (imac-2.local): host count=1
    imac-2.local

Playbook with a group of hosts:

$ ansible-playbook user.yml --extra-vars "target=office" --list-hosts

playbook: user.yml

  play #1 (office): host count=3
    imac-1.local
    imac-2.local
    imac-3.local

Forgetting to define hosts is safe!

$ ansible-playbook user.yml --list-hosts

playbook: user.yml

  play #1 ({{target}}): host count=0

Playbooks in a subdirectory, not next to group_vars

Ansible will pick up group_vars without stating path explicitly:

Here is the example directory structure in /tmp/ansible:

/tmp/ansible
├── group_vars
│   └── test_group.yml
├── inventory
├── playbooks
│   └── foo.yml
└── site.yml

Inventory file:

[test_group]
localhost

Main Playbook site.yml:

# site.yml
---
- include: playbooks/foo.yml

Secondary Playbook foo.yml:

---
- hosts: localhost

  tasks:

      - debug: var=foo

Group Variables test_group.yml:

foo: bar

Here are all the ways to execute the secondary playbook:

From root folder using relative path /tmp/ansible:

ansible-playbook -i inventory playbooks/foo.yml -c local

PLAY [localhost] **************************************************************

GATHERING FACTS ***************************************************************
ok: [localhost]

TASK: [debug var=foo] *********************************************************
ok: [localhost] => {
    "var": {
        "foo": "bar"
    }
}

PLAY RECAP ********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0

From Playbooks subfolder with inventory in parent path /tmp/ansible/playbooks:

ansible-playbook -i ../inventory foo.yml -c local

PLAY [localhost] **************************************************************

GATHERING FACTS ***************************************************************
ok: [localhost]

TASK: [debug var=foo] *********************************************************
ok: [localhost] => {
    "var": {
        "foo": "bar"
    }
}

PLAY RECAP ********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0

As we can see in the above examples, ansible-playbook will look for variables based on the path of inventory file or folder were ansible was executed from. Playbooks can be separated without additional effort.

Best Answer

Related Solutions

Safely limiting Ansible playbooks to a single machine

Playbooks in a subdirectory, not next to group_vars

Related Topic