## Introduction Helm est le gestionnaire de paquets pour Kubernetes, mais lorsqu'une version échoue, qu'un modèle rend un résultat incorrect ou qu'une restauration ne se comporte pas comme prévu, le chemin du symptôme à la solution est rarement évident. Dépanner Helm efficacement signifie dépasser les conjectures : vous devez identifier la version installée, comprendre la topologie du déploiement, capturer les bons journaux et apporter des modifications limitées et réversibles. Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui utilisent Helm sur de vrais clusters. Il se concentre sur le diagnostic pratique : erreurs Helm, journaux Helm, commandes Helm et récupération Helm. Chaque section associe un problème observé à une commande concrète, la sortie attendue, un signal d'échec et une décision de récupération. Les exemples sont volontairement limités en version et utilisent des espaces réservés au lieu de secrets réels ou d'identifiants de production. Le principe opérationnel tout au long du guide est la sécurité : observer avant de modifier, limiter le rayon d'impact, protéger les valeurs sensibles, vérifier le résultat et savoir comment récupérer avant de toucher quoi que ce soit. ## Inventaire des versions et de l'environnement Avant de pouvoir dépanner un problème Helm, vous devez savoir exactement ce que vous exécutez. De nombreux problèmes sont causés par des incompatibilités de version entre le client Helm, le cluster Kubernetes et le chart. Commencez par un inventaire en lecture seule. ### Vérifier la version du client Helm helm version --short Sortie attendue : v3.12.3+g3a31588 Si la commande échoue, Helm n'est pas installé ou n'est pas dans votre PATH. Installez-le depuis la documentation officielle et assurez-vous que la version correspond à celle standardisée par votre équipe. ### Vérifier la version du cluster Kubernetes kubectl version --short Sortie attendue : Client Version: v1.27.3 Kustomize Version: v5.0.1 Server Version: v1.28.0 Un écart de plus d'une version mineure entre le client et le serveur peut provoquer des incompatibilités d'API dans les manifestes rendus. Si vous voyez un message comme « Error from server (NotFound): the server could not find the requested resource », votre chart utilise peut-être une version d'API qui a été supprimée dans la version du cluster. ### Lister les versions Helm installées helm list --all-namespaces Sortie attendue : NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION my-release default 3 2024-05-12 10:24:31.123456789 +0000 UTC deployed my-app-1.2.0 1.0.0 Faites attention à la colonne STATUS. Si une version est dans un état failed ou pending, c'est votre premier indice. Si l'horodatage de mise à jour est ancien, vous êtes peut-être face à une version obsolète. ### Capturer les détails de l'environnement helm env La sortie attendue inclut : HELM_BIN="/usr/local/bin/helm" HELM_CACHE_HOME="/home/user/.cache/helm" HELM_CONFIG_HOME="/home/user/.config/helm" HELM_DATA_HOME="/home/user/.local/share/helm" HELM_KUBECONTEXT="prod-cluster" HELM_NAMESPACE="default" Cela montre le contexte Kubernetes et le namespace actuels, ce qui est crucial car les commandes Helm utilisent par défaut le contexte de votre kubeconfig. Une erreur courante est d'exécuter des commandes Helm sur le mauvais cluster. Vérifiez toujours le contexte avant de faire des changements : kubectl config current-context Sortie attendue : prod-cluster Si le contexte n'est pas celui attendu, basculez explicitement avant de continuer : kubectl config use-context staging-cluster ### Enregistrer la topologie Pour une version spécifique, voyez quelles ressources Kubernetes ont été créées : helm get manifest my-release -n default Cela affiche le manifeste rendu. Vous pouvez l'enregistrer dans un fichier pour comparaison ultérieure : helm get manifest my-release -n default > my-release-manifest-backup.yaml Avant toute modification, capturez cette référence. C'est votre point de récupération si une modification tourne mal. ## Chemin de configuration sûr Les pratiques de dépannage Helm les plus dangereuses consistent à modifier directement les ressources en direct ou à remplacer des valeurs sans comprendre le rayon d'impact. Un chemin de configuration sûr sépare l'observation de l'intervention. ### Inspecter les valeurs actuelles sans rien changer helm get values my-release -n default Sortie attendue : USER-SUPPLIED VALUES: replicaCount: 2 image: repository: nginx tag: "1.25.0" service: type: ClusterIP Cela montre uniquement les valeurs que vous ou un opérateur précédent avez fournies lors de l'installation ou de la mise à niveau. Cela n'affiche pas les valeurs par défaut du chart. Pour voir toutes les valeurs effectives : helm get values my-release -n default --all Cela inclut les valeurs par défaut calculées. Comparez les deux pour comprendre ce qui est explicitement défini par rapport à ce qui est hérité. ### Rendre les modèles localement avant d'appliquer Si vous modifiez des valeurs, prévisualisez d'abord les manifestes rendus avec un essai local. Créez un fichier de remplacement de valeurs override.yaml : replicaCount: 3 image: tag: "1.26.0" resources: limits: cpu: "500m" memory: "512Mi" requests: cpu: "250m" memory: "256Mi" Puis rendez le chart localement : helm template my-release ./my-chart -f override.yaml > rendered.yaml Inspectez rendered.yaml pour vérifier l'exactitude. Cela ne touche pas le cluster. Si le modèle a une erreur, Helm affichera un diagnostic, tel que : Error: parse error at (my-chart/templates/deployment.yaml:12): unexpected "}" in if Corrigez le modèle avant de continuer. ### Valider avec un essai de mise à niveau Pour tester un changement sur le cluster en direct sans l'appliquer : helm upgrade my-release ./my-chart -f override.yaml --dry-run --debug Cela simule la mise à niveau et affiche la différence entre la version actuelle et celle proposée. Ajoutez --debug pour voir la sortie du modèle et l'exécution des hooks. La sortie se termine par : Release "my-release" has been upgraded. Happy Helming! Même si cela indique une mise à niveau, rien n'a changé. C'est un moyen sûr de détecter les erreurs. ### Faire le plus petit changement justifié Si l'essai est propre, appliquez la mise à niveau : helm upgrade my-release ./my-chart -f override.yaml --atomic --wait - --atomic restaure automatiquement la version si la mise à niveau échoue. - --wait attend que les ressources soient prêtes avant de rendre la main. Si la mise à niveau échoue, Helm restaurera automatiquement la révision précédente, mais seulement si --atomic a été spécifié. Sinon, vous devrez restaurer manuellement (voir Modes d'échec et récupération). ## Vérification et diagnostics Après tout changement, vérifiez le résultat avant de considérer le problème résolu. Helm fournit plusieurs commandes de diagnostic en lecture seule. ### Vérifier le statut de la version helm status my-release -n default La sortie attendue inclut : NAME: my-release LAST DEPLOYED: Mon May 13 15:04:05 2024 NAMESPACE: default STATUS: deployed REVISION: 4 Si le statut n'est pas « deployed », approfondissez. Un statut de « pending-install » ou « pending-upgrade » signifie que l'opération est encore en cours ou bloquée. ### Inspecter les ressources Kubernetes créées par la version Utilisez des étiquettes pour lister les ressources : kubectl get all -n default -l app.kubernetes.io/instance=my-release La sortie attendue montre le pod, le service et le déploiement. Si un pod ne fonctionne pas, décrivez-le : kubectl describe pod my-release-nginx-6d4cf56db6-c9bgk -n default Cherchez des événements comme : Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Failed 10m kubelet Failed to pull image "nginx:1.26.0": rpc error: code = NotFound desc = failed to pull and unpack image Warning Unhealthy 5m kubelet Readiness probe failed: Get "http://10.0.0.12:80/": dial tcp 10.0.0.12:80: connect: connection refused Cela vous indique que l'étiquette d'image est manquante ou que le conteneur n'est pas prêt. ### Vérifier les journaux Récupérez les journaux d'un pod spécifique : kubectl logs my-release-nginx-6d4cf56db6-c9bgk -n default Si le pod a planté, utilisez --previous pour voir les journaux de l'instance de conteneur précédente : kubectl logs my-release-nginx-6d4cf56db6-c9bgk -n default --previous Utilisez helm get manifest pour vérifier ce que Helm a réellement rendu : helm get manifest my-release -n default | grep -A5 -B5 "image:" Cela montre la spécification d'image exacte dans la révision actuelle. Comparez-la avec vos valeurs. ### Valider les hooks Les hooks Helm sont des ressources Kubernetes qui s'exécutent à des moments spécifiques du cycle de vie de la version. Affichez les hooks d'une version : kubectl get jobs -n default -l helm.sh/chart=my-app-1.2.0,helm.sh/hook=pre-install Si un hook échoue, la version peut être bloquée. Vérifiez les journaux du hook et supprimez le job de hook échoué pour permettre une nouvelle tentative, mais seulement après avoir compris pourquoi il a échoué. ## Modes d'échec et récupération Les échecs Helm se classent généralement en quelques catégories : erreurs de rendu de modèle, échecs de mise à niveau, problèmes de restauration et délais d'attente des hooks. Connaître le chemin de récupération pour chacun est essentiel. ### Mise à niveau échouée Si helm upgrade échoue et que vous n'avez pas utilisé --atomic , la version peut rester dans un état d'échec. Vérifiez le statut de la version : helm list -n default La sortie peut montrer : NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION my-release default 4 2024-05-13 15:04:05.123456789 +0000 UTC failed my-app-1.3.0 1.0.0 Pour récupérer, restaurez la dernière révision connue comme bonne : helm rollback my-release 3 -n default Sortie attendue : Rollback was a success! Happy Helming! Si vous ne savez pas quelle révision restaurer, affichez l'historique : helm history my-release -n default La sortie montre chaque révision avec son statut et sa description. ### La restauration ne fonctionne pas Parfois, une restauration échoue car les ressources de la révision précédente ne sont plus valides (par exemple, elles référencent une CRD supprimée). Dans ce cas, vous devrez peut-être désinstaller et réinstaller, mais sauvegardez d'abord toutes les données importantes. Inspectez le manifeste précédent : helm get manifest my-release --revision 3 -n default > previous-manifest.yaml Si le manifeste est inutilisable, envisagez de restaurer à partir d'une version de chart connue comme bonne : helm upgrade my-release ./my-chart --version 1.2.0 --reset-values --atomic Cela réinitialise les valeurs par défaut du chart pour cette version, en écartant toute valeur fournie par l'utilisateur. À utiliser avec prudence en production. ### Délai d'attente du hook Les hooks Helm ont un délai d'attente par défaut de 5 minutes. Si un hook prend plus de temps, la version échoue avec : Error: timed out waiting for the condition Pour augmenter le délai d'attente d'un hook spécifique, définissez timeoutSeconds dans l'annotation du hook : apiVersion: batch/v1 kind: Job metadata: name: my-migration annotations: "helm.sh/hook": pre-upgrade "helm.sh/hook-delete-policy": hook-succeeded "helm.sh/hook-timeout": "600" Puis relancez la mise à niveau. Alternativement, exécutez manuellement le job et supprimez le hook après son succès, mais l'approche par annotation est plus propre. ### Version bloquée Si une version est bloquée en « pending-install » ou « pending-upgrade », cela signifie souvent que l'opération Kubernetes ne s'est pas terminée. Listez les ressources et cherchez des objets bloqués : kubectl get all -n default -l app.kubernetes.io/instance=my-release Si un pod est bloqué en terminaison, forcez sa suppression après avoir confirmé que c'est sûr : kubectl delete pod my-release-nginx-6d4cf56db6-c9bgk -n default --grace-period=0 --force Vérifiez ensuite si l'opération Helm se termine. Sinon, vous devrez peut-être restaurer ou désinstaller. ### Désinstallation et nettoyage Quand tout le reste échoue, désinstallez la version et réinstallez à partir d'un état propre : helm uninstall my-release -n default --keep-history L'option --keep-history conserve l'historique de la version pour inspection ou restauration ultérieure. Sans elle, l'historique est supprimé. Pour supprimer complètement, exécutez sans l'option. ## Liste de contrôle opérationnelle Utilisez cette liste de contrôle avant et après chaque session de dépannage Helm. Elle renforce les principes de sécurité et rend vos actions reproductibles. Attribuez chaque vérification à un responsable unique (par exemple, l'ingénieur de garde) et révisez la liste mensuellement ou après tout incident. ### Liste de contrôle pré-changement - [ ] Confirmez le contexte du cluster avec kubectl config current-context . Attendu : le cluster cible, pas le staging ou le local. Responsable : ingénieur de garde. - [ ] Enregistrez les versions du client et du serveur Helm avec helm version --short et kubectl version --short . Notez toute incompatibilité. - [ ] Listez les versions actuelles avec helm list --all-namespaces . Notez toute version échouée. - [ ] Capturez les valeurs actuelles avec helm get values -n --all . Enregistrez dans un fichier. - [ ] Capturez le manifeste actuel avec helm get manifest -n . Enregistrez dans un fichier. - [ ] Identifiez la ressource ou la valeur exacte à modifier. Définissez le résultat attendu. - [ ] Déterminez le rayon d'impact : quelles ressources seront modifiées ? Qui les consomme ? - [ ] Préparez un plan de restauration : connaissez le numéro de révision précédent ( helm history ) et la commande pour revenir en arrière. - [ ] Si des secrets sont impliqués, utilisez des espaces réservés ou des variables d'environnement, jamais de valeurs réelles dans les commandes ou fichiers. ### Vérification post-changement - [ ] Exécutez helm status -n . Confirmez que STATUS est deployed. - [ ] Exécutez kubectl get pods -n -l app.kubernetes.io/instance= . Confirmez que tous les pods sont Running et Ready. - [ ] Vérifiez les journaux des pods pour les erreurs : kubectl logs -n . Cherchez des traces de pile ou des problèmes de connectivité. - [ ] Vérifiez que le point de terminaison de santé de l'application renvoie la réponse attendue (par exemple, curl http://service-name/health ). - [ ] Si des hooks sont impliqués, confirmez que les jobs de hook ont réussi : kubectl get jobs -n -l helm.sh/hook=pre-upgrade,helm.sh/chart= . Le statut doit être Complete. - [ ] Documentez le changement, y compris les valeurs avant/après et les résultats de vérification. ### Fréquence de révision - Cette liste est révisée mensuellement lors de la revue opérationnelle de l'équipe. - Après tout déploiement échoué, la liste est mise à jour pour capturer le nouveau mode d'échec. - L'ingénieur de garde est responsable de la liste pendant son quart. Le responsable DevOps examine les changements trimestriellement. ## Pièges courants et comment les éviter Même les opérateurs expérimentés commettent ces erreurs. Les connaître à l'avance fait gagner des heures. ### 1. Utiliser le mauvais contexte Kubernetes Pourquoi cela arrive : Vous avez plusieurs clusters configurés dans le kubeconfig, et Helm utilise le contexte actuel par défaut. Une commande destinée au staging frappe accidentellement la production. Comment éviter : Exécutez toujours kubectl config current-context avant une commande Helm, ou utilisez explicitement --kube-context . Par exemple : helm upgrade my-release ./my-chart --kube-context prod-cluster Comment récupérer : Si vous avez déjà modifié le mauvais cluster, notez immédiatement l'horodatage et ce qui a été changé, puis restaurez la révision précédente si possible. Si le changement était une mise à niveau échouée, la version peut être intacte. Si elle a réussi mais est incorrecte, effectuez une restauration. ### 2. Modifier les ressources directement au lieu d'utiliser Helm Pourquoi cela arrive : Dans la précipitation, vous utilisez kubectl edit deployment pour corriger une spécification de pod. Cela crée une dérive entre la version Helm et le cluster en direct. La prochaine helm upgrade peut annuler ou entrer en conflit avec votre modification manuelle. Comment éviter : Modifiez toujours le chart ou les valeurs Helm et exécutez helm upgrade . Si vous devez faire une modification temporaire en direct, documentez-la et annulez-la dès que possible en réappliquant l'état géré par Helm. Comment récupérer : Utilisez helm get manifest pour voir l'état géré par Helm et comparez avec le direct. Exécutez helm upgrade avec les bonnes valeurs pour réaligner. ### 3. Ne pas utiliser --atomic lors des mises à niveau Pourquoi cela arrive : Vous supposez que la mise à niveau réussira et omettez --atomic . Si elle échoue, la version reste dans un état d'échec, et certaines ressources peuvent avoir été partiellement mises à jour. Comment éviter : Utilisez toujours --atomic pour les mises à niveau en production. Cela garantit une restauration automatique en cas d'échec. Comment récupérer : Restaurez manuellement : helm rollback my-release -n default . ### 4. Coder en dur des secrets dans les fichiers de valeurs Pourquoi cela arrive : Par commodité, vous mettez des mots de passe de base de données ou des clés API dans values.yaml . Ils peuvent être validés dans le contrôle de version ou exposés dans les journaux. Comment éviter : Utilisez les Secrets Kubernetes, ou référencez les valeurs depuis des variables d'environnement ou un gestionnaire de secrets. Helm a un indicateur intégré --set mais évitez-le pour les secrets. Utilisez plutôt un fichier de valeurs qui pointe vers une référence de clé secrète. Comment récupérer : Si un secret a été exposé, faites-le tourner immédiatement. Mettez à jour le Secret Kubernetes et redéployez. ### 5. Ignorer les échecs de hook Pourquoi cela arrive : Un job de migration pré-mise à niveau échoue, mais la mise à niveau continue car elle ne bloque pas le déploiement dans certaines configurations. L'application fonctionne avec un mauvais schéma. Comment éviter : Vérifiez toujours le statut des jobs de hook avant de marquer une mise à niveau comme réussie. Utilisez --wait pour attendre que les ressources, y compris les hooks, soient prêtes. Comment récupérer : Corrigez la cause racine de l'échec du hook, puis relancez la mise à niveau. Si nécessaire, supprimez le job de hook échoué pour effacer son statut, mais seulement après avoir résolu le problème. ### 6. Incompatibilité de version entre Helm et le chart Pourquoi cela arrive : Vous utilisez un client Helm plus ancien avec un chart qui nécessite Helm 3.7+, ou le chart utilise des API absentes de votre version Kubernetes. Comment éviter : Vérifiez la version Helm requise du chart dans son Chart.yaml (champ helmdependencies ou engine ). Assurez-vous que votre client et votre cluster répondent aux exigences. Comment récupérer : Mettez à niveau le client Helm vers une version compatible, ou utilisez une version de chart plus ancienne qui fonctionne avec votre configuration actuelle. ## Conclusion Le dépannage Helm avec exemples pratiques consiste à transformer les conjectures en un processus reproductible. Commencez par un inventaire précis des versions et de l'environnement, utilisez des essais à sec et des inspections de valeurs sûrs, vérifiez les changements avec des diagnostics en lecture seule, et connaissez les modes d'échec et leurs commandes de récupération. Chaque étape doit être limitée, observable et réversible lorsque la technologie le permet. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure d'exploitation. Un flux de travail fiable rend l'échec visible, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Comme prochaine étape, choisissez une vérification à faible risque de ce guide : confirmez le contexte du cluster, rendez un modèle localement ou exécutez une mise à niveau d'essai. Enregistrez l'état actuel, exécutez la vérification documentée, comparez le résultat avec le signal attendu et examinez les dépendances telles que Kubernetes, GitLab CI/CD et les points d'intégration Docker. Documentez ensuite ce que vous avez appris pour votre équipe.