Tout ce que vous créez dans Kubernetes est un objet décrit dans un manifeste, un fichier YAML qui dit ce que vous voulez. Ce guide couvre juste assez de YAML pour en lire un, explique la structure commune à tous les manifestes et décrit pas à pas l’exécution d’un Pod à partir d’un fichier. Il suppose que vous disposez d’un cluster fonctionnel (voir le guide précédent).

Le YAML en cinq minutes

Le YAML repose sur deux briques à reconnaître.

Une map est un ensemble de paires clé: valeur. L’indentation indique l’imbrication, et tout ce qui est indenté sous une clé lui appartient. Une liste est une série d’éléments, chacun commençant par un tiret :

app:
  name: shop
  enabled: true
  labels:
    tier: frontend
  ports:
    - 80
    - 443

Ici, app est une map avec les clés name, enabled, labels et ports. labels est elle-même une map, et ports est une liste de deux nombres. Utilisez des espaces, jamais de tabulations. Une mauvaise indentation est la cause la plus courante d’un manifeste qui ne s’applique pas, et elle change silencieusement ce qui appartient à quoi. Plusieurs objets peuvent partager un même fichier s’ils sont séparés par une ligne contenant ---.

Anatomie d’un manifeste

Chaque objet Kubernetes a les mêmes champs de premier niveau :

• apiVersion indique quelle version de l’API définit ce type d’objet.
• kind est le type d’objet, comme Pod ou Deployment. Il est sensible à la casse.
• metadata identifie l’objet : son name, éventuellement un namespace, ainsi que des labels et des annotations.
• spec est l’état souhaité, et son contenu dépend du type.

Kubernetes ajoute une quatrième section, status, qui décrit l’état réel. Vous ne l’écrivez pas. Voici un Pod minimal :

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

containers est une liste : un Pod pourrait donc exécuter plusieurs conteneurs, chacun commençant par son propre tiret. Le champ image est celui à vérifier deux fois. Une faute de frappe signifie que Kubernetes ne peut pas la télécharger et que le Pod restera dans un état d’erreur.

N’écrivez pas les manifestes de zéro

Copiez un exemple fonctionnel depuis la documentation Kubernetes ou laissez kubectl en générer un :

kubectl run web --image=nginx:1.25 --port=80 --dry-run=client -o yaml > pod.yaml

--dry-run=client construit l’objet localement sans le créer, et -o yaml l’affiche en YAML. Cela vous donne un point de départ valide à modifier.

Choisir la bonne apiVersion

Différents types vivent dans différents groupes et versions d’API. Les Pods sont en v1, les Deployments en apps/v1, les Ingresses en networking.k8s.io/v1. Si vous choisissez la mauvaise, ou utilisez une version qu’un cluster plus récent a supprimée, vous obtenez une erreur du type no matches for kind "X" in version "Y". Pour trouver la bonne valeur :

kubectl api-resources | grep -i deployment
kubectl explain deployment | head

La première commande montre le groupe de chaque type, et la seconde affiche sa VERSION. Cela compte surtout lors de la mise à niveau d’un cluster, car d’anciens manifestes peuvent cesser de fonctionner quand une version est supprimée. Le guide de dépréciation de Kubernetes liste ce qui a changé à chaque release.

Créer, inspecter et supprimer

kubectl apply -f pod.yaml
kubectl get pods
kubectl describe pod web
kubectl delete -f pod.yaml

Dans kubectl get pods, la colonne READY indique combien de conteneurs du Pod sont prêts (1/1 signifie sain), STATUS montre sa phase, et RESTARTS compte les redémarrages de conteneurs. Un nombre qui ne cesse de grimper signifie que quelque chose tue sans arrêt le conteneur. describe affiche tous les détails du Pod, avec les événements récents en bas, ce qui est le premier endroit où regarder quand quelque chose ne va pas.

apply est déclaratif : il crée l’objet s’il n’existe pas et le met à jour s’il existe, vous pouvez donc modifier le fichier et réappliquer. kubectl create -f échoue si l’objet existe déjà.

Impératif ou déclaratif

Des commandes comme kubectl run et kubectl create sont impératives : vous dites à Kubernetes de faire quelque chose maintenant. Elles sont rapides pour les expériences et pour les examens de certification. Les manifestes appliqués avec kubectl apply -f sont déclaratifs, et c’est ce qu’il vous faut pour tout usage réel, car les fichiers peuvent vivre dans Git, être relus et être réappliqués. Les guides Argo CD de cette série montrent comment pousser cette idée jusqu’au bout.