Import vs Include Ansible : import_tasks, include_tasks, import_role, include_role, import

Ansible offre 5 directives pour découper un playbook en fichiers réutilisables : import_tasks, include_tasks, import_role, include_role, import_playbook. La distinction import_* (static) vs include_* (dynamic) est fondamentale et testée à l'EX294 : elles n'ont pas le même comportement vis-à-vis des tags, conditions, variables runtime, handlers et --list-tasks.

À la fin de cette page, vous saurez choisir la bonne directive selon le cas d'usage (boucle ? conditionnel ? variables runtime ?), comprendre pourquoi import_tasks ne supporte pas loop:, et orchestrer un déploiement multi-fichiers avec import_playbook.

Ce que vous allez apprendre

Distinguer import_* (static, résolu au start) vs include_* (dynamic, résolu au runtime).
Choisir la bonne directive selon loop:, tags:, when:, variables runtime.
Découper un playbook avec import_tasks pour la lisibilité.
Boucler sur un fichier de tâches avec include_tasks + loop:.
Orchestrer plusieurs plays avec import_playbook.
Comprendre la propagation des tags: et when: selon la directive.

Prérequis

Avoir validé Premier playbook.
Maîtriser les variables et loop:.

Tableau de référence, quelle directive utiliser

Cas d'usage	Directive	Pourquoi
Découper un playbook en fichiers `tasks/*.yml` (sans loop)	`import_tasks`	Static, plus rapide, supporte `--list-tasks`, propage `tags:`/`when:`
Boucler sur un fichier de tâches (`loop: [...]`)	`include_tasks`	Static refuse `loop:` (variable de boucle inexistante au start)
Tagger un bloc entier de tâches incluses	`import_tasks` + `tags:`	Le tag se propage automatiquement aux tâches importées
Appeler un rôle classiquement	`import_role` ou directive `roles:`	Static, équivalent au mot-clé `roles:` du play
Boucler sur un rôle	`include_role` + `loop:`	Static refuse `loop:`
Orchestrer plusieurs plays	`import_playbook` (only)	`include_playbook` n'existe pas
Variable de runtime pas encore connue au start	*`include_`**	Dynamic résout au moment de la tâche

Règle d'or : par défaut, utiliser import_* (plus rapide, plus lisible avec --list-tasks). Basculer sur include_* uniquement si vous avez besoin de loop: ou d'une variable runtime.

`import_tasks` vs `include_tasks`

Static (`import_tasks`), résolu au démarrage

- hosts: db1.lab
  tasks:
    - name: Importer le bloc d'install (parsé au start)
      ansible.builtin.import_tasks: tasks/install.yml
      tags: [setup]                    # ← propagé à TOUTES les tâches du fichier

Comportement :

