Helm install : déployer et gérer vos releases

Ce guide vous apprend à déployer des applications sur Kubernetes avec helm install et à gérer leur cycle de vie complet : mises à jour, rollbacks et suppression. Vous allez comprendre ce qu'est une release, comment Helm stocke son historique, et surtout comment lire et interpréter chaque ligne de sortie des commandes Helm. En 20 minutes, vous saurez déployer, mettre à jour et dépanner vos applications.

Ce que vous allez apprendre

• Distinguer un chart d'une release, et comprendre où Helm conserve son historique.
• Installer une application et lire chaque ligne de la sortie de helm install.
• Mettre à jour une release avec helm upgrade, en sachant ce que --reuse-values conserve.
• Revenir en arrière avec helm rollback en s'appuyant sur helm history.
• Supprimer une release en identifiant ce qui lui survit, PVC et CRD compris.
• Simuler un déploiement avec --dry-run avant de toucher au cluster.

Prérequis

• Helm installé et au moins un repo configuré (voir module H1-02)
• Un cluster Kubernetes fonctionnel (minikube, kind, k3d ou distant)
• kubectl configuré et connecté au cluster

Vérifiez votre environnement :

# Vérifier la connexion au cluster
kubectl cluster-info

# Vérifier que Helm communique avec le cluster
helm list --all-namespaces

Comprendre les releases Helm

Helm ne se contente pas d'appliquer des manifests : il garde la mémoire de ce qu'il a déployé. Cette mémoire, c'est la release, l'objet qui relie un chart, les valeurs utilisées et l'état obtenu sur le cluster. Comprendre où elle est stockée et comment elle évolue explique la quasi-totalité du comportement de Helm, y compris ses messages d'erreur.

Qu'est-ce qu'une release ?

Une release est une instance déployée d'un chart Helm. Chaque release possède :

• Un nom unique dans le namespace (choisi par vous)
• Un numéro de révision (commence à 1, incrémenté à chaque upgrade)
• Un statut (deployed, failed, pending-install, etc.)
• Un historique des révisions précédentes (pour les rollbacks)

Release ≠ Chart

• Chart = le package versionné, avec ses templates et ses values par défaut
• Release = l'instance déployée dans un namespace, avec les values réellement appliquées et son numéro de révision

Vous pouvez déployer le même chart plusieurs fois avec des noms de release différents, par exemple prometheus-prod et prometheus-staging à partir du même chart prometheus-community/prometheus.

Où Helm stocke-t-il les releases ?

Helm stocke les métadonnées des releases directement dans Kubernetes, sous forme de Secrets dans le namespace de la release :

kubectl get secrets -n helm-demo -l "owner=helm"

NAME                          TYPE                 DATA   AGE
sh.helm.release.v1.podinfo.v1   helm.sh/release.v1   1      5m
sh.helm.release.v1.podinfo.v2   helm.sh/release.v1   1      2m

Chaque Secret sh.helm.release.v1.<release>.<revision> contient l'état complet de cette révision : les values utilisées, le manifeste généré, les métadonnées.

Installer une application

L'installation transforme un chart en objets Kubernetes réels. Helm calcule les manifests à partir des templates et des values, les envoie à l'API server, puis enregistre le tout dans une nouvelle release en révision 1. Tant que cette étape n'est pas comprise, les commandes suivantes (upgrade, rollback) restent opaques.

Syntaxe de base

Deux arguments seulement sont obligatoires : le nom que vous donnez à la release et la référence du chart à déployer.

helm install <nom-release> <chart> [options]

• nom-release : identifiant unique de votre choix (ex: my-app, prometheus-prod)
• chart : référence du chart (repo/chart ou chemin local)

Premier déploiement

Préparons un namespace de test et déployons une application :

# Créer un namespace dédié
kubectl create namespace helm-demo

# Installer kube-state-metrics depuis prometheus-community
helm install my-metrics prometheus-community/kube-state-metrics --namespace helm-demo

Résultat :

