Consommer un rôle Ansible : roles, import_role, include_role, tasks_from

Ansible offre 3 façons de consommer un rôle dans un playbook : roles: classique (statique, exécuté avant tasks:), import_role (statique, parsé au démarrage du playbook), include_role (dynamique, parsé au runtime, supporte when: et loop:). Cette page explique quand utiliser chacun et démontre tasks_from: pour cibler un fichier spécifique du rôle.

Pressé ? Les 3 façons de consommer un rôle

# 1. roles: classique — exécuté AVANT tasks: (ordre fixe)
- hosts: webservers
  become: true
  roles:
    - common
    - webserver

# 2. import_role — statique, libère l'ordre vis-à-vis de tasks:
- hosts: webservers
  become: true
  tasks:
    - name: Préparation
      ansible.builtin.command: /usr/local/bin/prepare.sh
      changed_when: false

    - name: Importer le rôle (équivalent à roles:)
      ansible.builtin.import_role:
        name: webserver

    - name: Post-configuration
      ansible.builtin.debug:
        msg: "Webserver déployé"

# 3. include_role — dynamique, supporte when: et loop:
- hosts: all
  become: true
  tasks:
    - name: Inclure conditionnellement
      ansible.builtin.include_role:
        name: webserver
      when: ansible_os_family == "RedHat"

    - name: Boucler sur plusieurs apps
      ansible.builtin.include_role:
        name: appdeploy
      loop: "{{ apps }}"
      loop_control:
        loop_var: app

# 4. tasks_from: cibler un fichier spécifique (utile pour rôles modulaires)
- ansible.builtin.import_role:
    name: webserver
    tasks_from: install.yml      # exécute uniquement tasks/install.yml

Sécurité non négociable :

• Préférer roles: ou import_role: par défaut, comportement statique, prévisible, --list-tasks les voit, tags: propagés.
• include_role: SEULEMENT quand vous avez besoin de when: ou loop:, la dynamique a un coût (résolution runtime, debug plus délicat).
• tasks_from: pour les rôles modulaires (un rôle = plusieurs entrypoints), pattern propre pour des rôles complexes (install.yml, configure.yml, enable.yml).
• Variables passées au rôle via vars: au niveau de l'inclusion ont la précédence la plus haute parmi les vars de rôle, pratique pour customiser un rôle sans modifier defaults/.

Ce que vous allez apprendre

• Le pattern roles: classique au top du play.
• import_role : statique, parsé au démarrage.
• include_role : dynamique, supporte when:/loop:.
• tasks_from: pour cibler un fichier autre que main.yml.
• Quand préférer chacun selon le contexte.

Tableau de décision

Besoin	Pattern recommandé
Rôle exécuté toujours au début du play	roles: classique
Rôle exécuté au milieu des tasks (avant/après autres tasks)	import_role
Rôle exécuté conditionnellement (when:)	include_role
Rôle exécuté en boucle sur une liste	include_role + loop:
Cibler tasks/configure.yml au lieu de tasks/main.yml	import_role ou include_role + tasks_from:

Glissez pour voir

1. Pattern roles: classique

- name: Pattern roles classique
  hosts: web1.lab
  become: true

  roles:
    - role: webserver        # ← équivalent à `import_role` au début du play

Comportement :

• Le rôle est exécuté AVANT les tasks: du play.
• Statique : parsé au démarrage du playbook.
• Pas de when: direct au niveau roles: (peut être contourné avec un when: au niveau du rôle).

2. Pattern import_role

- name: Pattern import_role
  hosts: web1.lab
  become: true

  tasks:
    - name: Message avant le rôle
      ansible.builtin.debug:
        msg: "Avant l'import du rôle webserver"

    - name: Importer le rôle webserver
      ansible.builtin.import_role:
        name: webserver

    - name: Message après le rôle
      ansible.builtin.debug:
        msg: "Après l'import du rôle webserver"

Comportement :

• Le rôle s'exécute à l'endroit où import_role: est appelé (au milieu des tasks).
• Statique : parsé au démarrage du playbook (les tâches du rôle sont visibles dans --list-tasks).
• Pas de when: au niveau du import_role:, utiliser roles: ou include_role.

Cas d'usage : intégrer un rôle dans un séquencement précis (pre_tasks → import_role → post_tasks).

3. Pattern include_role

