## Introduction Lorsqu'une installation ou une mise à niveau Helm échoue, le message d'erreur n'est que le point de départ. Une correction utile provient de la connaissance de la version de Helm, des valeurs attendues par le chart, de l'état actuel de la release et de la commande exacte qui a produit l'échec. Ce guide passe en revue les erreurs Helm courantes, leur signification et la manière de les résoudre à l'aide de commandes et d'exemples que vous pouvez exécuter dans votre propre cluster. Helm est un gestionnaire de paquets pour Kubernetes qui simplifie le déploiement d'applications. Mais comme tout outil, il a des modes de défaillance : incompatibilités de versions, valeurs mal formées, conflits d'API Kubernetes et corruption de l'état des releases. Chaque section ci-dessous couvre une erreur spécifique, explique pourquoi elle survient et fournit une correction ciblée avec des étapes de vérification. Avant de modifier quoi que ce soit, observez l'état actuel. Utilisez des espaces réservés au lieu de secrets réels, limitez les modifications à un composant à la fois et confirmez la récupération avant de poursuivre. Ce guide suppose que Helm est installé (la version 3.x est actuelle), que vous avez accès à un cluster Kubernetes et que kubectl est configuré. Les commandes utilisent des noms d'espaces de noms et de releases d'exemple ; remplacez-les par les vôtres. ## Inventaire des versions et de l'environnement Commencez par identifier les versions exactes et la topologie. Le comportement de Helm change entre les versions, et de nombreuses erreurs proviennent d'une incompatibilité entre le client Helm, le serveur Kubernetes ou les exigences d'API d'un chart. Vérifier la version du client Helm : helm version --short Sortie attendue pour Helm 3 : v3.12.0+g0a3159c Vérifier la version du serveur Kubernetes : kubectl version --short Remarque : dans les versions récentes de kubectl, le drapeau --short est déconseillé ; utilisez kubectl version sans lui. Vérifier le contexte et le cluster actuels : kubectl config current-context Confirmez que vous opérez sur le cluster prévu. Une erreur courante consiste à exécuter des commandes Helm sur le mauvais contexte, entraînant des modifications dans un espace de noms de production au lieu d'un environnement de test. Examiner les releases Helm existantes : helm list --all-namespaces Cela affiche toutes les releases, leurs statuts et leurs espaces de noms. Si une release est dans un état « failed » ou « pending », notez-le avant de tenter toute correction. Prérequis pour une correction sûre : - Helm 3.8+ recommandé pour un meilleur support OCI et des correctifs de sécurité. - Accès à l'espace de noms de la release ou autorisations à l'échelle du cluster si vous utilisez --all-namespaces . - Une sauvegarde de toutes les valeurs personnalisées utilisées lors des déploiements précédents. Considération sur le rayon d'impact : ne désinstallez jamais une release sans essayer d'abord helm rollback si une révision précédente existe. La désinstallation supprime toutes les ressources Kubernetes gérées par cette release, ce qui peut entraîner une perte de données si des volumes persistants sont inclus. ## Chemin de configuration sûr De nombreuses erreurs Helm proviennent de valeurs ou d'une configuration de chart incorrectes. L'approche sûre consiste à inspecter les valeurs actuelles, à utiliser --dry-run pour simuler les modifications, puis à appliquer avec --atomic pour une annulation automatique en cas d'échec. Erreur : values.yaml a un type invalide ou une clé manquante Helm produira quelque chose comme : Error: cannot load values.yaml: error converting YAML to JSON: yaml: line 5: did not find expected key Pourquoi cela arrive : YAML est sensible aux espaces ; une indentation mal alignée ou un caractère de tabulation casse l'analyse. De plus, le chart peut attendre une valeur qui n'est pas fournie. Correction : Validez d'abord la syntaxe YAML : yamllint values.yaml Ou utilisez helm lint pour vérifier le chart et les valeurs : helm lint mychart --values values.yaml Exemple de values.yaml avec une indentation correcte : replicaCount: 3 image: repository: nginx tag: "1.25" service: type: ClusterIP port: 80 Si une valeur est manquante, vérifiez le values.yaml du chart pour les clés requises. Vous pouvez inspecter les valeurs par défaut du chart : helm show values bitnami/nginx Fournissez ensuite la clé manquante dans votre fichier de surcharge. Erreur : Error: UPGRADE FAILED: cannot patch "my-deployment" with kind Deployment: ... field is immutable Cela se produit lorsqu'une mise à niveau tente de modifier un champ immuable, comme le sélecteur d'un déploiement ou le modèle de réclamation d'un volume. Helm ne peut pas modifier ces champs sur place. Correction : Souvent, la seule solution est de désinstaller et de réinstaller la release, ce qui remplace la ressource. Mais d'abord, voyez s'il existe un chemin de migration. Par exemple, certains charts permettent de changer le nom d'un déploiement pour éviter les conflits de sélecteur. Utilisez --force en dernier recours car cela peut provoquer une interruption : helm upgrade my-release bitnami/nginx --set replicaCount=4 --force Cependant, --force ne corrige pas les erreurs de champ immuable ; il ne fait que supprimer et recréer des ressources lorsque la mise à niveau échouerait autrement. Pour les erreurs de champ immuable, la solution de contournement typique est de supprimer la release et de la réinstaller, en acceptant une brève interruption : helm uninstall my-release helm install my-release bitnami/nginx --values values.yaml Modèle de mise à niveau sûr : helm upgrade my-release bitnami/nginx --values values.yaml --dry-run --debug Examinez le diff, puis : helm upgrade my-release bitnami/nginx --values values.yaml --atomic --timeout 5m Le drapeau --atomic annule la release si la mise à niveau échoue, laissant la version précédente en cours d'exécution. ## Vérification et diagnostics Après une modification, vérifiez l'état du déploiement et diagnostiquez tout nouveau problème. Vérifier le statut de la release : helm status my-release La sortie inclut l'heure du dernier déploiement, les ressources et les notes. Pour un examen plus approfondi de l'objet release : helm get manifest my-release Cela affiche les manifestes Kubernetes que Helm a envoyés au serveur d'API. Comparez-les avec les ressources attendues. Vérifier les ressources Kubernetes : kubectl get all -n my-namespace Si les pods ne démarrent pas, inspectez les événements : kubectl describe pod pod-name -n my-namespace Recherchez des erreurs de tirage d'image, des échecs de planification ou des problèmes de sonde de disponibilité. Déboguer un déploiement échoué : Si un pod est en CrashLoopBackOff, obtenez les journaux : kubectl logs pod-name -n my-namespace --previous Le drapeau --previous affiche les journaux de l'instance de conteneur précédente, utile lorsque le conteneur plante immédiatement. Exemple : erreur de tirage d'image Symptôme : ErrImagePull dans le statut du pod. Vérifiez le nom et le tag de l'image. Une erreur courante consiste à utiliser un tag qui n'existe pas. Vérifiez en tirant l'image manuellement (si vous avez Docker) : docker pull nginx:1.25 Si le tag est incorrect, corrigez-le dans values.yaml et mettez à niveau : helm upgrade my-release bitnami/nginx --set image.tag=1.25 Vérifiez ensuite que le pod est en cours d'exécution : kubectl get pods -n my-namespace ## Modes de défaillance et récupération Les releases Helm peuvent passer dans un état d'échec en raison d'opérations interrompues, de ressources conflictuelles ou de modifications de l'API Kubernetes. Voici les modes de défaillance courants et les étapes de récupération. Erreur : Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress Cela se produit lorsqu'une opération Helm précédente est toujours en cours ou est restée bloquée. Helm utilise un verrou dans l'espace de noms de la release pour empêcher les opérations concurrentes. Correction : Attendez que l'opération se termine, ou si elle est bloquée, supprimez le verrou. D'abord, vérifiez si un processus Helm est toujours en cours : ps aux | grep helm Si aucun processus n'est en cours, le verrou peut être obsolète. Vous pouvez supprimer le verrou à l'aide de kubectl (uniquement si vous êtes sûr qu'aucune opération n'est en cours) : kubectl delete secret -n my-namespace sh.helm.release.v1.my-release.v1.lock Pour Helm 3, les verrous sont stockés sous forme de secrets ou de configmaps Kubernetes (selon le backend de stockage). Le nom du secret suit le modèle sh.helm.release.v1..v.lock . Après avoir supprimé le verrou, réessayez l'opération. Erreur : Error: release: not found Cela se produit lorsque vous essayez de mettre à niveau ou d'annuler une release qui n'existe pas. Vérifiez les releases : helm list --all-namespaces Si la release est manquante, vous devrez peut-être l'installer à nouveau ou la restaurer à partir d'une sauvegarde. Récupérer une release échouée via l'annulation : Si une release a des révisions précédentes réussies, l'annulation est la récupération la plus rapide : helm history my-release La sortie affiche les numéros de révision et les statuts. Pour annuler vers une révision spécifique : helm rollback my-release 2 Vérifiez que l'annulation a réussi : helm status my-release Erreur : Error: rendered manifests contain a resource that already exists Cela peut se produire lorsqu'une ressource a été créée en dehors de Helm ou par une release différente. Helm refuse d'adopter des ressources existantes sauf si vous utilisez --force ou supprimez manuellement la ressource conflictuelle. Correction : Identifiez la ressource conflictuelle avec --dry-run et --debug : helm upgrade my-release bitnami/nginx --dry-run --debug La sortie affichera la ressource qui existe déjà. Si c'est sûr, supprimez cette ressource manuellement (assurez-vous qu'elle n'est pas gérée par autre chose), puis réessayez. Alternativement, vous pouvez utiliser --force pour la remplacer, mais cela peut provoquer une interruption. ## Pièges courants et comment les éviter Au fil des ans, certaines erreurs se répètent chez les utilisateurs de Helm. Voici les plus fréquentes, pourquoi elles surviennent et comment s'en remettre. - Ne pas épingler les versions de chart. Utiliser latest ou des tags flottants entraîne des changements inattendus et des échecs difficiles à reproduire. Spécifiez toujours une version de chart et un tag d'image dans values.yaml ou avec le drapeau --version . - Gérer les secrets en clair. Mettre des mots de passe dans values.yaml et les committer dans Git est un risque de sécurité. Utilisez les secrets Kubernetes avec la gestion intégrée des secrets de Helm ou des outils externes comme Sealed Secrets ou Vault. - Ignorer la sortie de --dry-run . Sauter la simulation signifie des surprises en production. Prévisualisez toujours les modifications, surtout lors des mises à niveau. - Supprimer une release sans vérifier les dépendances. Désinstaller un chart dont d'autres services dépendent peut casser l'application. Utilisez helm dependency list pour voir les dépendances. - Ne pas définir de limites de ressources. Les charts sans limites de ressources peuvent affamer d'autres charges de travail. Définissez des limites dans les valeurs sous resources . - Laisser des releases échouées traîner. Les releases échouées encombrent le cluster et peuvent bloquer les opérations futures. Nettoyez-les avec helm uninstall après investigation. Exemple de récupération : Si vous avez accidentellement désinstallé une release et que vous avez une sauvegarde du secret de release (si vous utilisez le stockage par secrets), vous pouvez potentiellement la restaurer. Helm stocke les données de release dans des secrets nommés sh.helm.release.v1..v . Si vous avez une sauvegarde de ce secret, vous pouvez le recréer, mais les ressources Kubernetes associées doivent également être présentes. Une meilleure récupération consiste à redéployer depuis votre pipeline CI/CD ou depuis un dépôt Git contenant le chart et les valeurs. ## Liste de contrôle des opérations Avant d'apporter une modification à une release Helm, passez en revue cette liste de contrôle. Elle est conçue pour minimiser les risques et garantir une récupération fluide si quelque chose tourne mal. - [ ] Confirmer le contexte Kubernetes correct : kubectl config current-context - [ ] Vérifier la version du client Helm et la compatibilité avec le cluster : helm version - [ ] Lister les releases actuelles et leurs statuts : helm list --all-namespaces - [ ] Examiner les valeurs par défaut du chart et vos surcharges : helm show values et inspecter votre values.yaml - [ ] Créer une sauvegarde des valeurs personnalisées actuelles ou du manifeste de la release : helm get manifest my-release > my-release-backup.yaml - [ ] Toujours exécuter une simulation avant la mise à niveau : helm upgrade my-release chart --dry-run --debug - [ ] Pour les mises à niveau, utiliser --atomic pour une annulation automatique en cas d'échec - [ ] Définir un délai d'attente approprié : --timeout 10m pour les grands charts - [ ] Après le déploiement, vérifier le statut des pods et les journaux : kubectl get pods et kubectl logs - [ ] Documenter le changement et le plan d'annulation Attribuez un responsable unique pour les opérations de release dans votre équipe (par exemple, l'ingénieur de garde). Examinez les configurations de release mensuellement et après les mises à jour majeures des charts. ## Conclusion Les erreurs Helm peuvent être intimidantes, mais elles sont généralement résolubles avec une approche systématique. Commencez par comprendre votre environnement : versions, releases existantes et état actuel. Utilisez des modèles sûrs comme --dry-run et --atomic pour prévenir les mauvaises modifications. Lorsque des échecs surviennent, inspectez le statut de la release, les manifestes et les ressources Kubernetes pour identifier la cause. Apprenez des pièges courants pour éviter les problèmes récurrents. Ayez toujours un plan d'annulation. Pour mettre cela en pratique, choisissez une vérification à faible risque pour votre prochaine opération Helm : exécutez helm lint sur votre chart, faites une mise à niveau simulée ou vérifiez l'historique de la release. Enregistrez l'état actuel, exécutez la commande et comparez le résultat avec la sortie attendue. Examinez les dépendances et assurez-vous que votre équipe suit la liste de contrôle des opérations. Avec ces habitudes, Helm devient un outil de déploiement fiable plutôt qu'une source d'échecs mystérieux.