YAML pour Ansible : indentation, types, multilines, pièges classiques

YAML est le format obligatoire des playbooks et inventaires Ansible — et c’est aussi la première source de bugs en débutant. L’indentation est sémantique, les booléens sont stricts, les chaînes non quotées sont parfois interprétées comme des nombres ou des dates, et les multilines ont quatre variantes (|, >, |-, >-) qui ne donnent pas le même résultat. Cette page synthétise ce qu’Ansible attend de votre YAML — assez pour éviter 90 % des erreurs de syntaxe et de comportement.

Ansible utilise YAML 1.2 depuis ansible-core 2.12 (même si certaines versions des bibliothèques tierces tolèrent encore du YAML 1.1). La règle saine est de coder strictement YAML 1.2 : booléens explicites (true/false), strings ambiguës toujours quotées, indentation à 2 espaces.

Ce que vous allez apprendre

L’indentation YAML : 2 espaces, pas de tabs, le piège des deux niveaux mélangés ;
Les types de base : string, integer, float, boolean, null, list, dict ;
Les multilines : | (literal), > (folded), |- / >- (strip trailing) ;
Les ancres et alias : & et * pour réutiliser un bloc de configuration ;
Les pièges classiques : yes/no/on/off, octets non quotés, deux-points dans les strings, dates sauvages.

Indentation : 2 espaces, jamais de tab

YAML rejette catégoriquement les tabulations dans l’indentation. Toujours 2 espaces en Ansible (la convention de la communauté) :

- name: Installer nginx
  ansible.builtin.dnf:
    name: nginx        # 4 espaces sous le module
    state: present     # alignement strict avec name

Le piège classique : copier un exemple depuis un site web qui mélange tabulations et espaces. Vérifiez avec cat -A fichier.yml : les tabs apparaissent en ^I, les espaces en · ·.

Ajoutez à votre .editorconfig ou config VSCode :

[*.{yml,yaml}]
indent_style = space
indent_size = 2
end_of_line = lf
trim_trailing_whitespace = true

yamllint détecte les tabulations à votre place avant exécution.

Les types de base

YAML couvre les types primaires sans annotation explicite :

# String (quotes optionnelles si non ambiguë)
nom: "ansible"
nom_simple: ansible
nom_avec_espaces: "ansible-lab@hostname"

# Integer / Float
forks: 10
timeout: 30.5

# Booléen — toujours true/false en YAML 1.2
become: true
gather_facts: false

# Null
secret: ~          # tilde = null
secret_explicite: null

# Liste
hosts:
  - web1.lab
  - web2.lab
  - db1.lab

# Liste compacte (flow style)
hosts: [web1.lab, web2.lab, db1.lab]

# Dictionnaire
ansible_facts:
  ansible_distribution: AlmaLinux
  ansible_distribution_version: "10.1"   # quote forcée

# Dictionnaire compact
user: { name: ansible, sudo: true }

Multilines : 4 variantes à connaître

YAML offre quatre variantes pour écrire des blocs multilignes. Chacune a son usage :

# Literal block (|) : conserve les newlines, garde le \n final
script_literal: |
  #!/bin/bash
  echo "ligne 1"
  echo "ligne 2"

# Folded block (>) : plie les newlines en espaces, garde le \n final
description_pliee: >
  Cette description est sur plusieurs
  lignes mais sera concaténée en une
  seule ligne avec des espaces.

# Literal strip (|-) : conserve les newlines, supprime le \n final
script_strip: |-
  echo "pas de newline à la fin"

# Folded strip (>-) : plie en espaces, supprime le \n final
description_strip: >-
  Une seule ligne sans newline final.

Cas typiques en Ansible :

Situation	Variante
Script shell dans `command:`/`shell:`	**`
Description longue dans `name:` ou `msg:`	`>` (folded)
Contenu inline d’un fichier (`copy: content:`)	**`

Ancres et alias : factoriser un bloc

Les ancres (&id) et alias (*id) permettent de définir un bloc une fois et de le réutiliser :