NAME: my-metrics
LAST DEPLOYED: Sun Feb  1 17:48:21 2026
NAMESPACE: helm-demo
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
kube-state-metrics is a simple service that listens to the Kubernetes API server and generates metrics about the state of the objects.
The exposed metrics can be found here:
https://github.com/kubernetes/kube-state-metrics/blob/master/docs/README.md#exposed-metrics

The metrics are exported on the HTTP endpoint /metrics on the listening port.
In your case, my-metrics-kube-state-metrics.helm-demo.svc.cluster.local:8080/metrics

They are served either as plaintext or protobuf depending on the Accept header.
They are designed to be consumed either by Prometheus itself or by a scraper that is compatible with scraping a Prometheus client endpoint.

Comprendre la sortie de helm install (crucial !)

Chaque ligne de la sortie vous donne une information importante. Décortiquons :

Ligne	Signification	À retenir
NAME: my-metrics	Nom de la release que vous avez choisi	C'est l'identifiant pour toutes les commandes futures (helm upgrade my-metrics, helm uninstall my-metrics)
LAST DEPLOYED: Sun Feb 1 17:48:21 2026	Horodatage du déploiement	Utile pour le debugging ("quand a été déployée cette version ?")
NAMESPACE: helm-demo	Namespace Kubernetes cible	Tous les objets créés (Pods, Services, etc.) sont dans ce namespace
STATUS: deployed	État actuel de la release	deployed = succès. Autres valeurs possibles : failed, pending-install, pending-upgrade
REVISION: 1	Numéro de version de la release	Commence à 1, s'incrémente à chaque helm upgrade. Utilisé pour les rollbacks
TEST SUITE: None	Résultat des tests Helm (si définis)	Certains charts incluent des tests de validation post-installation
NOTES:	Instructions post-installation	Lisez toujours cette section ! Elle contient les informations spécifiques au chart

Glissez pour voir

Les NOTES sont essentielles

La section NOTES: est générée par le chart et contient des informations critiques :

• Comment accéder à l'application (URL, port-forward, Ingress)
• Credentials par défaut (si applicable)
• Commandes de vérification à exécuter
• Configuration additionnelle recommandée

Dans notre exemple, les NOTES nous indiquent :

1. Ce que fait kube-state-metrics (expose des métriques Kubernetes)
2. L'URL interne du service : my-metrics-kube-state-metrics.helm-demo.svc.cluster.local:8080/metrics
3. Le format des métriques (Prometheus-compatible)

Les différents statuts de release

Le statut est la première chose à regarder quand quelque chose ne va pas. Les statuts pending-* signalent une opération interrompue, souvent parce que le client Helm a été coupé en cours de route : la release reste alors bloquée dans cet état jusqu'à intervention. Le statut superseded n'est pas une anomalie, il désigne simplement une révision remplacée par une plus récente.

Statut	Signification	Action
deployed	Installation réussie, ressources créées	✅ Tout va bien
failed	Installation échouée	Vérifier les logs, corriger, réessayer
pending-install	Installation en cours	Attendre ou investiguer si bloqué
pending-upgrade	Mise à jour en cours	Attendre
pending-rollback	Rollback en cours	Attendre
superseded	Ancienne révision remplacée	Normal après un upgrade
uninstalling	Suppression en cours	Attendre

Glissez pour voir

Vérifier le déploiement

Après un helm install, vérifiez que les ressources Kubernetes sont bien créées :

# Voir les ressources créées par la release
kubectl get all -n helm-demo -l "app.kubernetes.io/instance=my-metrics"

NAME                                                 READY   STATUS    RESTARTS   AGE
pod/my-metrics-kube-state-metrics-7b8d5c4f87-xj2kp   1/1     Running   0          2m

NAME                                    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/my-metrics-kube-state-metrics   ClusterIP   10.96.xxx.xxx   <none>        8080/TCP   2m

NAME                                            READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/my-metrics-kube-state-metrics   1/1     1            1           2m

Lister les releases

