Async et poll Ansible : tâches longues, fire-and-forget, async_status

Une tâche Ansible standard bloque la connexion SSH jusqu'à ce qu'elle finisse. Pour une compilation de 30 minutes, un dnf upgrade complet ou un reboot, ce comportement pose deux problèmes : timeout SSH (la connexion lâche) et monopolisation du worker (les autres hôtes attendent). Le mode async détache la tâche du worker, elle tourne en arrière-plan côté managed node, et Ansible la surveille par polling.

Cette page couvre les trois patterns : async + poll > 0 (surveillance synchrone), async + poll: 0 (fire-and-forget), et la combinaison async_status (suivre une tâche async lancée plus tôt).

Ce que vous allez apprendre

• async: : durée maximale d'une tâche en arrière-plan (timeout) ;
• poll: : intervalle de surveillance (en secondes) ; poll: 0 = fire-and-forget ;
• async_status : module qui vérifie l'état d'une tâche async à un moment donné ;
• Le pattern fire-and-forget suivi d'une vérification ultérieure ;
• Les modules incompatibles avec async (raw, meta).

Le problème : timeout SSH sur tâches longues

Imaginez :

- name: Mettre à jour tous les paquets (peut prendre 20 minutes)
  ansible.builtin.dnf:
    name: "*"
    state: latest

Sur un serveur avec 200 paquets à mettre à jour, cette tâche prend 20-30 minutes. SSH coupe la connexion après le ssh_args de default 60s (avec ControlPersist=60s), et le timeout du module fait planter l'opération.

Mode async :

- name: Mettre à jour tous les paquets (async)
  ansible.builtin.dnf:
    name: "*"
    state: latest
  async: 1800              # max 30 min côté managed node
  poll: 30                 # vérifier toutes les 30s

La tâche fork côté managed node, Ansible se déconnecte après le démarrage et revient toutes les 30 secondes pour vérifier l'avancement. La connexion SSH ne reste jamais ouverte plus de quelques secondes.

Les trois patterns

Les trois motifs ci-dessous se distinguent par ce que fait le play pendant que la tâche tourne. Le premier attend sa fin sans tenir la connexion ouverte, le deuxième passe à la suite immédiatement, le troisième revient plus tard chercher le résultat. Dans les trois cas, la tâche tourne détachée sur la machine administrée.

Pattern 1, async + poll > 0 : surveillance synchrone

- name: Build long avec surveillance
  ansible.builtin.command: make -j4
  args:
    chdir: /srv/build
  async: 3600              # max 1 heure
  poll: 60                 # vérifier toutes les 60s
  changed_when: true

Le play attend la fin (mais sans monopoliser SSH). C'est le pattern par défaut quand vous ne savez pas si la tâche peut échouer et que vous voulez bloquer si oui.

Pattern 2, async + poll: 0 : fire-and-forget

- name: Lancer un backup en arrière-plan
  ansible.builtin.command: /usr/local/bin/backup.sh
  async: 7200              # max 2 heures
  poll: 0                  # fire-and-forget
  register: backup_job
  changed_when: true

Avec poll: 0, Ansible lance la tâche, récupère un ID de job, et passe immédiatement à la suite. La tâche tourne indépendamment côté managed node. Cas typique : un backup qui doit s'exécuter sans bloquer le déploiement.

Pattern 3, async_status : suivre une tâche fire-and-forget

Pour récupérer le statut d'une tâche fire-and-forget plus tard :

- name: Lancer le backup
  ansible.builtin.command: /usr/local/bin/backup.sh
  async: 7200
  poll: 0
  register: backup_job
  changed_when: true

# ... d'autres tâches ...

- name: Attendre la fin du backup
  ansible.builtin.async_status:
    jid: "{{ backup_job.ansible_job_id }}"
  register: backup_result
  until: backup_result.finished
  retries: 60
  delay: 60                # 60 retries x 60s = 1h max d'attente

until: backup_result.finished répète la vérification jusqu'à ce que le job soit fini. retries: 60 + delay: 60 autorisent jusqu'à 1 heure d'attente.

Cas pratique, reboot avec retour

Un reboot coupe SSH en plein milieu et ne peut pas être géré comme une tâche normale. Le pattern :

- name: Reboot du système
  ansible.builtin.reboot:
    msg: "Reboot pour appliquer le nouveau kernel"
    reboot_timeout: 300        # attendre max 5 min que SSH revienne
    test_command: uptime

