In an Ansible playbook, what is the difference between import_role and include_role, and how does the choice affect tags, loops and when?

## One difference, many consequences Ansible has two families of task inclusion: **static imports** (`import_role`, `import_tasks`, `import_playbook`) and **dynamic includes** (`include_role`, `include_tasks`). The single underlying difference is timing. Imports are resolved when the playbook is parsed, before the first task executes. Includes are resolved when control reaches them, as ordinary tasks. Every behavioural difference below is downstream of that. ## What import_role gives you Because the role's tasks are flattened into the play at parse time, they become indistinguishable from tasks you wrote inline: - `ansible-playbook --list-tasks` shows every task in the role. - A tag placed on the `import_role` task is **inherited** by every task inside the role, so `--tags nginx` selects them. - A `when` on the import is **copied onto each child task**, so it is evaluated once per task, per host, at runtime. This surprises people: the condition is not evaluated once at import time, and if it references a fact, it is re-checked at each task. - Handlers the role defines are available immediately, including to tasks written before the import. The cost is that the import must be fully determined before the play runs. You cannot loop over it, and the role name cannot depend on a runtime variable such as a fact or a registered result. (Variables that are known at parse time - extra vars, inventory vars - do work in the name, but relying on that is fragile enough that most teams avoid it.) ## What include_role gives you An include is one task that happens to run a role, which buys flexibility: - It can carry `loop`, so a single statement applies a role once per item. - Its `when` is evaluated once, on the include itself; false means the entire role is skipped without evaluating anything inside. - The role name can come from a variable resolved at runtime. - Options such as `tasks_from`, `vars_from`, `defaults_from` and `handlers_from` let you enter the role at a non-default file. - `public: true` exposes the role's vars and defaults to the rest of the play afterwards; by default an included role's variables stay scoped to the include. The cost is opacity. Ansible does not know what is inside a dynamic include until it runs it, so: ```bash # Prints the include statement, not the role's tasks ansible-playbook site.yml --list-tasks # Skips the include entirely if the tag exists only INSIDE the role ansible-playbook site.yml --tags certs ``` Tag selection happens before the include is expanded, so a tag written on a task inside the role is invisible to `--tags`. The include must itself be tagged. If you also want that tag on the role's inner tasks, use the `apply` keyword: ```yaml - name: Renew certificates for each site ansible.builtin.include_role: name: certbot apply: tags: [certs] loop: "{{ sites }}" tags: [certs] ``` (The tag on the include itself is still required - `apply` propagates keywords inward, it does not make the include selectable.) ## The `roles:` keyword is a third thing Roles listed under a play's `roles:` header behave like static imports, and they run **before** the play's `tasks:` section. That ordering catches people out: a task written above `roles:` in the file still runs after the roles. Using `import_role`/`include_role` inside `tasks:` puts the role exactly where you wrote it, which is why explicit task-level application has largely displaced the `roles:` header in newer code. ## How to choose Default to `import_role` for the ordinary case of "apply this role here": you keep tag selectivity, `--list-tasks` output stays honest, and there is no runtime resolution to reason about. Reach for `include_role` when you genuinely need runtime behaviour - looping a role over a list, choosing the role by variable, entering at an alternate `tasks_from`, or skipping a large role with one cheap decision instead of tagging hundreds of copied conditionals onto its tasks. ## Failure modes to name in an interview A CI job that runs `--tags migrate` and silently does nothing, because the migration tasks live inside an untagged `include_role`. A `--check` or `--list-tasks` review that looks empty for the same reason. A `when: ansible_facts['os_family'] == 'Debian'` on an `import_role` that produces a wall of skipped tasks in the output rather than one skip, because the condition was copied onto every task. And an attempt to add `loop:` to `import_role`, which is not supported - the fix is to switch to `include_role`.