Conditions Ansible (when) : opérateurs, multi-conditions, tests Jinja

when: est la directive Ansible qui conditionne l’exécution d’une tâche, d’un block ou d’un rôle sur une expression Jinja2. Si l’expression est vraie, la tâche s’exécute ; sinon elle est marquée skipped dans le PLAY RECAP. Cette page couvre la syntaxe correcte (sans {{ }} ni quotes), les opérateurs de comparaison, les multi-conditions via liste (and implicite), les tests Jinja (is defined, is none, is mapping), et les pièges classiques.

C’est la directive la plus utilisée pour adapter un playbook à différentes distributions, environnements ou variables optionnelles.

Pressé ? Les patterns when essentiels

# Multi-conditions = liste (and implicite, plus lisible que "and")
- name: Installer firewalld sur RHEL 9+
  ansible.builtin.dnf:
    name: firewalld
    state: present
  when:
    - ansible_os_family == "RedHat"
    - ansible_distribution_major_version | int >= 9
  become: true

# OR explicite
- name: Action si débutant OU intermédiaire
  ansible.builtin.debug:
    msg: "OK"
  when: env == "dev" or env == "staging"

# Variable definie + non vide (très fréquent)
- name: Action conditionnelle
  ansible.builtin.copy:
    content: "{{ optional_content }}"
    dest: /tmp/file
  when: optional_content is defined and optional_content | length > 0

# Test sur un fichier (avec stat préalable)
- ansible.builtin.stat:
    path: /etc/myapp.conf
  register: cfg

- name: Backup si fichier existe
  ansible.builtin.copy:
    src: /etc/myapp.conf
    dest: /etc/myapp.conf.bak
    remote_src: true
    mode: "0600"
  when: cfg.stat.exists
  become: true

Sécurité non négociable :

• when: PAS de {{ }} — la directive est déjà une expression Jinja, ajouter les doubles accolades produit un warning Ansible 2.16+.
• Liste sous when: plutôt que and explicite — chaque condition sur une ligne, plus lisible en revue. or doit rester sur une seule ligne.
• is defined AVANT toute autre opération sur une variable optionnelle — sinon Jinja plante avec 'X' is undefined. Pattern : when: var is defined and var > 10.
• int filter sur les versions — ansible_distribution_major_version est une string ("9"), pas un int. Sans | int, > 9 compare des strings (“10” < “9” en string).
• when: sur import_tasks: est appliqué à CHAQUE tâche du fichier — peut être inattendu. Pour conditionner l’import lui-même, utiliser include_tasks: (dynamique).

Ce que vous allez apprendre

• La syntaxe de when: — pas de {{ }}, pas de quotes
• Les opérateurs de comparaison : ==, !=, >, <, >=, <=, in, not in
• Multi-conditions via liste (and implicite) ou expression (and, or, not)
• Les tests Jinja : is defined, is undefined, is none, is mapping, is sequence
• when: sur un block : applique la condition à toutes les tâches du block

🧪 Lab d'accompagnement

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

Prérequis

• Avoir lu Variables — déclaration et Facts et magic vars (les conditions s’appuient sur variables et facts).

La syntaxe correcte

- name: Installer nginx uniquement sur RedHat
  ansible.builtin.dnf:
    name: nginx
  when: ansible_os_family == "RedHat"

3 règles importantes sur when: :

1. Pas de {{ }} : when: accepte directement une expression Jinja, pas une interpolation.

   when: ansible_os_family == "RedHat"        # ✅
   when: "{{ ansible_os_family == 'RedHat' }}" # ❌ erreur, double évaluation

2. Pas de quotes externes sauf si l’expression contient des caractères ambigus :

   when: var == 1                  # ✅
   when: "var == 1"                # ✅ aussi OK
   when: var: var == 1             # ❌ deux-points cassent le YAML

3. Une string non vide est truthy : when: my_var est vrai si my_var est défini ET non vide/zéro/false.

Opérateurs de comparaison

when: ansible_distribution == "AlmaLinux"
when: ansible_distribution != "Ubuntu"
when: ansible_distribution_major_version | int >= 10
when: ansible_memtotal_mb < 2048
when: "'docker' in ansible_facts.packages"
when: env not in ["dev", "staging"]

Le filtre | int ou | float est nécessaire quand le fact est une string (la plupart des ansible_*_version sont des strings).

Multi-conditions via liste

Quand vous avez plusieurs conditions à combiner avec and (cas le plus fréquent), passez une liste :

when:
  - ansible_distribution == "AlmaLinux"
  - ansible_distribution_major_version | int >= 10
  - ansible_memtotal_mb >= 1024

Toutes les conditions doivent être vraies pour que la tâche s’exécute. C’est plus lisible qu’une longue expression and.

Pour or ou des combinaisons mixtes, écrivez l’expression complète sur une ligne :