helm list interroge les Secrets de release, pas les objets déployés : vous voyez ce que Helm croit avoir installé. La commande est limitée à un namespace par défaut, celui du contexte courant, ce qui explique la plupart des « release not found » signalés par les débutants.

Voir les releases du namespace courant

Sans filtre supplémentaire, la sortie ne montre que les releases dans l'état deployed ou failed.

helm list -n helm-demo

NAME        NAMESPACE   REVISION    UPDATED                                 STATUS      CHART                       APP VERSION
my-metrics  helm-demo   1           2026-02-01 17:48:21.123456789 +0100 CET deployed    kube-state-metrics-5.27.0   2.14.0

Lecture du tableau :

Colonne	Signification
NAME	Nom de la release
NAMESPACE	Namespace Kubernetes
REVISION	Numéro de révision actuel
UPDATED	Date/heure de la dernière modification
STATUS	État actuel
CHART	Nom et version du chart
APP VERSION	Version de l'application déployée

Glissez pour voir

Voir toutes les releases (tous namespaces)

C'est la commande d'inventaire, celle qui répond à « qu'est-ce qui a été installé sur ce cluster ». Elle suppose un accès en lecture sur l'ensemble des namespaces.

helm list --all-namespaces
# ou
helm list -A

Filtrer par statut

Ces filtres servent surtout au diagnostic : une release restée pending plusieurs minutes après une opération indique presque toujours une commande interrompue.

# Voir les releases en échec
helm list --failed

# Voir les releases en cours de déploiement
helm list --pending

Mettre à jour une release

Une mise à jour ne remplace pas la release, elle en ajoute une révision. Helm compare l'état enregistré à l'état demandé et n'envoie au cluster que ce qui diffère. Chaque upgrade réussi incrémente le numéro de révision et fait passer la précédente en superseded, ce qui rend le retour arrière possible à tout moment.

helm upgrade

La commande helm upgrade met à jour une release existante :

# Mettre à jour vers la dernière version du chart
helm upgrade my-metrics prometheus-community/kube-state-metrics -n helm-demo

# Mettre à jour vers une version spécifique
helm upgrade my-metrics prometheus-community/kube-state-metrics --version 5.26.0 -n helm-demo

# Mettre à jour avec de nouvelles values
helm upgrade my-metrics prometheus-community/kube-state-metrics -n helm-demo --set replicas=2

Résultat :

Release "my-metrics" has been upgraded. Happy Helming!
NAME: my-metrics
LAST DEPLOYED: Sun Feb  1 18:15:42 2026
NAMESPACE: helm-demo
STATUS: deployed
REVISION: 2
...

Notez que REVISION est passé de 1 à 2.

install --upgrade (idempotent)

Pour les scripts CI/CD, utilisez --install avec upgrade pour une commande idempotente :

# Installe si n'existe pas, upgrade si existe
helm upgrade --install my-metrics prometheus-community/kube-state-metrics -n helm-demo

Bonne pratique CI/CD

En CI/CD, utilisez toujours helm upgrade --install plutôt que helm install. Cela rend votre pipeline idempotent : il fonctionne que la release existe déjà ou non.

Voir l'historique et rollback

L'historique est la contrepartie utile du stockage en Secrets : chaque révision conserve ses values et son manifeste complet, donc Helm sait reconstruire n'importe quel état passé sans avoir besoin de vos fichiers d'origine. C'est ce qui rend le rollback fiable, même si le poste qui a lancé le déploiement initial n'existe plus.

Historique des révisions

La colonne DESCRIPTION indique la nature de chaque opération, ce qui permet de repérer immédiatement un rollback antérieur.

helm history my-metrics -n helm-demo

REVISION    UPDATED                     STATUS        CHART                       APP VERSION   DESCRIPTION
1           Sun Feb  1 17:48:21 2026    superseded    kube-state-metrics-5.27.0   2.14.0        Install complete
2           Sun Feb  1 18:15:42 2026    deployed      kube-state-metrics-5.27.0   2.14.0        Upgrade complete

Revenir à une révision précédente

