Déboguer Helm : lint, template, --debug et diagnostics

Quand un déploiement Helm échoue, le message d'erreur ne dit pas toujours clairement ce qui s'est passé. Ce guide vous donne une méthode systématique de diagnostic : d'abord valider le chart lui-même, puis inspecter ce qu'il génère, et enfin analyser l'état de la release. En 20 minutes, vous saurez identifier rapidement si le problème vient du chart, des values, ou du cluster.

Ce que vous allez apprendre :

• Détecter les erreurs de syntaxe avant de déployer avec helm lint
• Comprendre exactement ce que Helm va envoyer au cluster avec helm template
• Investiguer une release en échec avec helm status, helm get
• Prévisualiser les changements avec helm diff avant un upgrade
• Résoudre les erreurs les plus courantes

La règle d'or du debug Helm

Toujours vérifier localement avant de déployer. Un helm template de 30 secondes peut vous éviter 30 minutes de debug sur un cluster cassé.

Pré-requis

• Helm v3.8+ installé
• Un chart à déboguer (ou créez-en un avec helm create mon-chart)
• Un cluster Kubernetes (optionnel pour les premières étapes)

La méthode de triage en 4 étapes

Le réflexe naturel face à un déploiement cassé est de relancer helm upgrade en espérant que ça passe. C'est le meilleur moyen de laisser la release en statut pending et de vous bloquer vous-même. La méthode ci-dessous part au contraire du niveau le plus local (les fichiers sur votre disque) pour remonter progressivement vers le cluster. Les deux premières étapes s'exécutent hors ligne, donc sans risque.

Étape	Commande	Ce qu'on vérifie	Sans cluster ?
1	helm lint	Syntaxe du chart	✅ Oui
2	helm template	Manifests générés	✅ Oui
3	helm install --dry-run	Validation côté serveur	❌ Non
4	helm status / helm get	État de la release	❌ Non

Glissez pour voir

Pourquoi cet ordre ? Chaque étape filtre une catégorie de problèmes. Si helm lint échoue, inutile de tester le reste, le chart est syntaxiquement incorrect. Si helm template échoue, le problème vient des values ou des templates. Si --dry-run échoue, c'est un problème de validation Kubernetes.

---

Étape 1, Valider la syntaxe avec helm lint

C'est le filtre le moins coûteux : helm lint lit les fichiers du chart sur votre disque et ne contacte jamais l'API Kubernetes. Il attrape les fautes qui empêchent le rendu des templates, celles qui vous feraient perdre le plus de temps si elles remontaient depuis un pipeline. Tant qu'il échoue, tester la suite ne sert à rien : Helm n'a même pas de manifests à envoyer.

Pourquoi lint ?

helm lint analyse un chart sans le déployer et détecte :

• Les erreurs de syntaxe YAML
• Les templates Go malformés (accolades manquantes, fonctions inconnues)
• Les valeurs manquantes référencées dans les templates
• Les bonnes pratiques non respectées (icon recommandé, etc.)

Utilisation basique

L'argument est un chemin de chart, pas un nom de release : helm lint travaille sur les fichiers du disque et fonctionne donc sans cluster, y compris sur un poste hors ligne.

helm lint ./mon-chart

==> Linting ./mon-chart
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

Décryptage du résultat :

Niveau	Signification	Action
[INFO]	Recommandation (non bloquant)	Optionnel à corriger
[WARNING]	Problème potentiel	À investiguer
[ERROR]	Erreur bloquante	Doit être corrigée

Glissez pour voir

Exemple avec erreur de template

Prenons un template qui référence une valeur absente du values.yaml :

templates/configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Values.config.name }}  # config n'existe pas dans values.yaml

helm lint ./mon-chart

==> Linting ./mon-chart
[INFO] Chart.yaml: icon is recommended
[ERROR] templates/: template: mon-chart/templates/configmap.yaml:4:18:
        executing "mon-chart/templates/configmap.yaml" at <.Values.config.name>:
        nil pointer evaluating interface {}.name

Error: 1 chart(s) linted, 1 chart(s) failed

Ce que l'erreur vous dit :

