Validateur YAML — Corriger les erreurs YAML avant de casser votre déploiement

Le déploiement qui m'a appris à valider d'abord

C'était un vendredi après-midi — le pire moment possible pour que cela arrive. Un déploiement Kubernetes était en revue depuis deux jours, et après l'approbation finale, la commande kubectl apply a craché une erreur qui a tout stoppé :

error: error parsing deployment.yaml: error converting YAML to JSON: yaml: line 34: mapping values are not allowed in this context

Ligne 34. Dans un manifest de 200 lignes. Le coupable s'est avéré être ceci :

env:
  - name: DATABASE_URL
    value: postgres://user:password@host:5432/db

Ça semble correct, non ? Faux. Le deux-points dans la valeur — user:password — était partiellement interprété comme de la syntaxe de mapping YAML. La correction était triviale :

env:
  - name: DATABASE_URL
    value: "postgres://user:password@host:5432/db"

Une paire de guillemets. Trente minutes de débogage. La leçon : valider votre YAML avant qu'il touche quoi que ce soit d'important.

---

Pourquoi YAML est vraiment piégeux

YAML a un problème de réputation. Il semble simple — pas de crochets, pas d'accolades, juste des paires clé-valeur indentées. Cette simplicité est réelle, mais elle a un coût caché : les règles de YAML sont étonnamment complexes à raisonner, surtout pour les cas limites.

L'espace blanc est de la syntaxe. Dans la plupart des langages, l'espace blanc est cosmétique. En YAML, le nombre d'espaces avant une clé définit sa position dans l'arbre du document. Deux espaces signifient un niveau d'imbrication ; quatre en signifient deux. Si vous vous trompez, le parser fait soit une erreur, soit crée silencieusement une structure différente de celle que vous souhaitiez. Le cas "crée silencieusement une structure différente" est le dangereux.

Jamais de tabulations. Cela prend les gens sans cesse au dépourvu. Votre éditeur peut insérer des tabulations quand vous appuyez sur Tab, vous pouvez coller du YAML d'un article de blog qui utilisait des tabulations, ou vous pouvez hériter d'une config de quelqu'un avec des paramètres d'éditeur différents. Les parsers YAML rejetteront les tabulations utilisées pour l'indentation avec une erreur found character that cannot start any token.

L'inférence de type est agressive. YAML essaie d'être utile en devinant les types. Cela crée quelques pièges célèbres :

# Ces valeurs ne sont PAS des chaînes en YAML 1.1 (la version utilisée par la plupart des outils)
version: 1.0      # float, pas une chaîne
enabled: yes      # booléen true, pas la chaîne "yes"
id: 08            # octal 8... ou une erreur de parsing
country: NO       # booléen false (le code ISO de la Norvège !)

Si vous avez besoin que ce soient des chaînes, vous devez les mettre entre guillemets. Toujours.

Les chaînes multi-lignes ne sont pas intuitives. YAML a deux styles de scalaires multi-lignes — le bloc littéral (|) et le bloc replié (>). Le littéral préserve les sauts de ligne ; le replié convertit les sauts de ligne uniques en espaces.

---

Les erreurs YAML les plus courantes (avec exemples)

1. Chaînes non entre guillemets contenant des deux-points

# CASSÉ — le deux-points crée un mapping implicite
message: Error: connection refused

# CORRIGÉ
message: "Error: connection refused"

2. Tabulations au lieu d'espaces

# CASSÉ (tabulation avant "name")
server:
	name: prod-01   # caractère de tabulation ici — va générer une erreur

# CORRIGÉ (espaces)
server:
  name: prod-01

3. Indentation inconsistante

# CASSÉ — "port" est indenté de 4 espaces tandis que "host" utilise 2
database:
  host: localhost
    port: 5432    # faux — cela fait de "port" un enfant de "host"

# CORRIGÉ
database:
  host: localhost
  port: 5432

4. Caractères spéciaux non entre guillemets

# CASSÉ — # commence un commentaire, donc "value" est perdu
description: This is important # not a comment here

# En réalité correct — les commentaires en ligne sont du YAML valide
# Mais si vous voulez le # dans la valeur :
description: "This is important # still part of the string"

5. Clés en double

# CASSÉ — le deuxième "host" écrase silencieusement le premier dans la plupart des parsers
database:
  host: localhost
  port: 5432
  host: prod.example.com   # doublon — mauvais

6. Valeurs booléennes et null incorrectes

# Tous ces éléments sont booléens true en YAML 1.1 :
enabled: true
enabled: True
enabled: yes
enabled: on

# Tous ces éléments sont null :
value: ~
value: null
value: Null

# Si vous voulez la chaîne "yes" ou "null", mettez-la entre guillemets :
status: "yes"
type: "null"

7. Erreurs d'ancre/d'alias

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults    # clé de fusion — valide mais déroutant
  timeout: 60      # écrase la valeur de l'ancre

staging:
  <<: *defaults
  timeout: 15

---

Comment utiliser le validateur YAML

Le validateur YAML sur toolboxhubs.com est conçu pour le workflow où vous interceptez les erreurs avant qu'elles n'atteignent votre pipeline.

Étape 1 — Coller votre YAML. Copier l'intégralité du contenu de votre fichier de configuration — docker-compose.yml, .github/workflows/deploy.yml, values.yaml, peu importe ce sur quoi vous travaillez — et le coller dans le panneau d'entrée.

