Static and dynamic role reuse · Ansible

There are four ways to pull other content into a play, and they divide into two pairs:

Static — parse time	Dynamic — run time
`roles:` keyword	—
`ansible.builtin.import_role`	`ansible.builtin.include_role`
`ansible.builtin.import_tasks`	`ansible.builtin.include_tasks`

Everything else follows from that one distinction. Static forms are expanded when the playbook is parsed, before a host is contacted. Dynamic forms are a task that runs, and what it pulls in does not exist until it does.

The consequences are operational rather than stylistic, and they are the sort of thing people repeat from memory incorrectly. Every claim below was executed against ansible-core 2.21.3.

What the parser knows

Two roles, alpha and beta. alpha has two tasks, one of them tagged alpha_inner. beta has one. A play imports the first and includes the second, tagging both statements patch:

- name: static versus dynamic
  hosts: web
  gather_facts: false
  tasks:
    - name: static import_role
      ansible.builtin.import_role:
        name: alpha
      tags: [patch]

    - name: dynamic include_role
      ansible.builtin.include_role:
        name: beta
      tags: [patch]

Read-only / Safeask the parser what it assembled— Reads and parses the playbook. Makes no connection and changes nothing.

ansible-playbook -i inventory.ini listtasks.yml --list-tasks

Read-only / Safethe answer, executed on 2.21.3— The imported role is expanded into its individual tasks. The included role is a single line - the include statement itself.

$ ansible-playbook -i inventory.ini listtasks.yml --list-tasks

playbook: listtasks.yml

play #1 (web): static versus dynamic	TAGS: []
  tasks:
    alpha : alpha task one	TAGS: [alpha_inner, patch]
    alpha : alpha task two	TAGS: [patch]
    dynamic include_role	TAGS: [patch]

Read that carefully, because four separate facts are visible in five lines:

The imported role is expanded. Both of alpha’s tasks appear, with the role-name prefix.
Tags on the import statement propagate to every task inside it. Both alpha tasks carry patch, although neither declares it.
A task’s own tags are additive. alpha task one has both alpha_inner and patch.
The included role is one line. beta’s task does not appear at all. The parser does not know what is inside beta, because it has not looked.

The same split applies at task-file level. import_tasks expands; include_tasks does not:

Read-only / Safeimport_tasks versus include_tasks, same file included both ways— Executed. The identical task file appears expanded under the static import and collapsed to one line under each dynamic include.

$ ansible-playbook -i inventory.ini incimp.yml --list-tasks

playbook: incimp.yml

play #1 (local): local	TAGS: []
  tasks:
    shared task one	TAGS: [inner, staticpart]
    shared task two	TAGS: [staticpart]
    dynamic include_tasks	TAGS: [dynpart]
    dynamic include_tasks in a loop	TAGS: []

Why that costs you something

--list-tasks is the cheapest pre-flight check there is. It costs no connection, no time and no risk, and it answers what is this run going to do. A play built from dynamic includes answers that question with a list of include statements.

The same blindness shows up in --list-tags, and there it is worse, because a tag you rely on can be missing from the list entirely:

Read-only / Safea play whose only content is a dynamic include— Executed. The included task file contains a task tagged inner. --list-tags reports no tags at all, because the parser never opened the file.

$ ansible-playbook -i inventory.ini dynonly.yml --list-tags

playbook: dynonly.yml

play #1 (local): local	TAGS: []
    TASK TAGS: []

An operator who runs --list-tags to find out what selections exist, sees nothing, and concludes the play has no tag structure, is reading an accurate report of what the parser knows and a false report of what the play contains.

Blast radius: the dry run under-reports

This is a blast-radius problem, not a tooling annoyance. The pre-flight question is “which hosts, and what will happen to them”. Dynamic includes answer the first half and refuse the second.

For anything that changes production, prefer the static forms so that --list-tasks is a complete answer. Reach for dynamic only when you need what it uniquely gives you — a loop, or a conditional decided from a fact gathered during the run — and when you do, say so in the task name so the next reader knows the dry run is incomplete:

- name: include per-platform hardening (dynamic - not visible to --list-tasks)
  ansible.builtin.include_tasks: "hardening-{{ ansible_facts['os_family'] }}.yml"

What each form can and cannot do

The static forms trade flexibility for visibility, and the trade is enforced rather than advisory. Attempting to loop a static form is a hard parse error with a message that names the fix:

Read-only / Safeloop on import_tasks— Executed. --syntax-check is enough to produce it; the failure is at parse time.

$ ansible-playbook -i inventory.ini importloop.yml --syntax-check

[ERROR]: You cannot use loops on 'import_tasks' statements. You should use 'include_tasks' instead.
Origin: /srv/automation/importloop.yml:4:7

2   gather_facts: false
3   tasks:
4     - name: import_tasks with a loop
      ^ column 7

Read-only / Safeloop on import_role— Executed. Same rule, same shape of message.