- name: Pattern include_role
  hosts: db1.lab
  become: true

  tasks:
    - name: Inclure le rôle UNIQUEMENT sur RHEL 9+
      ansible.builtin.include_role:
        name: webserver
        tasks_from: main.yml          # ← peut cibler un autre fichier
      vars:
        webserver_listen_port: 9090
      when: ansible_distribution_major_version | int >= 9

Comportement :

• Le rôle est inclus dynamiquement au runtime, au moment où la tâche est atteinte.
• Supporte when: et loop: directement.
• Pas visible dans --list-tasks (parsing au runtime).
• Plus lent que import_role car parsing à chaque exécution.

Cas d'usage :

• Conditionnel sur un fact (ansible_os_family).
• Boucle sur une liste de configs.
• Logique de branchement complexe.

tasks_from:, cibler un fichier non-main

Un rôle peut avoir plusieurs fichiers de tâches :

roles/webserver/tasks/
├── main.yml          ← entrypoint par défaut
├── install.yml
├── configure.yml
└── secure.yml

Pour cibler configure.yml uniquement (sans rejouer install) :

- name: Reconfigurer nginx (sans réinstaller)
  ansible.builtin.import_role:
    name: webserver
    tasks_from: configure.yml

Avantage : un rôle peut exposer plusieurs entrypoints logiques. L'utilisateur du rôle choisit quoi exécuter selon son besoin.

argument_specs avec plusieurs entrypoints

meta/argument_specs.yml peut déclarer plusieurs entrypoints (main:, configure:, secure:). Chaque entrypoint a sa propre validation de variables.

Passer des variables à un rôle

Au niveau du rôle (toutes les méthodes)

roles:
  - role: webserver
    vars:
      webserver_listen_port: 8080
      webserver_worker_processes: 4

- import_role:
    name: webserver
  vars:
    webserver_listen_port: 8080

- include_role:
    name: webserver
  vars:
    webserver_listen_port: 8080

Les vars: au niveau du rôle ont une priorité élevée (équivalent à --extra-vars). Surchargent defaults/main.yml et vars/main.yml des autres niveaux.

private parameter (ansible-core 2.17+)

- include_role:
    name: webserver
    public: true              # ← variables exposées au play parent

Par défaut, les variables d'un rôle sont privées au rôle. Avec public: true, elles fuitent dans le play appelant. À utiliser avec parcimonie, peut polluer le namespace.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/roles/consommer-role/ dans stephrobert/ansible-training.

Le lab fournit un playbook.yml qui démontre les 3 patterns dans un seul fichier (3 plays consécutifs). 6 tests structure validés (roles:, import_role, include_role, conditional when:).

cd ~/Projets/ansible-training/labs/roles/consommer-role/

cat playbook.yml                       # 3 patterns illustrés
pytest -v challenge/tests/             # 6 tests structure

Pièges courants

Symptôme	Cause	Fix
when: ignoré sur roles: ou import_role	Parsing statique avant évaluation	Utiliser include_role (dynamique)
Variable du rôle pas visible après son exécution	Scope par défaut privé	Utiliser public: true (avec parcimonie)
tasks_from: configure.yml plante	Fichier inexistant ou mal nommé	Vérifier roles/<role>/tasks/configure.yml
--list-tasks ne montre pas les tâches du rôle	include_role (dynamique)	Utiliser import_role pour visualisation
Lent au démarrage du playbook	Beaucoup de import_role (parsing initial)	Bascule vers include_role pour les rôles conditionnels

Glissez pour voir

À retenir

• roles: = exécution avant tasks:. Statique. Le plus simple.
• import_role = exécution au milieu des tasks. Statique (parsing initial).
• include_role = exécution au milieu des tasks. Dynamique (parsing runtime). Supporte when:/loop:.
• tasks_from: cible un fichier de tâches autre que main.yml.
• vars: sur le rôle = priorité haute, override les defaults/vars du rôle.

Prochaines étapes

Dépendances entre rôles meta/main.yml dependencies:, chaîner plusieurs rôles automatiquement

ansible-galaxy CLI Commandes essentielles pour installer/gérer des rôles

Installer des rôles Galaxy requirements.yml + ansible-galaxy install

Auditer un rôle existant Avant de consommer un rôle Galaxy, savoir l'évaluer

×

📖 Voir la documentation →