when: ansible_distribution == "AlmaLinux" or ansible_distribution == "RHEL"
when: (env == "prod" and not maintenance_mode) or force_run | default(false)

Les tests Jinja

Les tests Jinja sont écrits avec is :

Test	Vrai si…
var is defined	La variable existe
var is undefined	Elle n’existe pas
var is none	Elle est None/null
var is mapping	C’est un dict
var is sequence	C’est une liste
var is iterable	Itérable (liste, dict, string)
var is string	C’est une string
var is number	C’est un nombre
var is regex	C’est un objet regex

Glissez pour voir

Cas typique — variable optionnelle :

- name: Activer une feature optionnelle
  ansible.builtin.copy:
    dest: /tmp/feature.txt
    content: "feature ON\n"
  when:
    - enable_feature is defined
    - enable_feature | bool

enable_feature is defined évite l’erreur “undefined variable” ; | bool convertit 'true'/'1'/'yes' en vrai booléen.

when: sur un block

- block:
    - name: Tâche A (RedHat only)
      ansible.builtin.dnf:
        name: foo

    - name: Tâche B (RedHat only)
      ansible.builtin.systemd:
        name: foo
        state: started
  when: ansible_os_family == "RedHat"

Le when: sur le block est propagé à toutes les tâches du block. Plus DRY que de répéter le when: sur chacune.

Cas pratique — 4 conditions ciblées (lab ecrire-code/conditions-when)

Voici l’exemple validé sur le lab 19-ecrire-code-conditions-when :

---
- name: Challenge conditions when
  hosts: db1.lab
  become: true
  gather_facts: true

  tasks:
    - name: cond-redhat
      ansible.builtin.copy:
        dest: /tmp/cond-redhat.txt
        content: "famille=redhat\n"
        mode: "0644"
      when: ansible_os_family == "RedHat"

    - name: cond-alma10
      ansible.builtin.copy:
        dest: /tmp/cond-alma10.txt
        content: "os=AlmaLinux10\n"
        mode: "0644"
      when:
        - ansible_distribution == "AlmaLinux"
        - ansible_distribution_major_version | int >= 10

    - name: cond-feature
      ansible.builtin.copy:
        dest: /tmp/cond-feature.txt
        content: "feature=enabled\n"
        mode: "0644"
      when:
        - enable_feature is defined
        - enable_feature | bool

    - name: cond-debian (NE doit PAS s'exécuter sur AlmaLinux)
      ansible.builtin.copy:
        dest: /tmp/cond-debian.txt
        content: "famille=debian\n"
        mode: "0644"
      when: ansible_os_family == "Debian"

Lancement avec --extra-vars "enable_feature=true" :

PLAY RECAP
db1.lab    : ok=4    changed=3    skipped=1    failed=0

3 fichiers posés (redhat, alma10, feature), 1 task skipped (debian).

when: + loop: ensemble

when: est évalué à chaque itération de la boucle :

- name: Installer uniquement les paquets activés
  ansible.builtin.dnf:
    name: "{{ item.name }}"
    state: present
  loop:
    - { name: nginx, enabled: true }
    - { name: redis, enabled: false }
    - { name: postgresql, enabled: true }
  when: item.enabled

redis est skippé pour cette itération uniquement ; les deux autres sont installés.

Pièges fréquents

Symptôme	Cause	Fix
when: "{{ var == 'x' }}" ne fonctionne pas	Double évaluation Jinja	Retirer {{ }} : when: var == 'x'
Expression compare une string et un int incorrectly	Type mismatch	Filtre `
when: sur une variable absente plante	Variable undefined	Préfixer par var is defined and ...
when: var est faux alors que var: "yes"	'yes' est une string non vide donc truthy, mais YAML 1.2 ne convertit pas	Utiliser `
not item.enabled fait planter quand enabled est absent	Accès à clé inexistante	Utiliser `not item.enabled

Glissez pour voir

À retenir

• when: prend une expression Jinja sans {{ }} ni quotes externes.
• Multi-conditions and : passer une liste, plus lisible qu’une expression longue.
• is defined + | bool sont les deux outils pour gérer les variables optionnelles proprement.
• when: sur un block propage la condition à toutes les tâches enfants.
• Combiné avec loop:, when: est évalué à chaque itération.

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/ecrire-code/conditions-when/ dans stephrobert/ansible-training. Il contient un README.md guidé, un Makefile (make verify lance les tests), et un challenge final auto-évalué : conditionner 4 tâches sur ansible_os_family, version, et une variable optionnelle.

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/conditions-when/

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

Boucles — loop Itérer sur une liste, dict, ou résultat de lookup avec loop: + loop_control:

Block / rescue / always Gestion d'erreur structurée — when: sur block s'applique à toutes les tâches

Facts et magic vars Revoir les facts les plus utiles pour les conditions (ansible_distribution, etc.)

×

📖 Voir la documentation →