Le module ansible.builtin.reboot gère automatiquement :

1. La déconnexion attendue après le shutdown -r ;
2. L'attente que SSH revienne (reboot_timeout) ;
3. La vérification que le système est opérationnel (test_command).

Pas besoin d'async, reboot est conçu pour ça. Mais le pattern async est utile quand vous voulez lancer un reboot et ne pas attendre (par exemple en mode rolling où chaque hôte reboote indépendamment) :

- name: Reboot fire-and-forget
  ansible.builtin.shell: sleep 5 && shutdown -r now
  async: 60
  poll: 0
  changed_when: true

Limites et incompatibilités

Le mode détaché n'est pas un réglage universel, et trois limites méritent d'être connues avant de l'employer : les modules qui ne savent pas en bénéficier, les deux délais qui encadrent l'attente et se font concurrence, et le comportement en simulation, qui ne réserve aucune surprise.

Modules incompatibles

Certains modules ne peuvent pas tourner en async :

• raw : trop bas niveau (pas de Python pour gérer le job)
• meta : méta-actions internes (flush_handlers)
• Les modules interactifs (rares)

Ansible vous le signale avec un message clair en cas d'usage incorrect.

Timeout vs retries

Paramètre	Rôle
async: 3600	Côté managed node : tue la tâche si pas finie en 1h
until + retries + delay	Côté control node : attend N retries x delay secondes

Glissez pour voir

Les deux limites s'appliquent simultanément, la plus stricte gagne.

Async ne contourne pas le check_mode

Un async en --check se comporte comme une tâche normale en check : il simule sans rien lancer en arrière-plan. Pas de surprise.

Pièges fréquents

Les deux premières lignes sont les plus coûteuses, parce qu'elles laissent le playbook paraître correct : une attente sans fin et un travail détaché dont plus personne ne connaît le sort. Les trois suivantes sont des erreurs d'écriture, un module incompatible, une capture posée sur la mauvaise tâche, et la confusion entre les deux paramètres du mode détaché.

Symptôme	Cause	Fix
async_status retourne finished: 0 indéfiniment	Le job a été tué par le timeout async:	Augmenter async: ou paralléliser le travail
Job fire-and-forget perdu (pas de jid pour le suivre)	register: oublié sur la tâche async	Toujours register: var quand poll: 0
Module async qui plante avec module not supported	Module non compatible (raw, meta)	Bascule en mode synchrone, ou wrap dans un shell:
until: result.finished plante avec 'NoneType' has no attribute	La première vérif async_status n'a pas encore le job	Ajouter register: result à la tâche async_status: (pas la tâche d'origine)
async: 0 (zéro) au lieu de fire-and-forget	async: 0 = synchrone (ignore async) ; pour fire-and-forget c'est poll: 0	Bien mettre async: <timeout> + poll: 0

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• async: <secondes> détache la tâche du worker SSH, Ansible vérifie périodiquement, pas de timeout SSH.
• poll: <secondes> = surveillance synchrone (le play attend la fin, sans bloquer SSH).
• poll: 0 = fire-and-forget : Ansible lance la tâche, récupère un ID via register:, et continue.
• async_status: + until: + retries: + delay: suit une tâche fire-and-forget jusqu'à sa fin.
• ansible.builtin.reboot gère automatiquement le reboot + reconnexion SSH, pas besoin d'async pour ce cas.
• Les modules raw et meta ne supportent pas async.

Mettre en pratique

Un timeout SSH ne se reproduit qu'avec une tâche réellement longue. Le lab vous fait détacher une commande avec async et poll: 0, récupérer son identifiant de job, puis suivre sa fin avec async_status en polling actif. Vous y diagnostiquez aussi un job orphelin, le cas qui piège quand le play se termine avant la tâche détachée.

Lab pratique

Async et poll : tâches longues sans bloquer SSH

$ dsoxlab run ecrire-code-async-poll

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 et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run ecrire-code-async-poll
dsoxlab check ecrire-code-async-poll

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• register et set_fact : l'identifiant d'un job détaché se récupère avec register:, cette page en détaille le contenu.
• Contrôle de flux et gestion d'erreurs : encadrer une tâche détachée pour traiter proprement son échec.
• Boucles avec loop : suivre plusieurs jobs asynchrones d'un coup en bouclant sur les identifiants collectés.

×

📖 Voir la documentation →