Le numéro passé à helm rollback est celui de la révision cible, telle qu'affichée par helm history. Sans numéro, Helm revient à la révision immédiatement précédente.

# Rollback à la révision 1
helm rollback my-metrics 1 -n helm-demo

Rollback was a success! Happy Helming!

Vérifiez l'historique après le rollback :

helm history my-metrics -n helm-demo

REVISION    UPDATED                     STATUS        CHART                       APP VERSION   DESCRIPTION
1           Sun Feb  1 17:48:21 2026    superseded    kube-state-metrics-5.27.0   2.14.0        Install complete
2           Sun Feb  1 18:15:42 2026    superseded    kube-state-metrics-5.27.0   2.14.0        Upgrade complete
3           Sun Feb  1 18:30:15 2026    deployed      kube-state-metrics-5.27.0   2.14.0        Rollback to 1

Rollback = nouvelle révision

Un rollback ne "revient pas en arrière" dans l'historique, il crée une nouvelle révision (ici 3) qui reproduit l'état de la révision cible (1). L'historique complet est conservé.

Supprimer une release

La suppression est irréversible sans précaution : par défaut, Helm efface les objets Kubernetes et l'historique des révisions, donc plus aucun rollback n'est possible. Deux catégories d'objets survivent malgré tout, les PersistentVolumeClaims créés par un StatefulSet et les CRD installés par le chart, qu'il faut supprimer à la main si vous voulez repartir de zéro.

helm uninstall

Le namespace, lui, n'est jamais supprimé : il reste en place avec les éventuels objets qui n'appartenaient pas à la release.

helm uninstall my-metrics -n helm-demo

release "my-metrics" uninstalled

Par défaut, helm uninstall :

• Supprime tous les objets Kubernetes créés par la release
• Supprime l'historique des révisions

Conserver l'historique

L'option --keep-history supprime les ressources mais garde les révisions enregistrées, ce qui laisse la possibilité de restaurer la release par un helm rollback. Le nom de la release reste alors réservé dans le namespace.

helm uninstall my-metrics -n helm-demo --keep-history

Avec --keep-history, vous pouvez voir les releases supprimées :

helm list -n helm-demo --uninstalled

Options importantes de helm install

Ces options se combinent librement et changent beaucoup le comportement de la commande. Deux méritent une attention particulière : --wait fait patienter Helm jusqu'à ce que les Pods soient prêts, sans quoi la commande rend la main avant que l'application ne fonctionne réellement ; --atomic va plus loin en annulant automatiquement l'opération si le délai expire, ce qui évite de laisser une release à moitié installée.

Option	Description	Exemple
--namespace / -n	Namespace cible	-n production
--create-namespace	Crée le namespace s'il n'existe pas	--create-namespace
--version	Version spécifique du chart	--version 5.26.0
--values / -f	Fichier de values personnalisées	-f my-values.yaml
--set	Surcharge une value en ligne de commande	--set replicas=3
--dry-run	Simule sans appliquer	--dry-run
--wait	Attend que les Pods soient Ready	--wait
--timeout	Timeout pour --wait	--timeout 5m
--atomic	Rollback automatique si échec	--atomic

Glissez pour voir

Exemple avec plusieurs options

Cet appel est représentatif d'un déploiement réel : version du chart figée, fichier de values versionné, surcharge ponctuelle et attente de la disponibilité effective des Pods.

helm install prometheus prometheus-community/prometheus \
  --namespace monitoring \
  --create-namespace \
  --version 25.27.0 \
  -f custom-values.yaml \
  --set server.retention=30d \
  --wait \
  --timeout 10m

Simuler avant de déployer (dry-run)

La simulation rend visible le rendu final des templates, valeurs substituées comprises. C'est le seul moyen de vérifier ce qu'un chart va réellement créer avant de le laisser toucher au cluster, en particulier quand vous passez plusieurs fichiers de values qui se surchargent.

Toujours tester d'abord

Avant de déployer en production, utilisez --dry-run pour voir ce qui sera créé sans rien appliquer sur le cluster.

