Maîtriser la commande Helm : référence complète

Quand vous déployez des applications sur Kubernetes, vous avez besoin d'installer des charts, de mettre à jour des releases, de revenir en arrière en cas de problème, et de déboguer vos déploiements. helm est le gestionnaire de packages de Kubernetes qui orchestre tout cela en une seule commande.

Ce que vous allez apprendre

Installer et mettre à jour des applications avec helm install et helm upgrade
Gérer le cycle de vie complet : rollback, historique, suppression
Déboguer avec helm template, helm lint et helm get
Gérer les repositories et rechercher des charts
Maîtriser les options essentielles pour la production

La commande `helm` dans l'écosystème Kubernetes

helm fait partie des outils de déploiement Kubernetes. Il ne remplace pas kubectl : il génère les manifests à partir d'un chart (un paquet de templates paramétrables) puis les envoie à l'API du cluster, en gardant la trace de chaque déploiement sous forme de release versionnée. C'est cette mémoire des révisions qui permet le rollback, et c'est ce que les autres outils du tableau ne font pas de la même façon.

Chaque outil a sa spécialité :

Outil	Spécialité	Quand l'utiliser
`helm`	Gérer des packages (charts)	Déploiements reproductibles, versionnés
`kubectl`	Interagir avec l'API K8s	Commandes directes, debug, inspection
`kustomize`	Personnaliser des manifests	Overlays sans templating
`argocd`	GitOps continu	Synchronisation automatique depuis Git
`flux`	GitOps continu	Alternative à ArgoCD

Combinaisons fréquentes :

# helm + kubectl : vérifier le déploiement
helm install myapp ./chart && kubectl get pods -w

# helm template + kubectl diff : prévisualiser les changements
helm template myapp ./chart | kubectl diff -f -

# helm + grep : filtrer les releases
helm list -A | grep -i nginx

Comprendre la commande `helm` en 2 min

Quatre mots reviennent en permanence dans les messages de helm : repository, chart, release et values. Les confondre est la première source d'erreurs, parce que la même commande change de sens selon l'objet qu'on lui passe. Les définitions ci-dessous suffisent pour lire toutes les commandes de cette page.

Syntaxe générale

Toutes les sous-commandes suivent le même ordre : le verbe, puis les arguments positionnels, puis les options. L'ordre des arguments compte, celui des options non.

helm [commande] [arguments] [flags]

Les 5 commandes que vous utiliserez 80% du temps :

Commande	Ce qu'elle fait	Exemple
`helm install`	Déployer un chart	`helm install myapp bitnami/nginx`
`helm upgrade`	Mettre à jour une release	`helm upgrade myapp bitnami/nginx`
`helm list`	Lister les releases	`helm list -n prod`
`helm uninstall`	Supprimer une release	`helm uninstall myapp`
`helm template`	Générer les manifests (debug)	`helm template myapp ./chart`

Les 3 objets clés à comprendre

Un même chart peut être installé plusieurs fois dans le cluster : c'est le nom de release qui distingue les instances, et c'est lui qu'attendent upgrade, rollback et uninstall. Les values ne sont pas stockées dans le chart mais dans la release, ce qui explique qu'un upgrade sans fichier de values puisse effacer votre configuration.

Objet	Question	Exemples
Chart	Quel paquet installer ?	`bitnami/nginx`, `./mon-chart/`
Release	Quel nom donner à l'instance ?	`myapp`, `nginx-prod`
Values	Comment personnaliser ?	`-f values.yaml`, `--set replicas=3`

Installation et déploiement

Trois commandes couvrent le cycle de vie d'une application : install la crée, upgrade la fait évoluer, uninstall la retire. Elles partagent la plupart des options, notamment --namespace, --values et --wait. Retenez surtout que helm install échoue si le nom de release existe déjà dans le namespace, ce qui rend cette commande inutilisable telle quelle dans un pipeline rejoué plusieurs fois.

helm install, Déployer un chart

Le nom de release que vous choisissez ici vous suivra pendant toute la vie de l'application : il sert de clé à toutes les autres commandes et ne peut pas être changé après coup.

helm install <release-name> <chart> [flags]

Options principales :

