Network Automation with Red Hat Ansible Automation Platform

Use the ansible.builtin.import_role module in a task to statically import a role. Use the ansible.builtin.include_role module in a task to dynamically include a role.

The following play demonstrates how you can import a role by using a task with the ansible.builtin.import_role module. The example play runs the task called A normal task first, and then imports the role2 role:

- name: Run a role as a task
  hosts: ios
  tasks:
    - name: A normal task
      ansible.builtin.debug:
        msg: 'first task'
    - name: A task to import role2 here
      ansible.builtin.import_role:
        name: role2

With the ansible.builtin.import_role module, Ansible treats the role as a static import and parses it during initial playbook processing.

In the preceding example, when the playbook is parsed, Ansible performs the following tasks:

You can also set variables for the role when you call the task, in the same way that you can set task variables:

- name: Run a role as a task
  hosts: ios
  tasks:
    - name: A task to include role2 here
      ansible.builtin.import_role:
        name: role2
      vars:
        var1: val1
        var2: val2

The ansible.builtin.include_role module works in a similar way, but it dynamically includes the role when the playbook is running instead of statically importing it when the playbook is initially parsed.

One key difference between the two modules is how they handle task-level keywords, conditionals, and loops:

In addition, when you include a role, its role variables and default variables are not exposed to the rest of the play, unlike when you import a role.

Another way you can call roles in a play is to list them in a roles section. The roles section is similar to the tasks section, except instead of having a list of tasks, it has a list of roles.

In the following example play, the role1 role runs first, followed by the role2 role:

---
- name: A play that only has roles
  hosts: ios
  roles:
    - role: role1
    - role: role2

For each specified role, the role's tasks, variables, and dependencies are imported into the play in the order in which they are listed.

When you use a roles section to import roles into a play, the roles run before any tasks that you define for that play. Roles are run before tasks whether the roles section is listed before or after the tasks section.

- name: Roles always run first
  hosts: ios
  tasks:
    - name: A task
      ansible.builtin.debug:
        msg: "This task runs after the role."
  roles:
    - role: role1

Because roles run first, it generally makes sense to list the roles section before the tasks section, if you must have both.

The following example sets values for the var1 and var2 variables, which are associated with the role2 role. If the var1 and var2 variables are defined in the defaults or vars directories for the role2 role, then the variables are overridden when the role2 role is used.

---
- name: A play that runs the second role with variables
  hosts: ios
  roles:
    - role: role1
    - role: role2
      var1: val1
      var2: val2

Another equivalent playbook syntax that you might see in this case is as follows:

---
- name: A play that runs the second role with variables
  hosts: ios
  roles:
    - role: role1
    - { role: role2, var1: val1, var2: val2 }

This can be harder to read in some situations, even though it is more compact.

roles:
  - { role: role1, service: "httpd" }
  - { role: role2, var1: true }
  - { role: role1, service: "httpd" }

roles:
  - { role: role1, service: "httpd" }
  - { role: role2, var1: true }
  - { role: role1, service: "syslogd" }

Two special task sections, pre_tasks and post_tasks, are occasionally used with roles sections. The pre_tasks section is a list of tasks, similar to tasks, but these tasks run before any of the roles in the roles section.

Plays also support a post_tasks keyword. These tasks run after the play's tasks.

The following play shows an example with pre_tasks, roles, tasks, and post_tasks. It is unusual that a play would contain all four sections.

- name: Play to illustrate order of execution
  hosts: ios
  pre_tasks:
    - name: This task runs first
      ansible.builtin.debug:
        msg: This task is in pre_tasks
      notify: my handler
      changed_when: true
  roles:
    - role: role1
  tasks:
    - name: This task runs after the roles
      ansible.builtin.debug:
        msg: This task is in tasks
      notify: my handler
      changed_when: true
  post_tasks:
    - name: This task runs last
      ansible.builtin.debug:
        msg: This task is in post_tasks
      notify: my handler
      changed_when: true