There are a few different ways to invoke one or more roles in a playbook.

• roles
• import_playbook
• import_role (this article)
• include_role
• 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

And the foo role creates and then deletes the /tmp/foo.txt file and the bar role creates and then deletes the /tmp/bar.txt file.

~]$ cat roles/foo/tasks/main.yml
- name: touch /tmp/foo.txt
  ansible.builtin.file:
    path: /tmp/foo.txt
    state: touch

- name: delete /tmp/foo.txt    
  ansible.builtin.file:
    path: /tmp/foo.txt
    state: absent

~]$ cat roles/bar/tasks/main.yml
- name: touch /tmp/bar.txt
  ansible.builtin.file:
    path: /tmp/bar.txt
    state: touch
    
- name: delete /tmp/bar.txt    
  ansible.builtin.file:
    path: /tmp/bar.txt
    state: absent  

Your main.yml playbook could have the following, to import the foo and bar roles. This assumes that the "foo" and "bar" roles are included in one of your roles search directories.

---
- hosts: localhost
  tasks:
  - name: import_role foo
    ansible.builtin.import_role:
      name: foo

  - name: import_role bar
    ansible.builtin.import_role:
      name: bar
...

Running the main.yml playbook should return the following.

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

TASK [Gathering Facts] ***************************************************************************************************************************************************************************************
ok: [localhost]

TASK [import_role foo] **************************************************************************************************************************************************************************************

TASK [foo : touch /tmp/foo.txt] ******************************************************************************************************************************************************************************
changed: [localhost]

TASK [foo : delete /tmp/foo.txt] *****************************************************************************************************************************************************************************
changed: [localhost]

TASK [import_role bar] **************************************************************************************************************************************************************************************

TASK [bar : touch /tmp/bar.txt] ******************************************************************************************************************************************************************************
changed: [localhost]

TASK [bar : delete /tmp/bar.txt] *****************************************************************************************************************************************************************************
changed: [localhost]

PLAY RECAP ***************************************************************************************************************************************************************************************************
localhost                  : ok=5    changed=4    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Let's say you want to skip the import_role using a when statement, perhaps something like this.

---
- hosts: localhost
  tasks:
  - name: import_role foo
    ansible.builtin.import_role:
      name: foo
    when: x is defined

  - name: import_role bar
    ansible.builtin.import_role:
      name: bar
    when: y is defined      
...

Since both x and y are undefined in this example, the tasks in each role will be skipped.

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

TASK [Gathering Facts] ***************************************************************************************************************************************************************************************
ok: [localhost]

TASK [import_role foo] **************************************************************************************************************************************************************************************

TASK [foo : touch /tmp/foo.txt] ******************************************************************************************************************************************************************************
skipping: [localhost]

TASK [foo : delete /tmp/foo.txt] *****************************************************************************************************************************************************************************
skipping: [localhost]

TASK [import_role bar] **************************************************************************************************************************************************************************************

TASK [bar : touch /tmp/bar.txt] ******************************************************************************************************************************************************************************
skipping: [localhost]

TASK [bar : delete /tmp/bar.txt] *****************************************************************************************************************************************************************************
skipping: [localhost]

PLAY RECAP ***************************************************************************************************************************************************************************************************
localhost                  : ok=5    changed=4    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Better yet, you could use include_role. One thing that is really nice about include_role is that if the when statement does not evaluate to true the role will just totally be skipped and you won't get a bunch of output with "skipping" tasks.

---
- hosts: all
  tasks:
  - name: include_role foo when x is defined
    ansible.builtin.include_role:
      name: foo
    when: x is defined

  - name: include_role bar when y is defined
    ansible.builtin.nclude_role:
      name: bar
    when: y is defined
...

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

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

TASK [Gathering Facts] ***************************************************************************************************************************************************************************************
ok: [localhost]

TASK [include_role foo] **************************************************************************************************************************************************************************************
skipping: [localhost]

TASK [include_role bar] **************************************************************************************************************************************************************************************
skipping: [localhost]

PLAY RECAP ***************************************************************************************************************************************************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=2    rescued=0    ignored=0

Let's say the foo and bar roles directories contain multiple YAML files.

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

Perhaps main.yml creates /tmp/foo.txt and other.yml deletes /tmp/foo.txt.

~]$ cat roles/foo/tasks/main.yml
- ansible.builtin.file:
    path: /tmp/foo.txt
    state: touch

~]$ cat roles/foo/tasks/other.yml
- ansible.builtin.file:
    path: /tmp/foo.txt
    state: absent

tasks_from can be used to specify the YAML file in the role directory that you want to import.

---
- hosts: localhost
  tasks:
  - name: import_role foo main.yml
    ansible.builtin.import_role:
      name: foo
      tasks_from: main.yml

  - name: import_role foo other.yml
    ansible.builtin.import_role:
      name: foo
      tasks_from: other.yml
...

Running the main.yml playbook should return the following.

Running the main.yml playbook should return the following.

~]$ ansible-playbook main.yml
PLAY [localhost] 

TASK [Gathering Facts] 
ok: [localhost]

TASK [touch /tmp/foo.txt] 
changed: [localhost]

TASK [absent /tmp/foo.txt] 
changed: [localhost]

PLAY RECAP 
localhost                  : ok=3    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Be aware that you cannot use loops with import_role. For example, like this.

---
- hosts: localhost
  tasks:
  - ansible.builtin.import_role:
      name: foo
    with_items:
    - /tmp/hello.txt
    - /tmp/world.txt
...

Running a playbook with import_role and loop should return something like this.

ERROR! You cannot use loops on 'import_role' statements. You should use 'include_role' instead.

As the error suggests, use include_role if you want to loop.

---
- hosts: localhost
  tasks:
  - ansible.builtin.include_role:
      name: foo
    with_items:
    - /tmp/hello.txt
    - /tmp/world.txt
...