Ansible lit tasks/install.yml au démarrage du playbook (avant exécution).
--list-tasks voit toutes les tâches importées.
Les tags se propagent à chaque tâche du fichier importé.
Les conditions when: se propagent à chaque tâche.
Pas de loop: possible (la variable item n'existe pas encore au démarrage).

Dynamic (`include_tasks`), résolu au runtime

- name: Inclure des tâches dynamiquement
  hosts: db1.lab
  tasks:
    - name: Inclure dans une boucle (dynamic, résolu au runtime)
      ansible.builtin.include_tasks: tasks/install.yml
      loop: [1, 2, 3]                  # ← supporté par include_tasks
      vars:
        marker_path: "/tmp/marker-{{ item }}.txt"

Comportement :

Ansible résout tasks/install.yml au moment où la tâche est rencontrée.
--list-tasks voit uniquement la directive include_tasks, pas les tâches internes.
Les tags ne se propagent pas automatiquement aux tâches internes (sauf via apply:).
Les conditions when: sont évaluées une seule fois sur le include_tasks lui-même.
loop: supporté, c'est la seule raison principale d'utiliser include_*.

🔍 Observation cruciale : la différence visible se manifeste sur les tags et la boucle. Le piège classique : on tague un include_tasks en pensant que ça suffit, mais les tâches internes ne sont pas filtrées par --tags <nom>. Pour qu'un tag s'applique aux tâches internes du include, utiliser apply: { tags: [...] }.

Le piège des tags avec `include_tasks`

- hosts: db1.lab
  tasks:
    # Cas 1 : import_tasks (tag propagé OK)
    - ansible.builtin.import_tasks: tasks/setup.yml
      tags: [config]

    # Cas 2 : include_tasks SANS apply: (tag NON propagé)
    - ansible.builtin.include_tasks: tasks/setup.yml
      tags: [config]                   # ← tag UNIQUEMENT sur include_tasks lui-même

    # Cas 3 : include_tasks AVEC apply: (tag propagé aux tâches internes)
    - ansible.builtin.include_tasks: tasks/setup.yml
      apply:
        tags: [config]                 # ← propagé à toutes les tâches internes
      tags: [config]

Lancer avec ansible-playbook --tags config :

Cas 1 : toutes les tâches du fichier importé tournent. ✅
Cas 2 : rien ne tourne. Les tâches internes ne sont pas taguées config. ❌
Cas 3 : toutes les tâches du fichier inclus tournent. ✅

🔍 Observation : le apply: est la clé pour propager les tags (et autres attributs) à travers un include_*. Source de bug fréquent en CI quand on filtre par tag.

`import_role` vs `include_role`

- hosts: db1.lab
  tasks:
    - name: Static, équivalent au mot-clé `roles:` du play
      ansible.builtin.import_role:
        name: my_role
      vars:
        role_var: value

    - name: Dynamic, boucler sur un rôle (impossible avec import)
      ansible.builtin.include_role:
        name: my_role
      loop: [1, 2, 3]
      vars:
        role_iter: "{{ item }}"

🔍 Observation : include_role permet de boucler sur un rôle ou d'appliquer un rôle conditionnellement au runtime. Usage rare mais puissant. Pour 95 % des cas, utiliser import_role ou directement la directive roles: du play.

`import_playbook`, orchestrer plusieurs plays

---
# site.yml : orchestrateur
- name: Installer la base de données
  ansible.builtin.import_playbook: playbooks/install_db.yml
- name: Installer les serveurs web
  ansible.builtin.import_playbook: playbooks/install_web.yml
- name: Configurer l'application
  ansible.builtin.import_playbook: playbooks/configure_app.yml

🔍 Observation : import_playbook s'utilise uniquement au niveau plays (pas dans tasks:). include_playbook n'existe pas. Pattern standard pour découper un gros déploiement en sous-playbooks réutilisables, chacun avec son propre hosts:.

Pièges classiques

import_tasks + loop: → erreur de parsing au démarrage. Solution : include_tasks.
Tag sur include_tasks sans apply: → tag non propagé aux tâches internes. Solution : ajouter apply: { tags: [...] }.
include_playbook n'existe pas. Pour orchestrer des plays : import_playbook uniquement.
--list-tasks ne voit pas les tâches dans un include_*. Pour audit complet : utiliser import_* partout où possible.
FQCN obligatoire en 2026 : ansible.builtin.import_tasks, pas juste import_tasks (règle fqcn-builtins).

À retenir

import_* = static, parsé au start. Plus rapide. Tags/when propagés.
include_* = dynamic, parsé au runtime. Supporte loop:. Tags/when non propagés (sauf apply:).
import_playbook existe, include_playbook n'existe pas.
Boucle sur tâches/rôles → include_* obligatoire.
Default : utiliser import_*. Basculer sur include_* uniquement si boucle ou variable runtime.
apply: sur include_tasks propage tags/become/when aux tâches internes.

Mettre en pratique

La différence entre statique et dynamique ne se voit qu'à l'exécution, sur le comportement des tags. Le lab vous fait charger le même fichier de tâches avec import_tasks puis avec include_tasks, boucler sur le second, et comparer ce que --tags et when: déclenchent dans chaque cas. Le contrôle regarde les fichiers posés, donc les tâches réellement jouées, pas la syntaxe écrite.

Import vs include : statique ou dynamique

$ dsoxlab run ecrire-code-import-include

Environnement : VM·Durée : ~45 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI dsoxlab, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
git clone https://github.com/stephrobert/ansible-training.git
cd ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run ecrire-code-import-include
dsoxlab check ecrire-code-import-include

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress.

Pour aller plus loin

Précédence des variables : quelle valeur gagne quand un fichier importé et un group_vars définissent la même variable.
register et set_fact : les variables créées au runtime, le cas qui impose include_* plutôt que import_*.
Boucles avec loop : la mécanique de loop:, seule compatible avec include_tasks.

Import vs Include Ansible : import_tasks, include_tasks, import_role, include_role, import_playbook

Ce que vous allez apprendre

Prérequis

Tableau de référence, quelle directive utiliser

import_tasks vs include_tasks

Static (import_tasks), résolu au démarrage

Dynamic (include_tasks), résolu au runtime

Le piège des tags avec include_tasks

import_role vs include_role

import_playbook, orchestrer plusieurs plays