Aller au contenu
English
English
Conteneurs & Orchestration medium

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

60 min de lecture

logo helm

Quand un déploiement Helm échoue, le message d'erreur ne dit pas toujours ce qui s'est passé. Ce guide vous donne une méthode systématique de diagnostic : valider le chart lui-même, inspecter ce qu'il génère, puis analyser l'état de la release. En 20 minutes, vous saurez dire 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
  • Helm v4.3 installé, la version sur laquelle ce guide est mesuré
  • Un chart à déboguer (ou créez-en un avec helm create mon-chart)
  • Un cluster Kubernetes (optionnel pour les premières é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.

ÉtapeCommandeCe qu'on vérifieSans cluster ?
1helm lintSyntaxe du chart✅ Oui
2helm templateManifests générés✅ Oui
3helm install --dry-runValidation côté serveur❌ Non
4helm status / helm getÉtat de la release❌ Non

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.


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 coûtent le plus cher quand elles remontent depuis un pipeline. Tant qu'il échoue, tester la suite ne sert à rien : Helm n'a même pas de manifestes à envoyer.

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.)

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.

Fenêtre de terminal
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 :

NiveauSignificationAction
[INFO]Recommandation (non bloquant)Optionnel à corriger
[WARNING]Problème potentielÀ investiguer
[ERROR]Erreur bloquanteDoit être corrigée

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
Fenêtre de terminal
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" }}

--strict fait échouer le lint sur les [WARNING], et sur eux seuls. L'aide du binaire est explicite, « fail on lint warnings », et les [INFO] ne basculent pas : un chart sans icon reste en succès avec ou sans le drapeau. Retenez la hiérarchie, elle décide de ce que votre chaîne d'intégration bloque.

Fenêtre de terminal
helm lint ./mon-chart --strict
NiveauExemple mesuréSans --strictAvec --strict
[INFO]Chart.yaml: icon is recommendedcode 0code 0
[WARNING]extensions/v1beta1 Deployment is deprecatedcode 0code 1
[ERROR]name absent du Chart.yamlcode 1code 1

La ligne du milieu est celle qui compte : un avertissement ne bloque rien par défaut. Un chart qui déploie une apiVersion retirée depuis Kubernetes 1.16 passe donc un helm lint ordinaire en succès, et n'échouera qu'au moment de l'installation, quand l'API server refusera le manifeste.

Quand utiliser --strict ? En intégration continue, pour que ces avertissements arrêtent la chaîne au lieu de défiler. En développement local, le mode normal suffit. Notez au passage --kube-version, qui indique à quelle version de Kubernetes les contrôles de dépréciation doivent se référer.


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 }}.

helm template génère les manifestes Kubernetes exactement comme ils seront envoyés au cluster, mais sans les déployer. C'est l'outil principal pour comprendre ce que Helm fait réellement, par opposition à ce que vous croyez qu'il fait.

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