Étape 2 — Exécuter la validation. Le validateur parse votre YAML immédiatement et rapporte la première erreur de syntaxe trouvée, incluant le numéro de ligne. Corrigez-la et relancez.

Étape 3 — Examiner la sortie parsée. Au-delà de la détection des erreurs, le validateur affiche la structure parsée sous forme d'arbre. C'est là que vous interceptez les erreurs logiques — peut-être que votre clé est syntaxiquement au bon endroit mais au mauvais niveau d'imbrication.

Étape 4 — Vérifier les types. Faites attention à ce que les chaînes apparaissent comme des chaînes, les booléens comme des booléens, et les nombres comme des nombres.

Pour convertir entre formats, le convertisseur JSON vers YAML gère les allers-retours, et le formateur JSON est utile quand on travaille avec les deux formats dans le même projet.

---

YAML vs JSON — Quand choisir lequel

Utiliser YAML quand :

• Les humains éditent régulièrement le fichier (configs CI, manifests Kubernetes, playbooks Ansible)
• Les commentaires sont importants — YAML supporte les commentaires #, JSON non
• On veut réduire le bruit visuel dans les structures imbriquées
• La config est principalement statique et non générée par machine

Utiliser JSON quand :

• Le fichier est généré par du code et lu par du code — les humains le touchent rarement
• Des garanties de type strictes sont nécessaires
• On travaille avec une API qui attend du JSON
• On veut l'outillage le plus simple possible

---

YAML dans les outils spécifiques

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
        env:
          NODE_ENV: test
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

La syntaxe d'expression ${{ }} n'est pas de la syntaxe YAML — elle est évaluée par Actions avant le parsing YAML.

Docker Compose

services:
  app:
    image: node:20-alpine
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./src:/app/src:ro
    depends_on:
      db:
        condition: service_healthy

Notez "3000:3000" entre guillemets — le deux-points le rend nécessaire.

Manifests Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:latest
          ports:
            - containerPort: 8080

La double imbrication spec.template.spec piège fréquemment les gens. Le spec interne est la spécification Pod ; l'externe est la spécification Deployment.

Ansible

- hosts: webservers
  vars:
    deploy_path: /var/www/app
  tasks:
    - name: Copy application files
      copy:
        src: "{{ item }}"
        dest: "{{ deploy_path }}/{{ item }}"
      loop:
        - index.html
        - app.js
        - styles.css

La syntaxe de template Jinja2 {{ }} doit être entre guillemets (comme montré avec "{{ item }}") sinon le parser YAML d'Ansible interprétera le { d'ouverture comme un mapping de flux YAML.

---

Conseils pour écrire du YAML sans erreurs

1. Utiliser un linter, pas seulement un validateur. Un validateur vous dit si le YAML est syntaxiquement valide. Un linter comme yamllint impose aussi une indentation cohérente, les espaces de fin de ligne, la longueur des lignes et d'autres règles de style.

2. Configurer correctement l'éditeur. Configurer l'éditeur pour utiliser des espaces (pas des tabulations) pour les fichiers .yml et .yaml, avec une indentation de 2 espaces. L'extension YAML de VS Code (par Red Hat) valide à la volée et valide le schéma des fichiers Kubernetes, GitHub Actions et Docker Compose automatiquement.

3. Mettre les chaînes entre guillemets de façon défensive. Si une valeur de chaîne contient :, #, {, }, [, ], *, & ou !, la mettre entre guillemets. Si elle pourrait être mal interprétée comme booléen ou null, la mettre entre guillemets.

4. Valider avant de pousser. Ajouter la validation YAML à vos hooks pre-commit :

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [-d, relaxed]

5. Utiliser les ancres, mais les documenter. Les ancres réduisent la duplication mais ajoutent une charge cognitive. Ajouter un commentaire expliquant ce que l'ancre contient et où elle est utilisée.

6. Attention au problème de Norvège. En YAML 1.1, la chaîne à deux lettres NO est parsée comme booléen false. Le code pays ISO 3166-1 alpha-2 de la Norvège est NO. Mettre systématiquement entre guillemets les codes pays, les chaînes de statut comme yes/no.

7. Connaître la version YAML de votre parser. PyYAML de Python utilise 1.1 par défaut. gopkg.in/yaml.v3 de Go implémente 1.2. js-yaml de JavaScript est aussi en 1.2 par défaut. Cela importe quand on partage des configs entre toolchains.

---

Conclusion

YAML est le langage de configuration dominant pour les outils d'infrastructure modernes — Kubernetes, GitHub Actions, Docker Compose, Ansible et la plupart des systèmes CI/CD sont construits autour. Cela rend la connaissance de ses modes de défaillance vraiment importante.

Le workflow pratique est simple : coller votre config dans le validateur YAML avant de pousser, surtout pour tout ce qui touche un pipeline de déploiement. Cela prend dix secondes et attrape la classe d'erreurs qui vous enverrait autrement traquer un numéro de ligne cryptique dans un manifest de 200 lignes un vendredi après-midi.

Pour convertir des configs entre formats, JSON vers YAML gère la conversion proprement, et formateur JSON est utile pour valider le côté JSON de l'équation. Prenez l'habitude de valider d'abord — votre futur vous l'appréciera.