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

Quand quelque chose ne fonctionne pas, suivez cet ordre :

É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

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

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

Imaginons un template qui référence une valeur inexistante :

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

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

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

# 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

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

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

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

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 plugin install https://github.com/databus23/helm-diff

Utilisation

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

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

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”

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”

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”

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”

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

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 →