Conteneurs d'initialisation Kubernetes : erreurs de configuration et comment les éviter

Introduction

Les conteneurs d'initialisation Kubernetes sont un mécanisme puissant pour préparer un pod applicatif avant le démarrage des conteneurs principaux. Ils s'exécutent jusqu'à leur terme avant le lancement des conteneurs d'application, ce qui les rend idéaux pour des tâches comme l'attente de dépendances, la configuration des permissions de fichiers ou l'exécution de migrations de bases de données. Cependant, il est facile de mal configurer un conteneur d'initialisation, et les erreurs peuvent conduire à des pods bloqués dans les états Init:Error, Init:CrashLoopBackOff ou à des changements de comportement silencieux qui ne se manifestent que plus tard.

Cet article passe en revue les erreurs de configuration courantes avec des exemples pratiques, en montrant comment les diagnostiquer, les corriger et les prévenir. Vous apprendrez à valider le comportement des conteneurs d'initialisation, à revenir en arrière en toute sécurité après un mauvais changement et à résoudre les échecs à l'aide de commandes kubectl concrètes et d'extraits de manifestes. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter les étapes de récupération avant qu'un incident ne vous y oblige.

Nous supposerons que vous disposez d'un cluster Kubernetes fonctionnel (version 1.20 ou ultérieure pour les fonctionnalités stables des conteneurs d'initialisation, mais les exemples fonctionnent sur la plupart des versions modernes), de kubectl configuré et d'une familiarité de base avec les pods et les déploiements. Tous les exemples utilisent un espace de noms de démonstration appelé init-demo pour rester isolés.

Inventaire de la version et de l'environnement

Avant de modifier toute configuration de conteneur d'initialisation, vous devez savoir exactement ce que vous exécutez. Rassemblez la version du serveur Kubernetes, les ressources d'API impliquées et l'état actuel de vos pods. Cette section couvre les observations en lecture seule qui éclairent toutes les étapes ultérieures.

Vérifier la version du cluster et le support de l'API

Les conteneurs d'initialisation sont stables depuis Kubernetes 1.6, mais certains champs comme restartPolicy: Always pour les conteneurs d'initialisation de type side-car (alpha en 1.28, derrière une porte de fonctionnalité) peuvent ne pas être disponibles dans votre distribution. Confirmez votre version de serveur :

kubectl version --short

La sortie attendue montre à la fois les versions client et serveur, par exemple :

Client Version: v1.28.2
Server Version: v1.27.4

Si votre version de serveur est antérieure à 1.20, soyez prudent avec les fonctionnalités plus récentes des conteneurs d'initialisation. Documentez la version dans votre runbook ; cela compte lors du dépannage.

Inventorier l'état actuel des pods

Supposons que vous ayez un déploiement avec un conteneur d'initialisation qui copie un fichier de configuration dans un volume partagé. Obtenez les pods actuels avec une sortie détaillée :

kubectl get pods -n init-demo -o wide

Exemple de sortie :

NAME                           READY   STATUS     RESTARTS   AGE   IP            NODE
webapp-7f4c8d6b9c-5g2kx        0/1     Init:0/1   0          12s   10.244.1.8    worker-1
webapp-7f4c8d6b9c-8mzpl        0/1     Init:0/1   0          12s   10.244.1.9    worker-1

La colonne STATUS affiche Init:0/1, ce qui signifie que le pod possède un conteneur d'initialisation et qu'il n'est pas encore terminé. C'est normal pendant le démarrage, mais si cela persiste, quelque chose ne va pas.

Capturer les événements et décrire le pod

Utilisez kubectl describe pour voir les statuts des conteneurs d'initialisation et les événements :

kubectl describe pod webapp-7f4c8d6b9c-5g2kx -n init-demo

Concentrez-vous sur la section Init Containers et sur les Events en bas. Un conteneur d'initialisation sain qui s'est terminé affichera :

Init Containers:
  init-config:
    Container ID:  containerd://abcd1234...
    Image:         busybox:1.36
    State:          Terminated
      Reason:       Completed
      Exit Code:    0

Si le conteneur d'initialisation échoue, vous verrez State: Waiting avec Reason: CrashLoopBackOff ou Error, et des événements comme :

Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  30s   default-scheduler  Successfully assigned init-demo/webapp-7f4c8d6b9c-5g2kx to worker-1
  Warning  Failed     29s   kubelet            Error: Init container init-config failed: exit code 1

