include_role & import_role at Runtime
Invoke roles dynamically mid-play.
include_role & import_role at Runtime is a free Ansible Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Ansible Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Beyond the roles List
The top-level roles list applies roles before any tasks run. Sometimes you need a role mid-play, exactly where a task sits.
Call a Role as a Task
Both include_role and import_role let you invoke a role from inside the tasks section, in line with your other steps.
tasks:
- import_role:
name: nginximport_role Is Static
import_role is processed when the playbook is parsed, before the run starts. Its tasks are inlined early, so they cannot depend on runtime data.
include_role Is Dynamic
include_role is processed during the run, at the moment that task is reached. It can react to facts and registered results.
tasks:
- include_role:
name: backup
when: do_backupLoop Over a Role
Because include_role runs dynamically, you can put it in a loop and apply the same role with different variables each pass.
- include_role:
name: deploy_app
loop: "{{ app_list }}"import_role Cannot Loop
Since import_role resolves at parse time, it does not support loop. Use include_role whenever you need to repeat a role.
How when Behaves Differs
A when on import_role copies the condition onto every task inside. A when on include_role gates the whole role as one unit.
Pass Variables Either Way
Both forms accept vars to parameterize the role, just like the roles list does. The values flow straight into the included role.
- include_role:
name: web
vars:
http_port: 8080Tags and Static vs Dynamic
With import_role, tags on the imported tasks are visible to --list-tags. With include_role you must apply tags to the include itself.
Pick the Right Tool
Reach for import_role for predictable, always-run structure. Reach for include_role when the role must run conditionally or in a loop.
Same Pattern, Two Levels
Ansible offers the same static-versus-dynamic split for task files: import_tasks and include_tasks mirror these role keywords exactly.
Quick Check
Recall which keyword can apply a role inside a loop.
Recap
Use import_role for static, parse-time structure and include_role for dynamic, runtime invocation with loops and conditions. 🔁
Frequently asked questions
Is the “include_role & import_role at Runtime” lesson free?
Yes — the full text of “include_role & import_role at Runtime” is free to read here on the web, and the Ansible Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Ansible Academy course, upgrade to CoddyKit PRO.
What will I learn in “include_role & import_role at Runtime”?
Invoke roles dynamically mid-play. You practise Ansible Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Ansible Academy?
No prior experience is required. Ansible Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “include_role & import_role at Runtime” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Ansible Academy lesson?
Yes. Every Ansible Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Role Dependencies in meta/main.yml
- defaults vs vars: The Override Order
- include_role & import_role at Runtime
- allow_duplicates & Role Idempotency