$ ansible-playbook -i inventory.ini importroleloop.yml

[ERROR]: You cannot use loops on 'import_role' statements. You should use 'include_role' instead.
Origin: /srv/automation/importroleloop.yml:4:7

2   gather_facts: false
3   tasks:
4     - name: import_role with a loop
      ^ column 7

Summarised:

	`import_role` / `import_tasks`	`include_role` / `include_tasks`
Resolved	Parse time	Run time
Appears in `--list-tasks`	Expanded, task by task	One line for the statement
Tags on the statement	Applied to every task inside	Applied to the statement only
Inner tags visible to `--list-tags`	Yes	No
`loop` on the statement	Parse error	Supported
`when` on the statement	Copied onto every inner task, evaluated per task	Evaluated once, for the include
Filename can be templated from a run-time fact	No	Yes

The when row deserves a sentence. On a static import, when is not evaluated once for the block — it is copied onto each imported task and evaluated individually. Usually indistinguishable, but not always: if an early task in the imported file changes the thing the condition tests, later tasks in the same import can evaluate it differently.

Choosing

The decision is nearly always the same one:

Default to static. roles:, import_role, import_tasks. You get a complete dry run, working --tags, and a --list-tasks you can diff between branches to prove a refactor changed nothing.

Use dynamic when you need what only it does. Three genuine cases:

A loop. Applying a role once per virtual host, per database, per environment.
A path built from run-time information. The per-platform task file selected by ansible_facts['os_family'] cannot be resolved before facts are gathered.
A conditional whose answer is expensive or unknowable at parse time, where you want to skip loading the content at all rather than skip its tasks individually.

Everything else — “it feels cleaner”, “the file is big” — is not a reason, and it costs you the dry run.

The dynamic form’s own conveniences

When you do use include_role, two options are worth knowing.

tasks_from: selects an entry point other than main.yml, which is how a role exposes more than one operation:

Read-only / Safetasks_from and vars on an include— Executed. The first include runs roles/multi/tasks/verify.yml only; the second runs main.yml with a variable supplied at the call site.

$ ansible-playbook -i inventory.ini tasksfrom.yml

TASK [include only the verify entry point] *************************************

TASK [multi : multi verify] ****************************************************
ok: [localhost] => {
  "msg": "verify entry"
}

TASK [include with role vars] **************************************************

TASK [multi : multi main] ******************************************************
ok: [localhost] => {
  "msg": "main entry, greeting=passed-in"
}

- name: include only the verify entry point
  ansible.builtin.include_role:
    name: multi
    tasks_from: verify

- name: include with role vars
  ansible.builtin.include_role:
    name: multi
  vars:
    multi_greeting: passed-in

tasks_from pairs with the entry points in meta/argument_specs.yml from lesson 4: a role with tasks/verify.yml should declare a verify: entry point so its inputs are validated too.

Under the hood

The distinction is where in the pipeline the content is resolved.

Playbook parsing builds a tree of plays, each holding a list of blocks, each holding tasks. import_role, import_tasks, import_playbook and the roles: keyword are handled by the parser: it opens the referenced file, parses it into tasks, and splices those tasks into the tree. By the time the first host is contacted, the tree is complete and immutable. --list-tasks walks that tree, which is why it is both fast and total.

include_role and include_tasks are real tasks with real action plugins. The parser puts one task in the tree. At run time, when the strategy plugin reaches it, the plugin opens the file, parses it, and inserts the resulting tasks into the current play’s queue — for that host, at that moment. This is why a loop works (the plugin runs once per item and inserts a fresh copy) and why templating the filename works (the value exists by then).

It also explains the tag behaviour exactly. Tag selection is applied to the task tree. Tasks that do not exist in the tree cannot be selected, and tasks inserted later are evaluated against the same selection when they arrive — which is why an included role’s inner tasks respond to --tags at all, but only once the include statement itself has been selected and run. Part XXIII lesson 3 works through the failure that follows from that.

What happens if you convert an include_role to an import_role?

Three things change, and two of them are usually improvements.

--list-tasks gains the role’s contents. Good. Your dry run is now complete.

Tags on the statement start applying to every task inside. Usually what you meant, occasionally not: if the role contains a task tagged never, that task now sits inside an import whose tags it inherits, and the interaction is worth checking rather than assuming.

Anything that made the include dynamic stops working. A loop becomes a parse error, which is loud and fine. A templated name: referring to a fact becomes a resolution failure at parse time, before facts exist — also loud. The quiet one is a when: that was gating an expensive load: as an import, the file is loaded regardless and the condition merely skips each task, so you keep the parse cost and any parse-time errors in a file you intended not to touch.

Do the conversion and diff --list-tasks before and after. That diff is the review artefact.

What the parser knows

Why that costs you something

What each form can and cannot do

Choosing

The dynamic form’s own conveniences

Knowledge check