Collectez toujours ces informations avant de procéder à des modifications. Elles vous indiquent si le problème vient du conteneur d'initialisation lui-même ou de l'ordonnancement ou de l'environnement du pod.

Garder le test minimal

Pour tout changement de configuration, commencez par un manifeste minimal dans un espace de noms dédié, pas dans votre déploiement de production. Par exemple, utilisez un pod simple comme celui-ci :

apiVersion: v1
kind: Pod
metadata:
  name: init-test
  namespace: init-demo
spec:
  initContainers:
  - name: init-echo
    image: busybox:1.36
    command: ['sh', '-c', 'echo "init done" && sleep 2']
  containers:
  - name: main
    image: nginx:1.25

Appliquez-le et observez la transition d'état :

kubectl apply -f init-test.yaml
kubectl get pod init-test -n init-demo --watch

La sortie de surveillance devrait afficher Init:0/1, puis PodInitializing, puis Running. Si elle passe à Error ou CrashLoopBackOff, vous avez un signal rapide pour enquêter.

Chemin de configuration sûr

Maintenant que vous comprenez l'environnement actuel, suivez un chemin sûr pour modifier la configuration du conteneur d'initialisation. Le principe : observer, changer une seule chose, vérifier et être prêt à revenir en arrière.

Identifier l'erreur exacte

Les erreurs de configuration courantes des conteneurs d'initialisation incluent :

• Commande ou arguments incorrects : Le conteneur d'initialisation se termine avec un code non nul parce que la commande est incorrecte.
• Montages de volume manquants ou incorrects : Le conteneur d'initialisation écrit dans un chemin qui n'est pas partagé avec le conteneur principal, donc les données sont perdues.
• Échecs de tirage d'image : Mauvaise étiquette d'image ou informations d'identification de registre manquantes.
• Limites de ressources trop basses : Le conteneur d'initialisation est tué par OOM avant de se terminer.
• Méconnaissance de la politique de redémarrage : Les conteneurs d'initialisation redémarrent toujours jusqu'à ce qu'ils réussissent (sauf si vous utilisez restartPolicy: Never sur le pod, ce qui est rare). Un conteneur d'initialisation défaillant avec une mauvaise commande provoquera des redémarrages sans fin.

Illustrons avec une erreur concrète : un conteneur d'initialisation qui attend qu'une base de données soit prête en utilisant une commande qui ne réussit jamais parce qu'il utilise le mauvais nom de service.

initContainers:
- name: wait-for-db
  image: busybox:1.36
  command: ['sh', '-c', 'until nc -z database 5432; do echo waiting; sleep 2; done']

