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, kind pour cette formation
• 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 manifestes : 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 values 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, messages d'erreur compris.

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)

La distinction entre chart et release est celle qui débloque le reste de la leçon. Le chart est le paquet versionné, avec ses templates et ses values par défaut ; il vit dans un dépôt et ne sait rien de votre cluster. La release est l'instance déployée dans un namespace, avec les values réellement appliquées et son propre numéro de révision.

La conséquence pratique est qu'on peut déployer le même chart plusieurs fois, sous des noms de release différents, par exemple prometheus-prod et prometheus-staging. Chaque release porte alors son historique et ses values propres, et se met à jour ou se supprime indépendamment de l'autre.

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 manifestes depuis les templates et les values, les envoie à l'API server, puis enregistre le tout dans une release en révision 1. Tant que cette étape n'est pas comprise, upgrade et 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

La section NOTES: est la seule partie de la sortie qui soit écrite par l'auteur du chart, et c'est ce qui la rend irremplaçable : aucune commande générique ne vous dira comment joindre l'application que vous venez d'installer. Elle porte en général quatre choses, l'accès à l'application par URL, redirection de port ou Ingress, les identifiants par défaut quand il y en a, les commandes de vérification à jouer, et la configuration additionnelle recommandée.

Dans l'exemple ci-dessus, les NOTES indiquent ce que fait le composant, l'adresse interne sur laquelle il expose ses métriques, et le format dans lequel il les sert. Si vous les perdez, helm status les réaffiche : elles sont stockées avec la release, pas seulement écrites à l'installation.

Ne sautez pas les NOTES

C'est la partie de la sortie que tout le monde ignore, et celle qui contient l'URL d'accès. Un helm status <release> -n <namespace> la rejoue à tout moment, sans rien redéployer.

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 bloquée jusqu'à intervention. Le statut superseded n'est pas une anomalie : il désigne 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, ce qu'un compte restreint n'a pas toujours.

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

En intégration continue, écrivez helm upgrade --install plutôt que helm install. La commande devient rejouable telle quelle, que la release existe déjà ou non, ce qui évite d'écrire une condition fragile autour.

Attention toutefois au sens du mot idempotent : chaque passage crée quand même une révision de plus, même quand rien n'a changé. Une chaîne qui se déclenche à chaque commit gonfle donc l'historique sans rien apporter, d'où l'intérêt de --history-max.

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 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 que l'affiche 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

Un rollback ne « revient pas en arrière » dans l'historique : il y ajoute. Helm crée une nouvelle révision qui reproduit l'état de la révision visée, et conserve tout le reste. L'historique complet est donc préservé, ce qui garde une trace auditable de l'opération et permet, si le rollback était l'erreur, de revenir en avant par un second rollback.

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 réservé dans le namespace, et helm list --uninstalled la retrouve.

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. --rollback-on-failure, qui s'appelait --atomic en Helm v3, va plus loin en annulant 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
--rollback-on-failure	Rollback automatique si échec	--rollback-on-failure

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 plusieurs fichiers de values 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

La sortie porte alors trois blocs, et rien n'est créé dans le cluster :

1. Les métadonnées de la release, comme pour une installation normale
2. Le manifeste YAML complet qui serait appliqué
3. Les NOTES telles qu'elles s'afficheraient

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, mais valide en retour les schémas et les politiques d'admission.

# 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 remontent à 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 reuse 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é, helm get values les valeurs effectives, souvent différentes de celles que vous croyiez avoir passées. C'est cet écart qu'il s'agit de localiser.

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

Contrôle de connaissances

Six questions sur le cycle d'une release : ce que rend helm get values sans surcharge, ce que --install rend rejouable sans le rendre sans effet, et le nombre de secrets qu'accumule un historique non borné.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

5 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

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Mettre en pratique

Un retour arrière Helm se lit dans l'historique de la release, pas dans le chart. Ce lab vous fait installer un chart, le mettre à jour avec de nouvelles valeurs, puis revenir à la première révision, et la validation croise l'historique de la release et l'état du Deployment pour vérifier que les trois opérations ont eu lieu dans cet ordre.

Lab pratique

Installer, mettre à jour et revenir en arrière avec Helm 4

$ dsoxlab run ckad-helm-install-upgrade

Environnement : VM·Durée : ~15 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training

Lancer ce lab, puis valider votre travail :

dsoxlab run ckad-helm-install-upgrade
dsoxlab check ckad-helm-install-upgrade

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Anatomie d'un chart : Comprendre ce que votre release a réellement déployé.
• Upgrade, rollback et cycle de vie : Faire évoluer une release installée, et revenir en arrière proprement.
• Déboguer et valider un chart : Diagnostiquer une release qui échoue à l'installation.

×

📖 Voir la documentation →