# Inventaire YAML : factoriser des variables communes
all:
  vars: &common_vars
    ansible_python_interpreter: /usr/bin/python3.12
    ansible_user: ansible

  children:
    webservers:
      vars:
        <<: *common_vars      # << = merge des clés
        nginx_workers: 4

    dbservers:
      vars:
        <<: *common_vars
        db_engine: postgresql

L’opérateur <<: combiné avec *ancre fait un merge dans le mapping courant. Très pratique pour éviter la duplication, mais à utiliser avec parcimonie : un YAML truffé d’ancres devient illisible. La doctrine moderne préfère les group_vars/ dédiés ou les rôles.

Pièges classiques

1. Booléens YAML 1.1 vs 1.2

YAML 1.1 considérait yes, no, on, off comme booléens. YAML 1.2 a supprimé cette tolérance — seuls true et false sont reconnus. Selon la version de la bibliothèque YAML utilisée par votre Ansible, vous pouvez avoir un comportement différent. Toujours préférer true/false :

# ❌ Ambigu, dépend de la version de pyyaml
become: yes

# ✅ Sans ambiguïté
become: true

2. Strings ressemblant à des nombres

Une chaîne non quotée qui peut être interprétée comme un nombre sera interprétée comme un nombre :

# ❌ "01" devient 1 (entier), perte du zéro initial
version: 01

# ✅ Quote pour forcer la string
version: "01"

Cas réel : un IP avec zéros initiaux, un numéro de téléphone, un identifiant qui commence par 0.

3. Strings contenant un deux-points

Le : est un séparateur clé/valeur en YAML. Une string non quotée qui en contient casse le parsing :

# ❌ Erreur "mapping values are not allowed here"
name: Configurer un site: prod

# ✅ Quote
name: "Configurer un site: prod"

C’est l’erreur YAML n°1 chez les débutants Ansible.

4. Dates sauvages

YAML 1.2 reconnaît certaines chaînes comme des dates et les convertit en objet datetime Python :

# ❌ Devient un objet datetime, pas une string
release_date: 2026-04-25

# ✅ Quote pour conserver la string
release_date: "2026-04-25"

Le module Ansible qui consomme cette variable peut ne pas savoir gérer un objet datetime — symptôme typique : 'datetime.date' object has no attribute 'split'.

5. Octets non quotés

Une valeur comme 0644 (permissions Unix) est interprétée selon la version : YAML 1.1 la voit comme un octet (= 420 en décimal), YAML 1.2 la voit comme une string. Pour ne pas dépendre de la version :

# ❌ Comportement variable
mode: 0644

# ✅ Quote toujours les permissions
mode: "0644"

Vérification systématique

Trois outils à intégrer dans votre workflow :

yamllint fichier.yml — détecte les indentations cassées, lignes trop longues, deux-points non quotés ;
ansible-lint fichier.yml — détecte les anti-patterns Ansible (modules dépréciés, tâches sans name:, syntaxe FQCN) ;
ansible-playbook --syntax-check fichier.yml — parse le YAML sans rien exécuter, valide la syntaxe Ansible.

En CI, la combinaison des trois empêche 80 % des erreurs YAML d’atteindre vos managed nodes.

À retenir

Ansible utilise YAML 1.2 : booléens stricts (true/false), pas de yes/no.
2 espaces d’indentation, jamais de tab — cat -A ou yamllint pour vérifier.
4 variantes de multiline : |, >, |-, >- — choisir selon le besoin de newlines.
Quoter systématiquement les strings ambiguës : commençant par 0, contenant :, ressemblant à une date, ou aux permissions Unix (mode: "0644").
Ancres & + alias * factorisent un bloc — utile en inventaire, à éviter en playbook (préférer group_vars/).
En CI : yamllint + ansible-lint + --syntax-check détectent 80 % des problèmes avant exécution.

Prochaines étapes

Structure d'un projet Ansible ansible.cfg, inventory/, group_vars/, host_vars/, roles/, collections/, requirements.yml — le layout standard

Style guide Ansible Conventions de nommage, FQCN, indentation, commentaires — la cohérence sur une équipe

Premier playbook Revoir un playbook complet pour ancrer les conventions YAML dans un cas concret