Let's say you have a master playbook, and in the master playbook you want to run roles "foo" and "bar". This could be done using:

• roles
• import_playbook
• include_role (this article)
• include_tasks
• import_tasks

Let's say you have the following structure.

├── /usr/local
│   ├── main.yml
│   ├── roles
│   │   ├── foo
│   │   ├── ├── tasks
│   │   ├── ├── ├── main.yml
│   │   ├── bar
│   │   ├── ├── tasks
│   │   ├── ├── ├── main.yml

Here is a simple example of how roles "foo" and "bar" could be run using include_role. This assumes that the "foo" and "bar" roles are included in one of your roles search directories.

---
- hosts: localhost
  tasks:
  - name: include_role 'foo'
    include_role:
      name: foo

  - name: include_role 'bar'
    include_role:
      name: bar
...

Let's say you are using when to do something like this.

---
- hosts: all
  roles:
    - role: foo
      when: x is defined

    - role: bar
      when: y is defined
...

This is not ideal, as each task in the playbook that is not used will be skipped, making for a messy ansible.log that might have a bunch of "skipping" tasks.

TASK [/etc/ansible/roles/foo: foo test] 
ok: [server1.example.com] => {
    "msg": "Hello World"
}
 
TASK [/etc/ansible/roles/bar: bar test] 
skipping: [server1.example.com]

Sometimes, it's better to use include_role.

---
- hosts: all
  tasks:
    - name: include_role 'foo' when x is defined
      include_role:
        name: foo
      when: x is defined

    - name: include_role 'bar' when y is defined
      include_role:
        name: bar
      when: y is defined
...

Now, the role will be skipped without iterating through each task in the role.

TASK [/etc/ansible/roles/foo: foo test] 
ok: [server1.example.com] => {
    "msg": "Hello World"
}

tasks_from

By default, the tasks in the main.yml file in the role will be invoked. In this example, the tasks in roles/foo/tasks/main.yml would be run.

- name: include_role 'roles/foo/tasks/main.yml'
  include_role:
    name: foo

If you have other yaml files in the role tasks directory, such as roles/foo/tasks/bar.yml, the tasks_from parameter can be used to invoke the tasks in bar.yml.

- name: include_role 'roles/foo/tasks/bar.yml'
  include_role:
    name: foo
    tasks_from: bar

Including variables (vars and vars_from)

By default, if there is a "vars" directory that contains a main.yml file in the same directory as the role, the variables in the vars main.yml file will be available in the tasks main.yml file.

roles/foo/tasks/main.yml
roles/foo/vars/main.yml

If you have other yaml files in the role vars directory, such as roles/foo/vars/bar.yml, the vars_from parameter can be used to include the variable in bar.yml.

---
- hosts: all
  tasks:
  - name: include the variables in roles/foo/vars/bar.yml
    include_role:
      name: foo
      vars_from: bar
...

Or, variables can be define using vars.

---
- hosts: all
  tasks:
  - include_role:
      name: foo
    vars:
      bar: Hello World
...

apply delegate_to

Here is how you can use delegate_to to run all of the tasks in the "foo" role on localhost.

---
- hosts: all
  tasks:
  - include_role:
      name: foo
      apply:
        delegate_to: localhost
...