• Fichier : templates/configmap.yaml
• Ligne : 4, colonne 18
• Problème : .Values.config.name → config est nil (n'existe pas)
• Solution : Soit ajouter config.name dans values.yaml, soit utiliser {{ .Values.config.name | default "fallback" }}

Mode strict

Le flag --strict transforme les [INFO] et [WARNING] en erreurs bloquantes :

helm lint ./mon-chart --strict

Quand utiliser --strict ? En CI/CD, pour imposer le respect des bonnes pratiques. En développement local, le mode normal suffit.

---

Étape 2, Voir le rendu avec helm template

Un chart peut passer le lint et produire malgré tout des manifests faux : mauvaise valeur injectée, bloc conditionnel jamais activé, ressource absente. Cette étape rend visible le YAML final, celui que Helm enverrait réellement à l'API. C'est la commande à dégainer dès qu'un doute porte sur les values ou sur un {{- if }}.

Pourquoi template ?

helm template génère les manifests Kubernetes exactement comme ils seront envoyés au cluster, mais sans les déployer. C'est votre outil principal pour comprendre ce que Helm fait réellement.

Utilisation basique

Le premier argument est le nom de release, et ce n'est pas une simple étiquette : il alimente .Release.Name, donc changer ce nom change le préfixe des ressources générées.

helm template my-release ./mon-chart

mon-chart/templates/serviceaccount.yaml

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-release-mon-chart
  labels:
    helm.sh/chart: mon-chart-0.1.0
    app.kubernetes.io/name: mon-chart
    app.kubernetes.io/instance: my-release
    app.kubernetes.io/version: "1.16.0"
    app.kubernetes.io/managed-by: Helm
---
# Source: mon-chart/templates/service.yaml
apiVersion: v1
kind: Service
...

Ce que vous devez vérifier :

Élément	Question à se poser
Noms des ressources	Est-ce que my-release-mon-chart est cohérent ?
Labels	Les labels app.kubernetes.io/* sont-ils présents ?
Values injectées	Est-ce que replicas: 1 correspond à ce que je voulais ?
Ressources générées	Est-ce qu'il manque un Service ? Un ConfigMap ?

Glissez pour voir

Tester avec des values spécifiques

L'ordre de priorité est fixe : les valeurs par défaut du values.yaml du chart sont écrasées par les fichiers passés en -f, eux-mêmes écrasés par les --set. Si vous empilez plusieurs -f, c'est le dernier fichier de la ligne de commande qui gagne.

# Avec un fichier de values
helm template my-release ./mon-chart -f values-prod.yaml

# Avec une surcharge inline
helm template my-release ./mon-chart --set replicaCount=5

# Combiner les deux
helm template my-release ./mon-chart -f values-prod.yaml --set image.tag=v2.0.0

Pourquoi c'est important ? Un chart peut fonctionner avec les values par défaut mais échouer avec vos values de production. Testez toujours avec les values réelles.

Filtrer la sortie

La sortie de helm template peut être volumineuse. Utilisez grep ou yq pour filtrer :

# Voir uniquement les Deployments
helm template my-release ./mon-chart | grep -A 50 "kind: Deployment"

# Voir uniquement le nombre de replicas
helm template my-release ./mon-chart | grep "replicas:"

# Avec yq (si installé)
helm template my-release ./mon-chart | yq 'select(.kind == "Deployment")'

Mode debug

Le flag --debug ajoute des informations sur le chemin du chart et la version :

helm template my-release ./mon-chart --debug

install.go:225: 2026-02-01 19:39:36 [debug] Original chart version: ""
install.go:242: 2026-02-01 19:39:36 [debug] CHART PATH: /path/to/mon-chart

---
# Source: mon-chart/templates/serviceaccount.yaml
...

Quand utiliser --debug ? Quand vous n'êtes pas sûr que Helm charge le bon chart (problème de chemin, de dépendances).

---

Étape 3, Validation serveur avec --dry-run

Les deux premières étapes ne connaissent que votre disque. Elles ne savent pas si le CRD attendu est installé, si le nom généré dépasse la longueur admise, ni si l'apiVersion employée existe encore sur ce cluster. Cette étape confie les manifests à l'API Kubernetes pour qu'elle les juge, sans rien créer.

Pourquoi dry-run ?

helm template génère les manifests localement, sans contacter le cluster. Certaines erreurs ne sont détectées que par l'API Kubernetes :

• CRDs manquantes
• Quotas dépassés
• Noms de ressources invalides (trop longs, caractères interdits)
• Versions d'API obsolètes

--dry-run envoie les manifests au serveur Kubernetes pour validation sans créer les ressources.

Utilisation

Précisez toujours le namespace avec -n : la validation s'effectue dans son contexte, et un même manifest peut passer dans l'un et être refusé dans l'autre.

helm install my-release ./mon-chart --dry-run -n mon-namespace

NAME: my-release
LAST DEPLOYED: Sun Feb  1 19:41:13 2026
NAMESPACE: mon-namespace
STATUS: pending-install
REVISION: 1
HOOKS:
---
# Source: mon-chart/templates/tests/test-connection.yaml
...
MANIFEST:
---
# Source: mon-chart/templates/serviceaccount.yaml
...

Différence avec helm template :

Aspect	helm template	helm install --dry-run
Nécessite un cluster	❌ Non	✅ Oui
Valide le schema K8s	❌ Non	✅ Oui
Vérifie les CRDs	❌ Non	✅ Oui
Vérifie les quotas	❌ Non	✅ Oui
Vitesse	⚡ Instantané	🐢 Quelques secondes

Glissez pour voir

Dry-run côté serveur vs client

Helm propose deux modes de dry-run :

# Dry-run côté serveur (défaut depuis Helm 3.13+)
helm install my-release ./mon-chart --dry-run

# Dry-run côté client (comme helm template)
helm install my-release ./mon-chart --dry-run=client

Utilisez --dry-run (serveur) pour la validation complète, --dry-run=client si vous n'avez pas de cluster disponible.

---

Étape 4, Diagnostiquer une release existante

Si les trois premières étapes passent, le chart est sain et le problème est côté cluster ou dans l'historique de la release. Helm conserve dans des Secrets du namespace les manifests et les values de chaque révision, ce qui permet de comparer ce qui a été envoyé avec ce que vous croyiez envoyer. Les commandes qui suivent lisent cet historique.

helm status : état général

Quand une release est déployée mais semble ne pas fonctionner, commencez par helm status :

helm status demo -n helm-debug

NAME: demo
LAST DEPLOYED: Sun Feb  1 19:40:13 2026
NAMESPACE: helm-debug
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace helm-debug ...)

Ce que STATUS vous dit :

Status	Signification	Action
deployed	Installation/upgrade réussi	Le problème est côté K8s, pas Helm
failed	Helm a échoué	Voir les hooks, les erreurs de validation
pending-install	Installation en cours	Attendre ou vérifier les timeouts
pending-upgrade	Upgrade en cours	Idem
superseded	Ancienne révision	Normal après un upgrade

Glissez pour voir

helm get : investigation détaillée

helm get récupère les informations stockées par Helm pour une release :

Manifests déployés

helm get manifest demo -n helm-debug

Affiche les manifests tels qu'ils ont été envoyés à Kubernetes. Comparez avec helm template pour voir si le déploiement correspond à ce que vous attendiez.

Values utilisées

# Uniquement les surcharges
helm get values demo -n helm-debug

USER-SUPPLIED VALUES:
null

# Toutes les values (défauts + surcharges)
helm get values demo -n helm-debug --all

COMPUTED VALUES:
affinity: {}
autoscaling:
  enabled: false
  maxReplicas: 100
image:
  pullPolicy: IfNotPresent
  repository: nginx
...

Pourquoi deux commandes ? Pour distinguer ce que vous avez fourni de ce que le chart utilise par défaut. Si vous avez un doute sur une valeur, --all vous montre la valeur finale.

Notes post-install

helm get notes demo -n helm-debug

Ré-affiche les instructions post-installation (commandes port-forward, URL, etc.).

Tout d'un coup

helm get all demo -n helm-debug

Combine status + values + manifest + notes. Utile pour un diagnostic complet.

---

Bonus, Prévisualiser les changements avec helm diff

Les quatre étapes précédentes répondent à « est-ce que ça va marcher ». Il reste la question qui fait peur en production : « qu'est-ce que ça va modifier ». Le plugin helm-diff compare la révision déployée et celle que vous vous apprêtez à pousser, et affiche uniquement les lignes qui changent.

Pourquoi diff ?

Avant un helm upgrade, vous voulez savoir exactement ce qui va changer. Le plugin helm-diff compare l'état actuel avec le nouvel état :

Installation

helm-diff n'est pas livré avec Helm : c'est un plugin externe, installé dans le répertoire de plugins de votre utilisateur et non au niveau système. Il faut donc l'installer sur chaque poste et sur chaque agent de CI qui doit l'utiliser.

helm plugin install https://github.com/databus23/helm-diff

Utilisation

Passez exactement les mêmes arguments que le helm upgrade visé, values et --set compris : un seul écart entre la prévisualisation et la commande réelle rend le diff trompeur.

helm diff upgrade demo ./mon-chart -n helm-debug --set replicaCount=3

helm-debug, demo-mon-chart, Deployment (apps) has changed:
  spec:
   replicas: 1
   replicas: 3

Ce que diff vous montre :

• Les lignes supprimées (préfixe -)
• Les lignes ajoutées (préfixe +)
• Les ressources qui vont être créées/supprimées

Diff avant chaque upgrade en prod

En production, toujours faire un helm diff avant helm upgrade. Un changement involontaire peut avoir des conséquences désastreuses (suppression de PVC, changement de credentials...).

---

Top 5 des erreurs et solutions

Ces cinq messages couvrent l'essentiel des tickets de support Helm. Chacun trahit une étape précise du cycle : rendu des templates, appel à l'API, ou état de l'historique de la release. Identifier l'étape concernée vous donne déjà la moitié de la réponse, parce qu'elle indique où chercher : vos fichiers, votre cluster, ou les Secrets de révision.

1. "cannot re-use a name that is still in use"

Le message tombe côté client, avant toute création de ressource : Helm a trouvé une release portant ce nom dans le namespace.

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

Cause : Vous faites helm install sur une release qui existe déjà.

Solution : Utilisez helm upgrade --install (idempotent) ou un autre nom de release.

helm upgrade --install demo ./mon-chart -n helm-debug

2. "release: not found"

Neuf fois sur dix, la release existe mais dans un autre namespace : sans -n, Helm ne regarde que celui du contexte kubectl courant.

Error: release: not found

Cause : La release n'existe pas dans ce namespace.

Solution : Vérifiez le namespace et le nom de la release.

helm list -A  # Liste toutes les releases dans tous les namespaces

3. "nil pointer evaluating interface {}.xxx"

L'erreur survient au rendu du template, donc avant le moindre appel au cluster : elle se reproduit à l'identique avec helm template, hors ligne.

Error: template: mon-chart/templates/configmap.yaml:4:18:
       nil pointer evaluating interface {}.name

Cause : Un template référence .Values.something.nested mais something n'existe pas.

Solution : Ajouter la valeur dans values.yaml ou utiliser une valeur par défaut :

# Option 1 : Ajouter dans values.yaml
something:
  nested: "valeur"

# Option 2 : Valeur par défaut dans le template
{{ .Values.something.nested | default "fallback" }}

# Option 3 : Condition dans le template
{{- if .Values.something }}
{{ .Values.something.nested }}
{{- end }}

4. "UPGRADE FAILED: another operation in progress"

Helm se fie au statut de la dernière révision : tant qu'elle reste en pending-install ou pending-upgrade, il refuse toute nouvelle opération sur cette release.

Error: UPGRADE FAILED: another operation (install/upgrade/rollback)
       is in progress

Cause : Une opération précédente a été interrompue (Ctrl+C, timeout, crash).

Solution : Attendez quelques minutes ou forcez le rollback :

# Voir l'historique
helm history demo -n helm-debug

# Rollback à la dernière version stable
helm rollback demo 1 -n helm-debug

5. "YAML parse error"

Le rendu Go a réussi, c'est le YAML produit qui est invalide. Attention au numéro de ligne : il désigne le fichier rendu, pas la ligne correspondante dans votre template.

Error: YAML parse error on mon-chart/templates/deployment.yaml:
       error converting YAML to JSON: yaml: line 12: found character that
       cannot start any token

Cause : Erreur de syntaxe YAML (indentation, caractères spéciaux).

Solution : Vérifiez l'indentation et utilisez des quotes pour les valeurs spéciales :

# ❌ Mauvais
env:
  - name: PASSWORD
    value: mon:motdepasse  # : pose problème

# ✅ Bon
env:
  - name: PASSWORD
    value: "mon:motdepasse"  # Quotes = ok

---

Résumé de la méthode de debug

Les cinq contrôles ci-dessous se déroulent du local vers le cluster, et chacun élimine une famille de causes. Arrêtez-vous dès que l'un échoue : corriger ce point rend les suivants inutiles à ce stade. En CI, les deux premiers suffisent à bloquer une merge request fautive sans avoir besoin d'un cluster.

1. helm lint, Syntaxe du chart OK ?

2. helm template, Manifests générés corrects ?

3. helm diff, Changements attendus ?

4. helm install --dry-run, Validation serveur OK ?

5. helm status / helm get, État de la release ?

---

À retenir

Commande	Usage	Sans cluster
helm lint	Valider la syntaxe du chart	✅
helm template	Voir les manifests générés	✅
helm diff upgrade	Prévisualiser les changements	❌
helm install --dry-run	Validation serveur	❌
helm status	État d'une release	❌
helm get manifest	Manifests déployés	❌
helm get values	Values utilisées	❌

Glissez pour voir

Réflexe quotidien

Avant chaque helm upgrade en production :

1. helm diff upgrade ..., Voir ce qui va changer
2. helm upgrade ... --dry-run, Valider côté serveur
3. Seulement ensuite : helm upgrade ...

---

Prochaines étapes

Anatomie d'un chart Comprendre la structure d'un chart Helm

Qualité des charts Valider avec kubeconform et kube-linter

×

📖 Voir la documentation →