Option	Description	Exemple
`-n, --namespace`	Namespace cible	`-n production`
`-f, --values`	Fichier de values	`-f values-prod.yaml`
`--set`	Surcharge inline	`--set image.tag=v2.0`
`--create-namespace`	Créer le namespace	`--create-namespace`
`--dry-run`	Simuler sans appliquer	`--dry-run`
`--wait`	Attendre que tout soit prêt	`--wait --timeout 5m`
`--atomic`	Rollback auto si échec	`--atomic`

Formes courantes :

# Depuis un repository
helm install myapp bitnami/nginx

# Depuis un chart local
helm install myapp ./mon-chart/

# Depuis un registry OCI
helm install myapp oci://ghcr.io/org/charts/myapp --version 1.2.3

# Avec personnalisation
helm install myapp bitnami/nginx \
  -n production --create-namespace \
  -f values-prod.yaml \
  --set replicaCount=3

# Mode sécurisé (rollback auto si échec)
helm install myapp ./chart \
  --atomic \
  --timeout 5m \
  --wait

helm upgrade, Mettre à jour une release

Chaque upgrade réussi crée une nouvelle révision dans l'historique de la release, y compris quand rien ne change dans les manifests générés. C'est cet incrément qui rend le rollback possible.

helm upgrade <release-name> <chart> [flags]

Options spécifiques à upgrade :

Option	Description	Exemple
`--install`	Créer si n'existe pas	`--install` (idempotent)
`--reuse-values`	Garder les anciennes values	`--reuse-values`
`--reset-values`	Revenir aux defaults	`--reset-values`
`--force`	Forcer le remplacement	`--force`

Pattern CI/CD (idempotent) :

# Fonctionne que la release existe ou non
helm upgrade --install myapp ./chart \
  -n production \
  -f values-prod.yaml \
  --atomic \
  --wait

helm uninstall, Supprimer une release

L'opération est irréversible : sans --keep-history, l'historique des révisions disparaît avec la release et aucun rollback n'est plus possible. Les volumes persistants créés par un StatefulSet, eux, survivent à la suppression et restent à nettoyer à la main.

helm uninstall <release-name> [flags]

Options :

Option	Description	Exemple
`-n, --namespace`	Namespace de la release	`-n production`
`--keep-history`	Conserver l'historique	`--keep-history`
`--dry-run`	Simuler la suppression	`--dry-run`

# Suppression simple
helm uninstall myapp -n production

# Conserver l'historique (permet rollback ultérieur)
helm uninstall myapp --keep-history

Gestion du cycle de vie

Helm conserve l'état de chaque release dans des Secrets du namespace concerné, un par révision. Les commandes de cette section lisent ces objets : elles répondent à « qu'est-ce qui tourne », « qu'est-ce qui a changé » et « comment revenir en arrière » sans jamais interroger vos fichiers sources. C'est pour cette raison qu'elles fonctionnent même si vous avez perdu le chart d'origine.

helm list, Lister les releases

Sans option de namespace, la commande n'affiche que les releases du namespace courant de votre kubeconfig, souvent default : une release absente de la liste est presque toujours ailleurs, pas disparue.

helm list [flags]

Options de filtrage :

Option	Description	Exemple
`-A, --all-namespaces`	Tous les namespaces	`-A`
`-n, --namespace`	Namespace spécifique	`-n prod`
`-a, --all`	Inclure les releases supprimées	`-a`
`--deployed`	Seulement les déployées	`--deployed`
`--failed`	Seulement les échouées	`--failed`
`-o, --output`	Format de sortie	`-o json`

# Toutes les releases du cluster
helm list -A

# Releases en échec
helm list -A --failed

# Format JSON (scripting)
helm list -n prod -o json | jq '.[].name'

helm history, Historique d'une release

La colonne REVISION fournit le numéro à passer à helm rollback, et le statut superseded désigne simplement une révision remplacée par une plus récente. Notez qu'un rollback ne réécrit pas le passé : il ajoute une révision de plus, comme le montre la ligne 3 ci-dessous.

helm history <release-name> [flags]

# Voir l'historique
helm history myapp -n production

Sortie typique :