helm install my-app podinfo/podinfo -n helm-demo --dry-run

Cela affiche :

1. Les métadonnées de la release (comme un install normal)
2. Le manifeste YAML complet qui serait appliqué
3. Les NOTES qui seraient affichées

Dry-run côté client vs serveur

La différence tient à qui vérifie le résultat : votre poste ou l'API Kubernetes. Le mode client fonctionne même sans cluster joignable, le mode serveur exige une connexion et les droits associés.

# Côté client (ne contacte pas le cluster)
helm install my-app podinfo/podinfo --dry-run=client

# Côté serveur (valide avec l'API Kubernetes)
helm install my-app podinfo/podinfo --dry-run=server

--dry-run=server est plus précis car il valide que les manifestes sont acceptés par l'API Kubernetes.

Lab A3 : Cycle de vie complet d'une release

Objectif : Pratiquer le cycle install → upgrade → rollback → uninstall.

1. Créez un namespace et installez podinfo

   kubectl create namespace lab-helm
   helm install demo podinfo/podinfo --namespace lab-helm --version 6.7.0

   Lisez attentivement les NOTES affichées.

2. Vérifiez le déploiement

   kubectl get all -n lab-helm
   helm list -n lab-helm

3. Mettez à jour vers une version plus récente

   helm upgrade demo podinfo/podinfo --namespace lab-helm --version 6.9.0

4. Consultez l'historique

   helm history demo -n lab-helm

5. Effectuez un rollback

   helm rollback demo 1 -n lab-helm
   helm history demo -n lab-helm

6. Nettoyez

   helm uninstall demo -n lab-helm
   kubectl delete namespace lab-helm

Résultat attendu : Vous maîtrisez le cycle de vie complet d'une release Helm.

Dépannage

La plupart des erreurs Helm proviennent de l'écart entre l'état enregistré dans la release et la réalité du cluster : un nom déjà pris, un namespace implicite ou des Pods qui ne démarrent pas dans le temps imparti. Le tableau donne la lecture rapide, les commandes qui suivent permettent de remonter à la cause exacte.

Symptôme	Cause probable	Solution
STATUS: failed	Erreur dans les templates ou ressources invalides	helm status <release> puis kubectl describe sur les ressources
Error: cannot re-use a name that is still in use	Release existe déjà	Utiliser helm upgrade --install ou supprimer d'abord
Error: INSTALLATION FAILED: timed out	Pods ne démarrent pas	Augmenter --timeout ou investiguer avec kubectl describe pod
Pods en CrashLoopBackOff	Configuration incorrecte	Vérifier les values, les secrets, les ressources
Error: release not found	Mauvais namespace	Ajouter -n <namespace> à la commande

Glissez pour voir

Investiguer une release en échec

Ces trois commandes lisent la release telle qu'elle est enregistrée : helm get manifest montre le YAML réellement appliqué et helm get values les valeurs effectives, souvent différentes de celles que vous croyiez avoir passées.

# Voir le statut détaillé
helm status my-release -n my-namespace

# Voir les manifestes qui ont été appliqués
helm get manifest my-release -n my-namespace

# Voir les values utilisées
helm get values my-release -n my-namespace

À retenir

• Release = instance déployée d'un chart. Nom unique + numéro de révision + historique.
• helm install crée une nouvelle release. Lisez toujours les NOTES affichées !
• La sortie de helm install contient : NAME, NAMESPACE, STATUS, REVISION, informations essentielles pour le debugging.
• helm upgrade --install est idempotent, préférez-le en CI/CD.
• helm history + helm rollback permettent de revenir à un état antérieur.
• --dry-run simule le déploiement, utilisez-le systématiquement avant la production.
• Helm stocke les releases dans des Secrets Kubernetes (pas de base de données externe).

Prochaines étapes

Personnaliser avec les values Maîtrisez la configuration avec -f, --set et la hiérarchie des values

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

Repos et découverte de charts Retour au module précédent

×

📖 Voir la documentation →