Si le service s'appelle en réalité postgres-svc, le conteneur d'initialisation bouclera indéfiniment (ou jusqu'à ce qu'il atteigne le activeDeadlineSeconds du pod, s'il est défini). Le pod restera Init:0/1 indéfiniment.

Appliquer le plus petit changement justifié

Plutôt que de modifier plusieurs champs à la fois, corrigez une seule chose. Pour l'exemple ci-dessus, changez le nom d'hôte pour le nom de service correct :

initContainers:
- name: wait-for-db
  image: busybox:1.36
  command: ['sh', '-c', 'until nc -z postgres-svc 5432; do echo waiting; sleep 2; done']

Appliquez avec kubectl apply et surveillez le pod :

kubectl apply -f deployment.yaml
kubectl get pods -n init-demo --watch

Progression attendue : Init:0/1 (en attente de la base de données), puis une fois la base de données joignable, PodInitializing, puis Running pour le conteneur principal.

Utiliser des espaces réservés plutôt que des secrets

Lorsque les conteneurs d'initialisation ont besoin de données sensibles (comme des mots de passe de base de données), ne les codez jamais en dur. Utilisez les Secrets Kubernetes et des variables d'environnement ou des montages de volume. Par exemple, pour transmettre un mot de passe à un conteneur d'initialisation qui initialise un schéma :

apiVersion: v1
kind: Secret
metadata:
  name: db-init-secret
  namespace: init-demo
type: Opaque
stringData:
  DB_PASS: "s3cr3t"   # Dans la vraie vie, utilisez un coffre-fort ou un opérateur de secrets externe
---
apiVersion: v1
kind: Pod
metadata:
  name: db-migrate
  namespace: init-demo
spec:
  initContainers:
  - name: run-migration
    image: postgres:16
    env:
    - name: PGPASSWORD
      valueFrom:
        secretKeyRef:
          name: db-init-secret
          key: DB_PASS
    command: ['sh', '-c', 'psql -h postgres-svc -U app -d appdb -f /migrations/001.sql']
  containers:
  - name: main
    image: nginx:1.25

Appliquez et vérifiez que le secret est utilisé et non affiché dans les journaux. Évitez d'utiliser kubectl logs sur les conteneurs d'initialisation en production s'ils risquent d'exposer des valeurs secrètes ; utilisez kubectl logs <pod> -c <init-container> avec prudence.

Stratégie de retour en arrière

Si le changement casse quelque chose, vous avez besoin d'un moyen rapide de revenir en arrière. Avec les déploiements, vous pouvez utiliser l'historique des versions et l'annulation :

kubectl rollout history deployment webapp -n init-demo
kubectl rollout undo deployment webapp -n init-demo

Pour les pods bruts, vous devrez réappliquer un manifeste connu et bon. Gardez une sauvegarde du YAML précédent soit dans le contrôle de version, soit dans un fichier :

kubectl get pod webapp -n init-demo -o yaml > webapp-backup.yaml   # avant le changement
# si le changement échoue :
kubectl delete pod webapp -n init-demo
kubectl apply -f webapp-backup.yaml

Documentez cette procédure de retour en arrière dans votre runbook avant de faire des changements, pas après.

Vérification et diagnostic

Après avoir appliqué un changement de configuration, vérifiez que le conteneur d'initialisation se comporte comme prévu et que le conteneur principal démarre correctement. Cette section donne des commandes exactes et des sorties attendues pour différents scénarios.

Vérifier les journaux du conteneur d'initialisation

Les journaux du conteneur d'initialisation sont souvent le premier endroit à regarder. Utilisez -c pour spécifier le nom du conteneur d'initialisation :

kubectl logs webapp-7f4c8d6b9c-5g2kx -c init-config -n init-demo

Pour un conteneur d'initialisation réussi qui copie des fichiers, vous pourriez ne voir aucune sortie si la commande est silencieuse. Pour vérifier, utilisez une commande qui affiche un message de fin clair, comme :

command: ['sh', '-c', 'cp /config/* /data/ && echo "config copied successfully"']

Alors kubectl logs devrait afficher :

config copied successfully

Si le conteneur d'initialisation est en boucle de crash, utilisez --previous pour voir les journaux de la dernière tentative échouée :

kubectl logs webapp-7f4c8d6b9c-5g2kx -c init-config -n init-demo --previous

Exemple de journal d'échec :

cp: can't create '/data/config.txt': No such file or directory

Cela vous indique que le répertoire /data n'existe pas dans le système de fichiers du conteneur d'initialisation, probablement parce que le montage de volume est incorrect.

Décrire le pod pour le statut du conteneur d'initialisation

kubectl describe montre l'état de chaque conteneur d'initialisation. Pour l'échec ci-dessus, vous verriez :

Init Containers:
  init-config:
    State:          Terminated
      Reason:       Error
      Exit Code:    1
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
    Ready:          False
    Restart Count:  4

L'augmentation du Restart Count indique une boucle de crash. Vérifiez les événements pour plus de contexte.

Valider la préparation du conteneur principal

Une fois le conteneur d'initialisation terminé, assurez-vous que le conteneur principal devient prêt. Utilisez kubectl get pods pour voir la colonne READY passer de 0/1 à 1/1. Pour les déploiements, vérifiez le statut de déploiement :

kubectl rollout status deployment webapp -n init-demo

Sortie attendue :

deployment "webapp" successfully rolled out

Si cela reste bloqué, le conteneur principal peut échouer à sa sonde de préparation après le succès du conteneur d'initialisation. Dans ce cas, le conteneur d'initialisation n'est pas le problème, mais ses effets secondaires pourraient l'être. Par exemple, si le conteneur d'initialisation définit incorrectement les permissions de fichiers, l'application principale pourrait ne pas réussir à lire un fichier.

Tester la connectivité ou les données

Après que le pod est en cours d'exécution, vérifiez que le travail du conteneur d'initialisation a eu l'effet escompté. Par exemple, si le conteneur d'initialisation a rempli un volume partagé avec un fichier de configuration, exécutez une commande dans le conteneur principal et vérifiez :

kubectl exec -it webapp-7f4c8d6b9c-5g2kx -n init-demo -- cat /etc/app/config.yaml

La sortie attendue montre le contenu de configuration que vous attendez. S'il est manquant ou incorrect, examinez les montages de volume entre les conteneurs d'initialisation et principaux. Ils doivent utiliser les mêmes name et mountPath.

Modes de défaillance et récupération

Même avec une planification minutieuse, les conteneurs d'initialisation peuvent échouer. Cette section couvre les scénarios de défaillance courants, comment les diagnostiquer rapidement et comment récupérer avec un temps d'arrêt minimal.

Mode de défaillance 1 : Code de sortie non nul du conteneur d'initialisation

Symptôme : Pod bloqué dans Init:Error ou Init:CrashLoopBackOff.

Diagnostic :

kubectl describe pod <pod-name> -n init-demo
kubectl logs <pod-name> -c <init-container-name> --previous

Exemple : Un conteneur d'initialisation qui exécute un script de migration de base de données et le script échoue en raison d'une colonne en double. Les journaux montrent :

psql:/migrations/002.sql:3: ERROR: column "email" of relation "users" already exists

Récupération : Corrigez le script de migration (par exemple, rendez-le idempotent) et mettez à jour la configmap ou l'image qui contient le script. Si l'image du conteneur d'initialisation est figée, construisez une nouvelle image et mettez à jour le déploiement. Ensuite, supprimez le pod bloqué pour redémarrer proprement :

kubectl delete pod webapp-7f4c8d6b9c-5g2kx -n init-demo

Le contrôleur de déploiement créera un nouveau pod qui exécutera le conteneur d'initialisation corrigé.

Mode de défaillance 2 : Le conteneur d'initialisation expire

Symptôme : Le pod reste dans Init:0/1 pendant longtemps, puis peut être tué si activeDeadlineSeconds est défini sur le pod.

Diagnostic : Vérifiez la commande du conteneur d'initialisation. S'il attend un service externe, assurez-vous que le service est joignable depuis le cluster. Utilisez un pod temporaire pour tester la connectivité :

kubectl run test-conn --rm -it --image=busybox:1.36 -n init-demo -- sh -c 'nc -zv postgres-svc 5432'

Sortie attendue si joignable :

postgres-svc (10.96.0.10:5432) open

Si ce n'est pas joignable, vérifiez le service, les points de terminaison et les politiques réseau.

Récupération : Corrigez le nom du service ou la politique réseau, appliquez le changement et supprimez le pod bloqué.

Mode de défaillance 3 : Échec de tirage d'image

Symptôme : Pod dans Init:ErrImagePull ou Init:ImagePullBackOff.

Diagnostic : kubectl describe pod montre des événements comme :

Warning  Failed     30s   kubelet            Failed to pull image "myrepo/init-helper:v1.0": rpc error: code = NotFound desc = failed to pull and unpack image

Vérifiez le nom et l'étiquette de l'image. Assurez-vous qu'elle existe dans le registre et que le nœud dispose des informations d'identification de tirage si nécessaire (imagePullSecrets dans la spécification du pod).

Récupération : Corrigez la référence de l'image dans la spécification du pod ou du déploiement. S'il s'agit d'un registre privé, ajoutez ou mettez à jour les imagePullSecrets :

spec:
  imagePullSecrets:
  - name: regcred
  initContainers:
  - name: init-helper
    image: myrepo/init-helper:v1.1

Appliquez et le pod devrait redémarrer avec l'image corrigée.

Mode de défaillance 4 : Épuisement des ressources

Symptôme : Le conteneur d'initialisation redémarre à plusieurs reprises ; la description montre OOMKilled dans le dernier état.

Diagnostic : kubectl describe pod montre :

Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137

Vérifiez les demandes et limites de ressources pour le conteneur d'initialisation. Si elles ne sont pas définies, le conteneur peut consommer plus que ce que le nœud peut fournir.

Récupération : Définissez des limites appropriées dans la spécification du conteneur d'initialisation. Par exemple :

initContainers:
- name: data-loader
  image: myrepo/loader:1.0
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

Appliquez le changement et le conteneur d'initialisation devrait se terminer sans OOM.

Stratégies de retour en arrière pour les changements de conteneur d'initialisation

Si une nouvelle configuration de conteneur d'initialisation provoque des échecs de pod, la récupération la plus rapide est souvent de revenir à la révision de déploiement précédente. Pour un déploiement :

kubectl rollout undo deployment webapp -n init-demo

Pour un StatefulSet ou un DaemonSet, vous devrez peut-être revenir manuellement au manifeste. Gardez toujours une version de manifeste connue et bonne dans git et appliquez-la :

kubectl apply -f deployment-webapp-known-good.yaml

Si le changement de conteneur d'initialisation a été effectué directement sur un pod en cours d'exécution (non recommandé), supprimez le pod pour laisser le contrôleur le recréer avec l'ancienne spécification.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après tout changement de configuration de conteneur d'initialisation pour minimiser les risques et accélérer la récupération.

Liste de contrôle avant le changement

• [ ] Confirmer la version du cluster et la compatibilité de l'API pour les fonctionnalités de conteneur d'initialisation que vous prévoyez d'utiliser (kubectl version --short).
• [ ] Enregistrer le statut actuel des pods et l'état du conteneur d'initialisation (kubectl get pods -n <namespace> -o wide, kubectl describe pod <pod-name>).
• [ ] Capturer la révision actuelle du déploiement et son historique (kubectl rollout history deployment <name>).
• [ ] Sauvegarder le manifeste actuel (kubectl get deploy <name> -o yaml > deploy-backup.yaml).
• [ ] Tester la nouvelle logique du conteneur d'initialisation dans un pod jetable dans un espace de noms séparé (kubectl run init-test --image=... --restart=Never --command -- <test command>).
• [ ] S'assurer que les secrets ne sont pas codés en dur ; utiliser les Secrets Kubernetes ou un gestionnaire de secrets.
• [ ] Définir les demandes et limites de ressources pour le conteneur d'initialisation.
• [ ] Documenter le résultat attendu et la commande de retour en arrière.

Liste de contrôle après le changement

• [ ] Surveiller la progression des pods (kubectl get pods -n <namespace> --watch), confirmer la transition de Init:0/1 à Running.
• [ ] Vérifier les journaux du conteneur d'initialisation pour un message de succès ou des erreurs (kubectl logs <pod> -c <init-container>).
• [ ] Vérifier la préparation du conteneur principal (kubectl get pods affiche 1/1 prêt ; kubectl rollout status deployment <name> réussit).
• [ ] Valider l'effet secondaire du conteneur d'initialisation (par exemple, exécuter une commande dans le conteneur principal et vérifier le fichier/les données).
• [ ] En cas d'échec, exécuter kubectl rollout undo deployment <name> ou réappliquer un manifeste connu et bon.
• [ ] Mettre à jour la documentation avec les nouvelles découvertes ou ajustements.

Exemple d'entrée de runbook

Voici un exemple concret pour un conteneur d'initialisation de migration de base de données dans un déploiement nommé api-server :

Runbook : migration du conteneur d'initialisation api-server

1. Avant de déployer une nouvelle version de migration :

   kubectl get deploy api-server -n prod -o yaml > api-server-backup.yaml
   kubectl rollout history deployment api-server -n prod

1. Appliquer le nouveau déploiement avec l'étiquette d'image du conteneur d'initialisation mise à jour :

   kubectl apply -f api-server-deploy.yaml

1. Surveiller les pods :

   kubectl get pods -n prod -l app=api-server --watch

Attendu : les pods passent de Init:0/1 à Running.

1. Si les pods sont bloqués dans Init:Error, vérifier les journaux :

   kubectl logs <new-pod> -c db-migrate -n prod --previous

1. Si la migration échoue, revenir en arrière :

   kubectl rollout undo deployment api-server -n prod

1. Après un déploiement réussi, confirmer la migration en vérifiant une version de table de base de données ou un point de terminaison de santé de l'application.

Conclusion

Les conteneurs d'initialisation sont une partie essentielle de nombreuses charges de travail Kubernetes, mais leurs pièges de configuration peuvent entraîner des échecs silencieux ou des pannes prolongées. En suivant une approche structurée — inventaire de version, configuration sûre, vérification approfondie et plans de récupération explicites — vous pouvez éviter les erreurs courantes et réagir rapidement lorsque les choses tournent mal.

Rappelez-vous les principes fondamentaux : observer avant de changer, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier les résultats avec des commandes concrètes et documenter les étapes de récupération avant d'en avoir besoin. Appliquez ces pratiques à vos configurations de conteneurs d'initialisation et vous construirez des applications Kubernetes plus fiables et plus faciles à maintenir.

La prochaine fois que vous modifierez un conteneur d'initialisation, commencez par la liste de contrôle des opérations et un manifeste de sauvegarde. Les quelques minutes de préparation vous feront économiser des heures de débogage lorsqu'un conteneur d'initialisation se comportera mal en production.