REVISION  UPDATED                   STATUS      CHART         APP VERSION  DESCRIPTION
1         Mon Jan 15 10:00:00 2026  superseded  myapp-1.0.0   1.0.0        Install complete
2         Mon Jan 15 11:30:00 2026  superseded  myapp-1.1.0   1.1.0        Upgrade complete
3         Mon Jan 15 14:00:00 2026  deployed    myapp-1.1.0   1.1.0        Rollback to 2

helm rollback, Revenir en arrière

Le numéro de révision est facultatif : omis, il ramène la release à la révision précédente. Le rollback restitue les manifests et les values de la révision visée, mais il ne redescend pas les images vers d'anciens tags si votre chart utilise un tag mouvant comme latest.

helm rollback <release-name> <revision> [flags]

Options :

Option	Description	Exemple
`--force`	Forcer le rollback	`--force`
`--wait`	Attendre la stabilisation	`--wait`
`--timeout`	Délai maximum	`--timeout 5m`

# Rollback à la révision 2
helm rollback myapp 2 -n production

# Rollback avec attente
helm rollback myapp 1 --wait --timeout 3m

Debug et validation

Quand un déploiement se passe mal, la première question à trancher est : le problème vient-il du rendu des templates ou de ce que Kubernetes en fait ensuite ? Les commandes de cette section répondent des deux côtés de la frontière. template et lint travaillent hors ligne sur les sources du chart ; get et status interrogent la release réellement enregistrée dans le cluster.

helm template, Générer les manifests

Cette commande travaille entièrement côté client : elle ne contacte pas l'API Kubernetes, ne crée rien et fonctionne donc sans cluster accessible. Corollaire à connaître, elle ne détecte ni un champ refusé par l'API ni un conflit avec l'existant, sauf si vous ajoutez --validate.

helm template <release-name> <chart> [flags]

La commande la plus importante pour débugger, elle génère les manifests Kubernetes sans les déployer.

# Voir ce que Helm va générer
helm template myapp ./chart -f values.yaml

# Filtrer un type de ressource
helm template myapp ./chart | grep -A 50 "kind: Deployment"

# Sauvegarder pour inspection
helm template myapp ./chart -f values-prod.yaml > manifests.yaml

# Avec validation serveur (dry-run)
helm template myapp ./chart --validate

helm lint, Valider un chart

helm lint vérifie la structure du chart et le rendu des templates avec les values fournies. Par défaut il sort en succès malgré les avertissements : sans --strict, un pipeline de validation laisse donc passer des charts douteux.

helm lint <chart-path> [flags]

# Lint basique
helm lint ./mon-chart

# Mode strict (warnings = erreurs)
helm lint ./mon-chart --strict

# Avec des values spécifiques
helm lint ./mon-chart -f values-test.yaml

Niveaux de messages :

Niveau	Signification	Action
`[INFO]`	Recommandation	Optionnel
`[WARNING]`	Problème potentiel	À investiguer
`[ERROR]`	Erreur bloquante	Doit être corrigée

helm get, Inspecter une release

C'est la commande qui répond à « qu'est-ce qui a réellement été appliqué », par opposition à ce que vos fichiers locaux décrivent aujourd'hui. Un écart entre helm get manifest et helm template signale une release plus ancienne que votre chart de travail.

helm get <subcommand> <release-name> [flags]

Sous-commandes :

Sous-commande	Ce qu'elle retourne	Usage
`manifest`	Manifests déployés	Voir ce qui tourne
`values`	Values utilisées	Comprendre la config
`notes`	Notes post-install	Instructions d'accès
`all`	Tout combiné	Debug complet

# Manifests actuellement déployés
helm get manifest myapp -n production

# Values utilisées (surcharges uniquement)
helm get values myapp -n production

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

# Notes d'installation
helm get notes myapp -n production

helm status, État d'une release

Le statut renvoyé (deployed, failed, pending-upgrade) décrit l'opération Helm, pas la santé applicative : une release deployed dont les pods redémarrent en boucle reste deployed. Un statut pending-upgrade qui ne bouge plus trahit une opération interrompue et bloque les suivantes.

helm status <release-name> [flags]

# État actuel
helm status myapp -n production

# Format JSON (scripting)
helm status myapp -o json | jq '.info.status'

Gestion des repositories

