Lire et écrire du YAML pour Kubernetes

Avec Kubernetes, presque tout s'écrit en YAML : un pod, un déploiement, un service, une règle réseau. Ce format est fait pour être lu par des humains, mais il a quelques pièges qui coûtent des heures quand on ne les connaît pas. Cette leçon vous donne les règles et vous apprend à les repérer.

Pourquoi YAML ?

Kubernetes fonctionne de façon déclarative : vous ne lui dites pas quoi faire étape par étape, vous lui décrivez l'état voulu (« je veux 3 copies de nginx 1.27 »), et il se débrouille pour l'atteindre. Ce « état voulu » est un document : on l'écrit en YAML, on l'envoie avec kubectl apply -f fichier.yaml, et on le range dans Git comme du code.

Règle n° 1 : l'indentation porte le sens

En YAML, ce sont les espaces en début de ligne qui disent qui appartient à qui. Pas d'accolades, pas de points-virgules.

metadata:
  name: web
  labels:
    app: boutique

Ici, name et labels sont dans metadata (2 espaces), et app est dans labels (4 espaces).

• On indente avec des espaces, jamais des tabulations : une tabulation provoque une erreur.
• Le nombre d'espaces est libre (2 est l'usage), mais il doit être le même pour tous les éléments d'un même niveau.

Décaler labels d'un seul espace en arrière suffit à changer complètement le sens du document, ou à le rendre invalide.

Les trois briques

Tout document YAML se construit avec trois choses.

1. Les dictionnaires (des paires clé: valeur). Attention à l'espace après les deux-points, obligatoire :

name: web        # correct
name:web         # incorrect : c'est un seul texte « name:web », pas une clé

2. Les listes, avec un tiret suivi d'un espace :

ports:
  - 80
  - 443

Une liste peut contenir des dictionnaires : c'est le cas des conteneurs d'un pod.

containers:
  - name: web
    image: nginx:1.27-alpine
  - name: journal
    image: busybox:1.37

Chaque tiret ouvre un nouvel élément ; les lignes alignées sous name appartiennent au même élément. Ici, la liste contient deux conteneurs.

3. Les valeurs simples : texte, nombre, booléen.

replicas: 3              # nombre
enabled: true            # booléen
image: nginx:1.27-alpine # texte

Le piège des types

YAML devine le type d'une valeur. La plupart du temps, c'est pratique ; parfois, c'est un piège.

version: 1.10     # devient le NOMBRE 1.1 : le zéro final disparaît
version: "1.10"   # reste le texte « 1.10 »
port: "8080"      # texte, alors que Kubernetes attend souvent un nombre

Règle simple : mettez entre guillemets tout ce qui doit rester du texte mais ressemble à un nombre ou à un booléen (versions, codes postaux, "true", "yes"). Dans Kubernetes, c'est en particulier le cas des valeurs des labels et des variables d'environnement, qui doivent être du texte :

env:
  - name: DEBUG
    value: "true"     # sans guillemets, Kubernetes refuse : il attend du texte

Les textes sur plusieurs lignes

Pour un script ou un fichier de configuration :

script: |
  echo "première ligne"
  echo "deuxième ligne"

Le | garde les retours à la ligne tels quels. (Le > les remplace par des espaces : utile pour un long texte, rarement pour un script.)

Plusieurs objets dans un fichier

Trois tirets --- séparent deux documents. On peut ainsi ranger un Deployment et son Service dans le même fichier :

apiVersion: apps/v1
kind: Deployment
# …
---
apiVersion: v1
kind: Service
# …

Et # commence un commentaire, ignoré par Kubernetes.

L'anatomie d'un objet Kubernetes

Presque tous les objets ont la même forme, en quatre parties :

apiVersion: v1            # quelle version de l'API décrit cet objet
kind: Pod                 # quel type d'objet
metadata:                 # son identité : nom, namespace, labels
  name: web
  labels:
    app: boutique
spec:                     # l'état voulu : ce que vous demandez
  containers:
    - name: web
      image: nginx:1.27-alpine

Une cinquième partie, status, est remplie par Kubernetes lui-même : c'est l'état réel, que vous lisez avec kubectl get … -o yaml. Vous n'écrivez jamais status.

Trouver le bon champ

Personne ne connaît tous les champs par cœur. Deux réflexes que vous utiliserez dès les prochaines leçons :

• kubectl explain pod.spec.containers affiche la documentation d'un champ, directement dans le terminal ;
• kubectl create deployment web --image=nginx --dry-run=client -o yaml génère un squelette correct que vous n'avez plus qu'à modifier.

À retenir

• L'indentation (en espaces) définit la structure.
• Toujours un espace après : et après -.
• Guillemets pour tout texte qui ressemble à un nombre ou à un booléen.
• apiVersion, kind, metadata, spec : vous écrivez l'état voulu, Kubernetes remplit status.

Quand vous êtes prêt, validez la leçon avec le questionnaire : les questions vous demandent de repérer des erreurs et de prévoir le résultat, pas de recopier les exemples.