Plays et tasks Ansible : anatomie complète, ordre d'exécution, mots-clés

Un playbook est une liste ordonnée de plays, chaque play ciblant un groupe d’hôtes avec une séquence de tâches précise. Cette page décortique l’anatomie complète d’un play — au-delà du hosts: + tasks: minimal — et explique l’ordre d’exécution exact des sections (pre_tasks → roles → tasks → post_tasks → handlers). Comprendre cet ordre est essentiel pour structurer correctement vos playbooks et éviter les surprises sur les handlers déclenchés trop tôt ou trop tard.

Cette page se concentre sur l’anatomie. Les mots-clés de parallélisme (serial:, strategy:, max_fail_percentage:) ont leur page dédiée — voir Parallélisme et stratégies.

Pressé ? L'ordre d'exécution à mémoriser

- name: Déployer myapp
  hosts: webservers
  become: true                    # élévation pour tout le play
  gather_facts: true              # défaut : récupère ansible_*
  vars:
    app_version: "1.2.3"

  pre_tasks:                      # 1. AVANT roles + tasks
    - name: Précondition OS
      ansible.builtin.assert:
        that: ansible_distribution_major_version | int >= 9

  roles:                          # 2. Roles dans l'ordre déclaré
    - common
    - webserver

  tasks:                          # 3. Tâches custom du play
    - name: Déployer la version applicative
      ansible.builtin.copy:
        src: "files/myapp-{{ app_version }}.tar.gz"
        dest: /opt/myapp/

  post_tasks:                     # 4. APRÈS roles + tasks (validation finale)
    - name: Healthcheck applicatif
      ansible.builtin.uri:
        url: http://localhost:8080/health
        status_code: 200

  handlers:                       # 5. Déclenchés en fin de play par notify:
    - name: Restart myapp
      ansible.builtin.systemd_service:
        name: myapp
        state: restarted

Ordre exact : gather_facts → pre_tasks → roles → tasks → post_tasks → handlers. Les handlers s’exécutent en fin de play (pas immédiatement) — un changement de conf à tasks puis un meta: flush_handlers permet de forcer l’exécution avant la suite. become: true au niveau du play plutôt que par tâche pour éviter la duplication.

Ce que vous allez apprendre

• L’anatomie complète d’un play et ses mots-clés principaux ;
• L’ordre d’exécution strict : gather_facts → pre_tasks → roles → tasks → post_tasks → handlers ;
• Comment enchaîner plusieurs plays dans un même playbook ;
• La différence entre environment: au niveau play, task et bloc ;
• Le pattern meta: flush_handlers pour forcer les handlers entre deux sections.

🧪 Lab d'accompagnement

Cette page est jumelée au lab labs/ecrire-code/plays-et-tasks/ dans stephrobert/ansible-training. Détails et commandes en bas de page : Pratiquer dans le lab.

Anatomie d’un play complet

Voici un play qui utilise la majorité des mots-clés disponibles :

---
- name: Déployer nginx avec rolling update
  hosts: webservers
  become: true
  gather_facts: true

  vars:
    nginx_version: "1.26.1"
    nginx_workers: 4

  vars_files:
    - vars/secrets.yml

  environment:
    PATH: "/usr/local/bin:{{ ansible_env.PATH }}"
    TZ: Europe/Paris

  pre_tasks:
    - name: Drainer le load-balancer
      ansible.builtin.debug:
        msg: "Drainer {{ inventory_hostname }} du LB"

  roles:
    - role: nginx
      vars:
        nginx_port: 80

  tasks:
    - name: Vérifier que nginx répond
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}/health"
        status_code: 200

  post_tasks:
    - name: Réintégrer dans le load-balancer
      ansible.builtin.debug:
        msg: "Réintégrer {{ inventory_hostname }} dans le LB"

  handlers:
    - name: Recharger nginx
      ansible.builtin.systemd:
        name: nginx
        state: reloaded

Chaque mot-clé a un rôle précis. Voyons-les un par un.

Les mots-clés essentiels

name: (obligatoire)

Description humaine du play, affichée dans le PLAY RECAP. Doit décrire l’objectif business, pas la liste des modules.

hosts: (obligatoire)

Pattern d’hôtes ciblé. Exemples : all, webservers, webservers:!web1, web*:&rhce_lab.

become: et become_user:

become: true élève en root via sudo. become_user: postgres exécute en tant qu’utilisateur dédié (utile pour pg_* commands). Peut être mis au niveau du play, du block, ou de la task.

gather_facts: et gather_subset:

gather_facts: true (défaut) lance le module setup au début et expose ansible_facts.*. Mettre false pour gagner quelques secondes si vous savez ne pas utiliser de facts. gather_subset: '!all,network' restreint à un sous-ensemble (gain de perf sur fleets très grandes).

vars: et vars_files:

vars: injecte des variables locales au play. vars_files: charge des fichiers YAML externes (utile pour les secrets vars_files: - vars/secrets.yml chiffrés Vault).

environment:

Injecte des variables d’environnement dans le shell qui exécute les modules. Utile pour http_proxy, PATH, LANG. Peut être posé au niveau play, block, ou task — la valeur la plus locale gagne.

environment:
  HTTP_PROXY: http://proxy.example.com:3128
  LANG: en_US.UTF-8

Les sections : pre_tasks, tasks, post_tasks, handlers, roles

Un play exécute ses sections dans cet ordre strict :

1. gather_facts (si true)
2. pre_tasks            ← tâches AVANT les rôles
3. handlers déclenchés par les pre_tasks
4. roles                ← rôles importés
5. tasks                ← tâches inline
6. handlers déclenchés par les tasks/roles
7. post_tasks           ← tâches APRÈS le reste
8. handlers déclenchés par les post_tasks