Un repository Helm n'est qu'un serveur HTTP exposant un fichier index.yaml qui recense les charts et leurs versions. Helm en garde une copie locale dans votre profil utilisateur, et toutes les recherches portent sur cette copie. Ces commandes servent à déclarer les sources, à rafraîchir ce cache et à inspecter un chart avant de l'installer.

helm repo, Gérer les sources de charts

Les repositories sont propres à votre poste : ils vivent dans votre configuration Helm locale, pas dans le cluster. Un agent de CI qui ne les déclare pas échouera sur un chart pourtant disponible depuis votre machine.

helm repo <subcommand> [flags]

Sous-commandes :

Sous-commande	Ce qu'elle fait	Exemple
`add`	Ajouter un repo	`helm repo add bitnami https://...`
`list`	Lister les repos	`helm repo list`
`update`	Mettre à jour l'index	`helm repo update`
`remove`	Supprimer un repo	`helm repo remove bitnami`

# Ajouter les repos essentiels
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

# Mettre à jour l'index local
helm repo update

# Lister les repos configurés
helm repo list

helm search, Rechercher des charts

helm search repo lit uniquement l'index local : si la version que vous attendez n'apparaît pas, lancez d'abord helm repo update. Par défaut la recherche masque les versions de développement, --devel les fait apparaître.

helm search <subcommand> <keyword> [flags]

Deux modes de recherche :

Mode	Ce qu'il cherche	Exemple
`repo`	Dans vos repos locaux	`helm search repo nginx`
`hub`	Sur Artifact Hub	`helm search hub postgresql`

# Dans les repos configurés
helm search repo nginx

# Toutes les versions disponibles
helm search repo nginx --versions

# Sur Artifact Hub (internet)
helm search hub postgresql --max-col-width 50

helm show, Inspecter un chart

helm show values est le seul moyen fiable de connaître les clés réellement acceptées par un chart avant de rédiger votre fichier de values : une clé mal orthographiée est ignorée en silence, sans erreur.

helm show <subcommand> <chart> [flags]

Sous-commandes :

Sous-commande	Ce qu'elle montre	Exemple
`chart`	Métadonnées (Chart.yaml)	`helm show chart bitnami/nginx`
`values`	Values par défaut	`helm show values bitnami/nginx`
`readme`	Documentation	`helm show readme bitnami/nginx`
`all`	Tout	`helm show all bitnami/nginx`

# Voir les values par défaut AVANT d'installer
helm show values bitnami/nginx > nginx-defaults.yaml

# Vérifier la version de l'application
helm show chart bitnami/nginx | grep appVersion

Packaging et distribution

Distribuer un chart maison suppose trois étapes : l'archiver, le publier, puis permettre à d'autres de le récupérer. Depuis Helm 3.8, le format de distribution recommandé est le registry OCI, celui-là même qui héberge vos images de conteneurs : un seul registre, une seule authentification, les mêmes règles d'accès.

helm package, Créer un package

L'archive produite s'appelle nom-version.tgz d'après les champs name et version du Chart.yaml : c'est ce fichier Chart.yaml qui fait foi, pas le nom du dossier. Sans -d, l'archive atterrit dans le répertoire courant.

helm package <chart-path> [flags]

# Packager un chart
helm package ./mon-chart

# Avec une version spécifique
helm package ./mon-chart --version 1.2.3

# Dans un dossier spécifique
helm package ./mon-chart -d ./releases/

helm push, Publier sur un registry OCI

La commande attend une archive .tgz déjà construite, jamais un dossier de chart : helm package est donc un préalable obligatoire. L'URL de destination désigne le dépôt parent, Helm y ajoute lui-même le nom et la version du chart.

helm push <chart.tgz> <registry-url>

# Login au registry
helm registry login ghcr.io

# Push du chart
helm push mon-chart-1.2.3.tgz oci://ghcr.io/myorg/charts

helm pull, Télécharger un chart

Récupérer le chart en local est le réflexe utile pour auditer ce qu'un éditeur va déployer chez vous, ou pour figer une version dans votre propre dépôt Git. Sans --version, Helm prend la dernière version stable publiée.

helm pull <chart> [flags]

# Télécharger le .tgz
helm pull bitnami/nginx

# Télécharger et extraire
helm pull bitnami/nginx --untar

# Version spécifique
helm pull bitnami/nginx --version 15.0.0 --untar