Fenêtre de terminal
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émentQuestion à se poser
Noms des ressourcesEst-ce que my-release-mon-chart est cohérent ?
LabelsLes labels app.kubernetes.io/* sont-ils présents ?
Values injectéesEst-ce que replicas: 1 correspond à ce que je voulais ?
Ressources généréesEst-ce qu'il manque un Service ? Un ConfigMap ?

L'ordre de priorité est fixe : les valeurs par défaut du values.yaml 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.

Fenêtre de terminal
# 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.

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

Fenêtre de terminal
# 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")'

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

Fenêtre de terminal
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).


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

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.

Précisez toujours le namespace avec -n : la validation s'effectue dans son contexte, et un même manifeste peut passer dans l'un et être refusé dans l'autre, quotas et politiques d'admission différant.

Fenêtre de terminal
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 :

Aspecthelm templatehelm 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

Helm propose deux modes de dry-run :

Fenêtre de terminal
# 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.


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 manifestes et les values de chaque révision, ce qui permet de comparer ce qui a été envoyé avec ce que vous croyiez envoyer.

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

Fenêtre de terminal
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 :

StatusSignificationAction
deployedInstallation/upgrade réussiLe problème est côté K8s, pas Helm
failedHelm a échouéVoir les hooks, les erreurs de validation
pending-installInstallation en coursAttendre ou vérifier les timeouts
pending-upgradeUpgrade en coursIdem
supersededAncienne révisionNormal après un upgrade

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

Fenêtre de terminal
helm get manifest demo -n helm-debug

Affiche les manifestes tels qu'ils ont été envoyés à Kubernetes. Comparez-les avec la sortie de helm template : un écart entre les deux signale que le chart a changé depuis le dernier déploiement.


Bonus, Prévisualiser les changements avec helm diff

Section intitulée « 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 n'affiche que les lignes qui changent.

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

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 d'intégration continue qui doit l'utiliser.

Helm v4 refuse par défaut d'installer un plugin non signé. La commande directe s'arrête sur :

Error: plugin source does not support verification. Use --verify=false to skip verification

Ce n'est pas un bug : --verify vaut true par défaut depuis Helm v4, qui cherche une signature de provenance avant d'installer. La quasi-totalité des plugins de l'écosystème, helm-diff compris, n'en publient pas encore. Il faut donc lever explicitement le contrôle :

Fenêtre de terminal
helm plugin install https://github.com/databus23/helm-diff --verify=false

Écrire --verify=false, c'est déclarer qu'on fait confiance à ce dépôt. Un plugin s'exécute avec vos droits et voit passer vos manifestes : traitez cette ligne comme l'ajout d'une dépendance, pas comme une formalité pour faire taire un message. Vérifiez le dépôt, sa fréquence de publication et le nombre de ses mainteneurs avant de la taper.

Une fois installé, helm plugin list rend compte de ce qui a été contrôlé :

NAME VERSION TYPE APIVERSION PROVENANCE SOURCE
diff 3.15.13 cli/v1 legacy unknown unknown

Les colonnes PROVENANCE et SOURCE à unknown sont la trace du contrôle contourné, et APIVERSION: legacy signale un plugin écrit pour l'ancien format. Un parc de CI se relit avec cette commande.

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.

Fenêtre de terminal
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

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

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: release name check failed: cannot reuse 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.

Fenêtre de terminal
helm upgrade --install demo ./mon-chart -n helm-debug

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.

Fenêtre de terminal
helm list -A # Liste toutes les releases dans tous les namespaces

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"

Section intitulée « 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 :

Fenêtre de terminal
# Voir l'historique
helm history demo -n helm-debug
# Rollback à la dernière version stable
helm rollback demo 1 -n helm-debug

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

En incident, personne ne déroule une méthode en quatre étapes : on a un message d'erreur et il faut savoir où regarder tout de suite. Ce tableau prend le problème par ce bout, et va au-delà des cinq classiques ci-dessus. Chaque ligne indique la cause la plus probable et la commande qui tranche, celle qui confirme ou élimine l'hypothèse en une seule exécution.

SymptômeCause la plus probableLa commande qui tranche
cannot reuse a name that is still in useune release du même nom existe déjàhelm list -n <ns>
another operation ... is in progressopération interrompue, statut pending-upgradehelm history <rel> -n <ns>
Révision failed, précédente deployedupgrade échoué, l'application n'a pas bougéhelm history <rel> -n <ns>
pre-upgrade hooks failed: ... Job Failedun Job de hook est sorti en erreurkubectl logs -n <ns> job/<nom>
Un Job de hook reste après couppas de hook-delete-policy sur ce hookkubectl get job -n <ns>
invalid ownership metadatala ressource existe déjà hors de cette releasekubectl get <res> -n <ns> -o yaml
server-side apply failed ... field is immutablechamp non modifiable après créationhelm diff upgrade, puis recréation assumée
no matches for kind ... l'API a disparu du clusterhelm get manifest <rel> -n <ns>
... is forbidden: User ... cannot get resourcedroits RBAC insuffisants sur un typekubectl auth can-i <verbe> <type> --as <user>
Ressource encore là après uninstallCRD, namespace ou objet hors releasekubectl get crd, kubectl get all -n <ns>
Surcharge --set sans effet, aucune erreurclé absente du chart, donc ignoréehelm get values <rel> -n <ns>
Bloc absent en local, présent après installlookup ou .Capabilities dans le charthelm install --dry-run=server

Les trois situations qui suivent méritent un développement : elles piègent même les habitués, parce que le message affiché désigne autre chose que la vraie cause. Dans les trois cas, le réflexe naturel envoie chercher au mauvais endroit, et c'est ce détour qui coûte le plus de temps en incident.

Pourquoi une release reste bloquée quand une API disparaît

Section intitulée « Pourquoi une release reste bloquée quand une API disparaît »

Supprimer une CRD alors qu'une release en déploie une instance verrouille cette release dans les trois sens. Helm continue d'afficher deployed, ce qui donne un faux sentiment de normalité, mais upgrade, rollback et uninstall échouent tous les trois, puisque chacun commence par relire le manifeste stocké et par le traduire en objets Kubernetes. Sans l'API correspondante, cette traduction est impossible.

helm upgrade Error: UPGRADE FAILED: resource mapping not found for name: "gad-g"
... no matches for kind "Gadget" in version "demo.local/v1"
helm rollback Error: unable to build kubernetes objects from current release manifest:
resource mapping not found ...
helm uninstall Error: failed to delete release: gad

Notez la dernière ligne : uninstall renvoie un message laconique, sans mentionner l'API manquante. Pris isolément, il oriente vers un problème de suppression alors que la cause est identique aux deux autres. Seul helm get manifest répond encore, parce qu'il se contente de relire le Secret de révision sans rien interpréter. La sortie de crise consiste à réinstaller la CRD le temps de désinstaller proprement la release.

Pourquoi une surcharge peut n'avoir aucun effet, sans la moindre erreur

Section intitulée « Pourquoi une surcharge peut n'avoir aucun effet, sans la moindre erreur »

Une clé --set que le chart n'utilise pas est acceptée en silence. Helm l'ajoute à l'arbre des values, la release passe en deployed, et rien n'indique que le template ne l'a jamais lue. C'est le seul cas de ce tableau où aucun message n'apparaît, et donc le plus long à diagnostiquer : on cherche une erreur qui n'existe pas.

Fenêtre de terminal
helm upgrade demo ./app -n demo --set replicaZ=42 # STATUS: deployed, aucune alerte
helm get values demo -n demo # replicaZ: 42 ... et pourtant
kubectl get deploy demo-web -n demo -o jsonpath='{.spec.replicas}' # 1

La valeur figure bien dans les values de la release, ce qui achève de convaincre qu'elle a été prise en compte. Le réflexe qui tranche est de comparer helm get values avec la clé réellement lue par le template. La parade durable est un values.schema.json avec additionalProperties: false : la faute de frappe devient alors une erreur bloquante au lieu d'un silence.

Pourquoi un refus RBAC tombe avant la première création

Section intitulée « Pourquoi un refus RBAC tombe avant la première création »

Helm a besoin de lire avant d'écrire, et le refus arrive donc sur un get, pas sur le create attendu. Un compte autorisé à créer des Deployments mais pas à les lire échouerait quand même : avant toute création, Helm interroge le cluster pour savoir si la ressource existe déjà.

Error: INSTALLATION FAILED: unable to continue with install: could not get
information about the resource Deployment "essai-web" in namespace "demo":
deployments.apps "essai-web" is forbidden: User "system:serviceaccount:demo:bride"
cannot get resource "deployments" in API group "apps" in the namespace "demo"

Le point important pour le diagnostic : helm template a rendu le manifeste sans broncher, puisqu'il ne parle à personne. Un rendu correct ne dit donc rien des droits. helm install --dry-run=server donne exactement le même message que l'installation réelle : c'est le bon contrôle à jouer en amont, et --kube-as-user permet de l'exécuter sous l'identité du compte de service plutôt que sous la vôtre.


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 intégration continue, les deux premiers suffisent à bloquer une demande de fusion fautive sans aucun 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 ?


CommandeUsageSans cluster
helm lintValider la syntaxe du chart✅
helm templateVoir les manifests générés✅
helm diff upgradePrévisualiser les changements❌
helm install --dry-runValidation serveur❌
helm statusÉtat d'une release❌
helm get manifestManifests déployés❌
helm get valuesValues utilisées❌

Six questions sur la méthode de diagnostic : ce que lint rend vraiment, la différence entre les deux modes de --dry-run, et pourquoi Helm v4 refuse d'installer un plugin non signé.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

8 questions
5 min.
80% requis

Informations

  • Le chronomètre démarre au clic sur Démarrer
  • Questions à choix multiples, vrai/faux et réponses courtes
  • Vous pouvez naviguer entre les questions
  • Les résultats détaillés sont affichés à la fin

Lance le quiz et démarre le chronomètre

Ce site vous est utile ?

Sachez que moins de 1% des lecteurs soutiennent ce site.

Je maintiens ce site gratuitement, sans publicité, sans profilage et sans compte à créer. Un soutien, même symbolique, m'aide à couvrir l'hébergement et à garder ces ressources gratuites. Merci pour votre appui.

Le formulaire ne s'affiche pas ? Ouvrir Ko-fi dans un onglet.

Abonnez-vous et suivez mon actualité DevSecOps sur LinkedIn