Les handlers sont déclenchés à la fin de chaque section qui les a notifiés — pas à la toute fin du play. Conséquence : si vous redémarrez nginx via un handler dans tasks:, le post_tasks: voit déjà le service redémarré.

pre_tasks:

Tâches exécutées avant les rôles. Cas typiques :

• Drainer un load-balancer avant de toucher aux serveurs ;
• Snapshotter une base de données ;
• Vérifier un prérequis externe (DNS, certificat, accès réseau).

tasks:

Le cœur du play. Tâches inline qui s’exécutent après les rôles.

post_tasks:

Tâches exécutées après tout le reste. Cas typiques :

• Réintégrer dans le load-balancer ;
• Notifier Slack/Teams/PagerDuty ;
• Écrire un journal de déploiement dans une base.

roles:

Liste de rôles à importer. Voir la section dédiée Rôles (à venir).

handlers:

Tâches réactives qui ne s’exécutent que si elles sont notifiées par une autre tâche via notify:. Voir la page dédiée Handlers.

Plusieurs plays dans un même playbook

Un playbook YAML peut contenir plusieurs plays — exécutés séquentiellement :

---
- name: Configurer la base de données
  hosts: dbservers
  become: true
  tasks:
    - name: Installer PostgreSQL
      ansible.builtin.dnf:
        name: postgresql-server
        state: present

- name: Déployer l'application
  hosts: webservers
  become: true
  tasks:
    - name: Installer nginx
      ansible.builtin.dnf:
        name: nginx
        state: present

Le second play ne démarre que si le premier réussit sur ses hôtes (sauf si le premier hôte a unreachable=true, le play continue par défaut sur les autres).

Quand séparer en plusieurs plays

Trois cas typiques :

• Cibles différentes : un play pour dbservers, un autre pour webservers.
• Élévation différente : un play sans become pour les vérifications, un avec pour la modification.
• Strategy différente : un play en rolling update, un autre en mode parallèle libre — voir Parallélisme et stratégies.

meta: flush_handlers — forcer les handlers

Par défaut, les handlers déclenchés dans pre_tasks: ou tasks: ne tournent qu’à la fin de leur section. Pour les forcer à s’exécuter immédiatement (par exemple avant un smoke test), utiliser :

tasks:
  - name: Modifier la conf nginx
    ansible.builtin.copy:
      dest: /etc/nginx/conf.d/site.conf
      content: "..."
    notify: Recharger nginx

  - name: Forcer le reload avant la suite
    ansible.builtin.meta: flush_handlers

  - name: Smoke test
    ansible.builtin.uri:
      url: http://localhost
      status_code: 200

Sans meta: flush_handlers, le smoke test tournerait avant le reload — donc sur l’ancienne config. Le pattern est essentiel dès que vous avez besoin de tester l’effet d’un handler dans la même section.

Pièges fréquents

Symptôme	Cause	Fix
Handlers exécutés trop tard	Vous attendiez qu’ils tournent avant post_tasks	Forcer le déclenchement avec meta: flush_handlers à la fin de tasks:
pre_tasks lance des handlers… mais ils tournent à la fin	C’est le comportement standard	Ajouter - meta: flush_handlers après les pre_tasks:
environment: ne s’applique pas	La var est posée sur le play mais surchargée au niveau task	La règle : la var la plus locale gagne. Vérifier les niveaux play/block/task
Plusieurs plays mais le second ne démarre pas	Le premier a marqué tous les hôtes en failed ou unreachable	Vérifier le PLAY RECAP, ajouter ignore_errors: true si pertinent

Glissez pour voir

À retenir

• Un play déclare hosts:, exécute pre_tasks → roles → tasks → post_tasks, avec handlers intercalés à chaque section qui les notifie.
• gather_facts: false + gather_subset: sont les leviers de performance sur grandes fleets.
• environment: injecte des variables d’environnement avec règle “le plus local gagne” (play < block < task).
• meta: flush_handlers force les handlers à tourner immédiatement, sans attendre la fin de la section.
• Pour le parallélisme (serial:, strategy:, max_fail_percentage:), voir Parallélisme et stratégies.

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/ecrire-code/plays-et-tasks/ dans stephrobert/ansible-training. Il contient un README.md guidé, un Makefile (make verify lance les tests), et un challenge final auto-évalué : reproduire le pattern pre_tasks + tasks + post_tasks + handlers sur db1.lab avec httpd.

Premier accès au lab ?

Avant la première utilisation, il faut cloner le dépôt et provisionner les 4 VMs (control-node + web1, web2, db1) — opération à faire une seule fois. Suivez la page Préparer le lab KVM qui couvre git clone, make bootstrap, make provision.

Une fois le lab provisionné :

cd ~/Projets/ansible-training/labs/ecrire-code/plays-et-tasks/

cat README.md           # tuto pas à pas
cat challenge/README.md # consigne du challenge final
pytest -v challenge/tests/   # lancer les tests testinfra

Si les tests passent, vous maîtrisez les concepts couverts dans ce guide. En cas de blocage, docs/troubleshooting.md à la racine du repo couvre les pièges fréquents (rate-limit SSH, clé absente, collection manquante).

Prochaines étapes

Modules built-in Vue d'ensemble des collections ansible.builtin, ansible.posix, community.general

Handlers Le déclenchement des handlers via notify:, listen:, et le pattern flush_handlers

Parallélisme et stratégies forks, serial, throttle, strategy en profondeur

×

📖 Voir la documentation →