Patterns courants

Les cinq combinaisons ci-dessous couvrent l'essentiel du travail quotidien avec Helm : déployer sans intervention humaine, vérifier avant d'agir, comprendre un échec, revenir en arrière et gérer plusieurs environnements. Chacune assemble des commandes déjà décrites, l'intérêt est dans l'ordre et dans le choix des options.

Pattern 1, Déploiement CI/CD idempotent

Un pipeline doit produire le même résultat qu'il tourne pour la première ou la centième fois, et ne jamais laisser une release à moitié appliquée derrière lui. Les quatre options ci-dessous sont exactement là pour ça.

helm upgrade --install myapp ./chart \
  -n production \
  --create-namespace \
  -f values-prod.yaml \
  --atomic \
  --wait \
  --timeout 5m

Pourquoi ce pattern ?

--install : crée si n'existe pas (idempotent)
--atomic : rollback auto si échec
--wait : attend que les pods soient Ready
--timeout : évite les blocages infinis

Pattern 2, Prévisualiser avant upgrade

Comparer l'état déployé et l'état à venir évite les mauvaises surprises sur une ressource sensible comme un Service ou un PersistentVolumeClaim. helm diff est un plugin à installer séparément ; la seconde forme s'appuie uniquement sur kubectl et fonctionne partout.

# Voir les changements
helm diff upgrade myapp ./chart -f values.yaml

# Ou sans le plugin diff
helm template myapp ./chart -f values.yaml | kubectl diff -f -

Pattern 3, Debug d'installation échouée

L'ordre des quatre étapes n'est pas arbitraire : il remonte du plus local au plus distant, de la syntaxe du chart jusqu'aux événements du cluster. Arrêtez-vous dès qu'une étape échoue, les suivantes ne feront que répéter le même symptôme.

# 1. Lint le chart
helm lint ./chart --strict

# 2. Vérifier les manifests générés
helm template myapp ./chart -f values.yaml > /tmp/manifests.yaml

# 3. Valider contre le cluster
helm install myapp ./chart --dry-run --debug

# 4. Si déjà installé, inspecter
helm status myapp
helm get manifest myapp
kubectl get events -n production --sort-by='.lastTimestamp'

Pattern 4, Rollback d'urgence

En incident, la tentation est de relancer un upgrade corrigé ; le rollback est plus sûr parce qu'il restitue une combinaison de manifests et de values déjà éprouvée en production. Dans helm history, la révision à viser est la plus récente marquée superseded : elle a été déployée avec succès avant d'être remplacée, contrairement à celles marquées failed.

# Voir l'historique
helm history myapp -n production

# Rollback à la dernière version stable
helm rollback myapp <revision> -n production --wait

# Vérifier
helm status myapp -n production
kubectl get pods -n production

Pattern 5, Multi-environnements

Les fichiers de values s'empilent dans l'ordre où vous les passez : le dernier -f gagne clé par clé. Un fichier de base commun suivi d'un fichier par environnement évite ainsi de dupliquer la configuration partagée tout en gardant les écarts visibles dans Git.

# Dev
helm upgrade --install myapp ./chart \
  -n dev -f values-base.yaml -f values-dev.yaml

# Staging
helm upgrade --install myapp ./chart \
  -n staging -f values-base.yaml -f values-staging.yaml

# Production
helm upgrade --install myapp ./chart \
  -n production -f values-base.yaml -f values-prod.yaml \
  --atomic --wait

Pièges courants

La plupart des messages d'erreur de Helm désignent un symptôme, pas la cause. Deux d'entre eux méritent une attention particulière : another operation in progress révèle une release restée en statut pending, qu'il faut débloquer avant toute autre commande ; les values non appliquées ne produisent aucune erreur du tout, seulement un déploiement qui ne ressemble pas à ce que vous attendiez.

Erreur	Cause	Solution
`cannot re-use a name`	Release existe déjà	Utiliser `helm upgrade --install`
`release not found`	Mauvais namespace	Ajouter `-n namespace`
`UPGRADE FAILED: another operation in progress`	Opération interrompue	`helm rollback` ou attendre
Values non appliquées	`--reuse-values` utilisé	Fournir explicitement `-f values.yaml`
`nil pointer evaluating`	Value manquante dans template	Ajouter valeur ou `default` dans template
Timeout dépassé	Pods ne démarrent pas	Vérifier `kubectl describe pod`

