Erreurs de syntaxe YAML : l'indentation, votre meilleur ennemi

L'indentation YAML : la clé de voûte (et le piège) des playbooks Ansible

YAML (YAML Ain't Markup Language) est le langage utilisé pour écrire les playbooks Ansible. Sa popularité vient de sa lisibilité, qui le rend plus accessible que des formats comme JSON ou XML pour définir des structures de données complexes. Cependant, cette lisibilité repose sur une règle fondamentale et parfois source de nombreuses erreurs : l'indentation. Contrairement à d'autres langages où l'indentation est une question de style, en YAML, elle définit la structure hiérarchique des données. Une mauvaise indentation est l'une des causes les plus fréquentes d'échec lors de l'analyse (parsing) d'un playbook.

Comprendre comment YAML utilise les espaces (et non les tabulations !) pour indiquer les niveaux d'imbrication est absolument crucial. Un décalage d'un seul espace peut complètement changer la signification de votre playbook ou le rendre invalide. Cette section se concentre sur l'identification, la compréhension et la prévention des erreurs de syntaxe YAML liées à l'indentation et à d'autres aspects structuraux.

Nous allons explorer les principes de base de l'indentation en YAML, montrer des exemples concrets d'erreurs courantes et comment les messages d'erreur d'Ansible peuvent (parfois) vous mettre sur la piste. L'objectif est de vous armer des connaissances nécessaires pour que l'indentation devienne votre alliée, et non plus votre ennemie.

Principes fondamentaux de l'indentation et de la structure YAML

En YAML, la hiérarchie est définie par le nombre d'espaces en début de ligne. La règle d'or est la cohérence : au sein d'un même bloc ou d'une même liste, tous les éléments de même niveau doivent avoir exactement la même indentation. Il n'y a pas de nombre d'espaces strict imposé par YAML lui-même (bien que deux espaces soient une convention très répandue et recommandée), mais une fois que vous avez choisi un niveau d'indentation pour un bloc, vous devez vous y tenir.

Les listes (séquences) en YAML sont indiquées par un tiret suivi d'un espace (- ). Chaque élément d'une liste doit commencer au même niveau d'indentation :

# Liste correcte
- pomme
- banane
- orange

# Erreur : indentation incohérente
- pomme
  - banane # 'banane' est interprété comme un sous-élément de 'pomme'
- orange

Les dictionnaires (mappings ou objets) sont des ensembles de paires clé-valeur. La clé et la valeur sont séparées par deux-points suivis d'un espace (key: value). Les éléments imbriqués d'un dictionnaire sont indentés par rapport à leur clé parente :

# Dictionnaire correct
utilisateur:
  nom: Dupont
  age: 30

# Erreur : 'age' n'est pas au même niveau que 'nom'
utilisateur:
  nom: Dupont
 age: 30 # Erreur de parsing probable

Une erreur très fréquente est l'utilisation de tabulations au lieu d'espaces. La plupart des parseurs YAML, y compris celui utilisé par Ansible, interdisent ou interprètent mal les tabulations. Configurez toujours votre éditeur de texte pour qu'il insère des espaces lorsque vous appuyez sur la touche Tab. La plupart des éditeurs modernes permettent de visualiser les caractères invisibles (espaces, tabulations), ce qui peut aider à débusquer ce type d'erreur.

Identifier les erreurs de syntaxe YAML dans Ansible

Lorsqu'Ansible rencontre une erreur de syntaxe dans votre fichier YAML, il arrête généralement l'exécution et affiche un message d'erreur. Ces messages peuvent parfois sembler obscurs, mais ils contiennent souvent des indices précieux. Par exemple, vous pourriez voir :

ERROR! Syntax Error while loading YAML.
  mapping values are not allowed in this context

The error appears to be in '/chemin/vers/votre/playbook.yml': line X, column Y

Un autre message courant pourrait être lié à une mauvaise indentation d'un élément de liste :

ERROR! We were unable to read either as JSON nor YAML, these are common reasons for this to happen:
  - Expecting property name enclosed in double quotes.
  - Verify if variable names are passed in quotes.
  - Ellipses (...) can be only used at the end of a YAML document.
  - YAML list items should start with a dash followed by a space (-" ").

The offending line appears to be:

- name: Ma tâche avec une erreur
    debug: msg="Bonjour"
    ^ ici

Pour diagnostiquer, la première étape est de se rendre à la ligne (et colonne, si indiquée) mentionnée dans le message d'erreur. Examinez attentivement l'indentation de cette ligne et des lignes environnantes. Comparez-la avec des exemples de playbooks valides. Souvent, le problème se situe à la ligne indiquée ou juste avant.

Utiliser la commande ansible-playbook --syntax-check mon_playbook.yml est une excellente pratique avant toute exécution. Elle ne fait qu'analyser la syntaxe de votre playbook sans tenter de l'exécuter, vous donnant un retour rapide sur les erreurs de parsing YAML.

L'utilisation d'un éditeur de texte avec une extension de "linting" YAML (comme l'extension "YAML" par Red Hat pour VS Code) est la meilleure défense préventive. Ces outils analysent votre code YAML pendant que vous l'écrivez et soulignent les erreurs de syntaxe, y compris les problèmes d'indentation, bien avant que vous ne tentiez d'exécuter le playbook. Ils peuvent également souvent auto-formater le code pour respecter une indentation cohérente, réduisant considérablement le risque d'erreurs.

Cas courants d'erreurs d'indentation et solutions

# Incorrect
tasks:
  - name: Installer nginx
    apt:
      name: nginx
      state: present
    - name: Démarrer nginx # Erreur: ce tiret est trop indenté
      service:
        name: nginx
        state: started

# Correct
tasks:
  - name: Installer nginx
    apt:
      name: nginx
      state: present
  - name: Démarrer nginx
    service:
      name: nginx
      state: started

# Incorrect
- name: Copier un fichier
  copy:
  src: mon_fichier.txt # Erreur: src et dest pas assez indentés
  dest: /tmp/mon_fichier.txt

# Correct
- name: Copier un fichier
  copy:
    src: mon_fichier.txt
    dest: /tmp/mon_fichier.txt

# Incorrect
vars:
  package_name nginx # Manque ':' après package_name

# Correct
vars:
  package_name: nginx