Cheatsheet

Ce récapitulatif reprend les commandes du guide sous une forme copiable. Toutes portent un -n explicite : sans lui, Helm travaille sur le namespace courant du kubeconfig, ce qui est la source d'erreur la plus fréquente quand on jongle entre plusieurs environnements.

Déploiement

upgrade --install couvre à lui seul les deux premiers cas et reste la forme à privilégier dans un script, puisqu'il ne présuppose pas l'état de départ.

helm install myapp ./chart -n prod -f values.yaml       # Installer
helm upgrade --install myapp ./chart -n prod -f values.yaml  # Install/upgrade idempotent
helm upgrade myapp ./chart -n prod -f values.yaml       # Mettre à jour
helm uninstall myapp -n prod                            # Supprimer

Inspection

Ces cinq commandes ne modifient rien : elles sont sans risque, y compris en production, et constituent le bon point de départ avant toute intervention.

helm list -A                          # Toutes les releases
helm status myapp -n prod             # État d'une release
helm history myapp -n prod            # Historique
helm get values myapp -n prod --all   # Values utilisées
helm get manifest myapp -n prod       # Manifests déployés

Debug

Les deux premières lignes s'exécutent sans cluster ; la troisième, avec --dry-run, soumet les manifests à l'API pour validation et --debug affiche en plus les values calculées.

helm lint ./chart --strict            # Valider le chart
helm template myapp ./chart -f values.yaml  # Générer manifests
helm install myapp ./chart --dry-run --debug  # Simuler avec debug

Repositories

Cette séquence est celle à rejouer sur toute nouvelle machine ou tout nouvel agent de CI, puisque les repositories sont stockés localement et non dans le cluster.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm search repo nginx
helm show values bitnami/nginx > defaults.yaml

Rollback

Consultez toujours l'historique avant de choisir un numéro : helm rollback accepte n'importe quelle révision existante, y compris une révision qui avait échoué.

helm history myapp -n prod            # Voir les révisions
helm rollback myapp 2 -n prod --wait  # Revenir à la révision 2

À retenir

Commande	Usage principal
`helm upgrade --install`	Déploiement CI/CD idempotent
`helm template`	Débugger les manifests générés
`helm lint --strict`	Valider un chart avant déploiement
`helm get values --all`	Comprendre la config d'une release
`helm rollback`	Revenir en arrière en cas de problème
`helm diff upgrade`	Prévisualiser les changements (plugin)

Prochaines étapes

Formation Helm complète 12 modules progressifs avec labs pratiques

Déboguer Helm Méthode de triage et résolution d'erreurs

Values et personnalisation Maîtriser -f et --set pour multi-environnements

CI/CD avec Helm Automatiser packaging et promotion

Maîtriser la commande Helm : référence complète

Ce que vous allez apprendre

La commande helm dans l'écosystème Kubernetes

Comprendre la commande helm en 2 min

Syntaxe générale

Les 3 objets clés à comprendre

Installation et déploiement

helm install, Déployer un chart

helm upgrade, Mettre à jour une release

helm uninstall, Supprimer une release

Gestion du cycle de vie

helm list, Lister les releases

helm history, Historique d'une release

helm rollback, Revenir en arrière

Debug et validation

helm template, Générer les manifests

helm lint, Valider un chart

helm get, Inspecter une release

helm status, État d'une release

Gestion des repositories

helm repo, Gérer les sources de charts

helm search, Rechercher des charts

helm show, Inspecter un chart

Packaging et distribution

helm package, Créer un package

helm push, Publier sur un registry OCI

helm pull, Télécharger un chart

Patterns courants

Pattern 1, Déploiement CI/CD idempotent

Pattern 2, Prévisualiser avant upgrade

Pattern 3, Debug d'installation échouée

Pattern 4, Rollback d'urgence

Pattern 5, Multi-environnements

Pièges courants

Cheatsheet

Déploiement

Inspection

Debug

Repositories

Rollback

À retenir

Prochaines étapes

La commande `helm` dans l'écosystème Kubernetes

Comprendre la commande `helm` en 2 min