Lifecycle Helm : upgrade, history, rollback et uninstall

Ce guide vous apprend à gérer le cycle de vie complet d'une release Helm. Vous allez maîtriser les commandes upgrade, rollback, history et uninstall pour mettre à jour vos applications en toute sécurité, revenir en arrière en cas de problème, et nettoyer proprement. En 20 minutes, vous saurez piloter vos releases comme en production.

Prérequis

• Helm installé et un repo configuré (voir module H1-02)
• Un cluster Kubernetes fonctionnel (minikube, kind, k3d)
• Avoir compris helm install et les values (voir modules précédents)

Comprendre le lifecycle d'une release

Les 5 états d'une release

Une release Helm peut se trouver dans différents états selon son cycle de vie :

État	Signification	Quand ?
deployed	Release active et fonctionnelle	Après un install ou upgrade réussi
superseded	Ancienne révision remplacée	Après un nouvel upgrade ou rollback
pending-install	Installation en cours	Pendant l'exécution de helm install
pending-upgrade	Mise à jour en cours	Pendant l'exécution de helm upgrade
failed	Échec de l'opération	Si les hooks échouent ou timeout atteint
uninstalled	Release supprimée (avec historique)	Après helm uninstall --keep-history

Glissez pour voir

Une seule révision deployed

À tout moment, une seule révision d'une release peut avoir le statut deployed. Toutes les autres sont en superseded (historique) ou uninstalled (supprimée).

Le concept de révision

Chaque opération sur une release crée une nouvelle révision :

Révision 1 (install)     → deployed → superseded
Révision 2 (upgrade)     → deployed → superseded
Révision 3 (upgrade)     → deployed → superseded
Révision 4 (rollback 2)  → deployed    ← ACTUELLE

Le rollback ne "revient pas dans le temps" : il crée une nouvelle révision avec la configuration d'une révision précédente.

Install vs Upgrade : quelle différence ?

Comportement de chaque commande

install et upgrade ne sont pas interchangeables : chacune échoue dans la situation opposée. helm install refuse une release déjà présente, helm upgrade refuse une release absente. Le tableau croise ces deux cas. Retenez surtout les deux lignes rouges, ce sont elles qui expliquent l'erreur que vous rencontrerez tôt ou tard en rejouant un script, et que upgrade --install résout d'un coup.

Commande	Release existe ?	Comportement
helm install	Non	✅ Crée la release
helm install	Oui	❌ Erreur : cannot re-use a name
helm upgrade	Non	❌ Erreur : has no deployed releases
helm upgrade	Oui	✅ Met à jour la release

Glissez pour voir

Démonstration : l'erreur d'install sur une release existante

Installez une release :

helm install mon-api stefanprodan/podinfo -n demo --create-namespace --version 6.7.1

Résultat :

NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:24:49 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 1

Tentez de réinstaller la même release :

helm install mon-api stefanprodan/podinfo -n demo --version 6.7.1

Résultat (erreur) :

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

Piège courant

Cette erreur est fréquente quand on relance un script d'installation. La solution : utiliser upgrade --install (voir section suivante).

Démonstration : l'erreur d'upgrade sur une release inexistante

helm upgrade app-inexistante stefanprodan/podinfo -n demo

Résultat (erreur) :

Error: UPGRADE FAILED: "app-inexistante" has no deployed releases

Idempotence avec upgrade --install

Le problème en CI/CD

En CI/CD, vous ne savez pas toujours si la release existe déjà :

• Premier déploiement : la release n'existe pas → install fonctionne
• Déploiements suivants : la release existe → install échoue

La solution : upgrade --install

L'option --install rend helm upgrade idempotent : la commande crée la release si elle n'existe pas, ou la met à jour si elle existe.

helm upgrade --install mon-api stefanprodan/podinfo -n demo --version 6.7.1

Si la release n'existe pas :

Release "mon-api" does not exist. Installing it now.
NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:25:42 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 1

Si la release existe déjà :

Release "mon-api" has been upgraded. Happy Helming!
NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:25:49 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 2

Bonne pratique CI/CD

Utilisez toujours helm upgrade --install dans vos pipelines. Cette commande est idempotente : vous pouvez la relancer autant de fois que nécessaire sans erreur.

Options complémentaires pour CI/CD

Option	Effet
--create-namespace	Crée le namespace s'il n'existe pas
--wait	Attend que les pods soient Ready avant de terminer
--timeout 5m	Timeout pour --wait (défaut: 5m)
--atomic	Rollback automatique si l'upgrade échoue
--description "v1.2.3"	Description personnalisée dans l'historique

Glissez pour voir

Commande CI/CD complète :

helm upgrade --install mon-api stefanprodan/podinfo \
  --namespace demo \
  --create-namespace \
  --version 6.7.1 \
  --wait \
  --timeout 3m \
  --description "Déploiement v6.7.1 depuis CI"

Mettre à jour avec helm upgrade

Mise à jour des values

Pour modifier la configuration d'une release existante :

helm upgrade mon-api stefanprodan/podinfo -n demo --set replicaCount=2

Résultat :

Release "mon-api" has been upgraded. Happy Helming!
NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:25:12 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 2

Mise à jour de la version du chart

Pour passer à une nouvelle version du chart :

helm upgrade mon-api stefanprodan/podinfo -n demo --version 6.8.0

Attention au --reuse-values

Par défaut, helm upgrade utilise les values par défaut du nouveau chart. Si vous voulez conserver vos surcharges, ajoutez --reuse-values. Voir le module Values pour les détails.

L'option --force

L'option --force supprime et recrée les ressources au lieu de les patcher :

helm upgrade mon-api stefanprodan/podinfo -n demo --set replicaCount=1 --force

Quand l'utiliser :

• Modification de champs immutables (selector d'un Deployment)
• Ressources corrompues qu'un patch ne peut pas réparer
• Debug de problèmes de synchronisation

Interruption de service

--force provoque une interruption de service car les ressources sont supprimées puis recréées. Utilisez-le uniquement si nécessaire.

Consulter l'état : status, get, history

helm status : état actuel de la release

helm status mon-api -n demo

Résultat :

NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:25:12 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 2
NOTES:
1. Get the application URL by running these commands:
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl -n demo port-forward deploy/mon-api-podinfo 8080:9898

Décryptage :

Champ	Signification
LAST DEPLOYED	Date/heure du dernier déploiement
STATUS	État actuel (deployed, failed, etc.)
REVISION	Numéro de la révision actuelle
NOTES	Instructions post-installation du chart

Glissez pour voir

helm status d'une révision spécifique

Vous pouvez consulter l'état d'une révision passée :

helm status mon-api -n demo --revision 1

Résultat :

NAME: mon-api
LAST DEPLOYED: Sun Feb  1 18:24:49 2026
NAMESPACE: demo
STATUS: superseded
REVISION: 1

Le statut superseded indique que cette révision a été remplacée par une plus récente.

helm history : historique des révisions

helm history mon-api -n demo

Résultat :

REVISION  UPDATED                   STATUS      CHART          APP VERSION  DESCRIPTION
1         Sun Feb  1 18:24:49 2026  superseded  podinfo-6.7.1  6.7.1        Install complete
2         Sun Feb  1 18:25:12 2026  superseded  podinfo-6.7.1  6.7.1        Upgrade complete
3         Sun Feb  1 18:26:56 2026  deployed    podinfo-6.7.1  6.7.1        Upgrade complete

Décryptage de chaque colonne :

Colonne	Contenu
REVISION	Numéro incrémental de la révision
UPDATED	Date/heure de cette révision
STATUS	deployed (actuelle), superseded (ancienne), failed
CHART	Nom et version du chart utilisé
APP VERSION	Version de l'application (définie dans Chart.yaml)
DESCRIPTION	Origine : Install complete, Upgrade complete, Rollback to X

Glissez pour voir

Les commandes helm get

Helm propose plusieurs commandes get pour inspecter les détails d'une release :

Commande	Contenu
helm get values	Values personnalisées (surcharges)
helm get values --all	Toutes les values (défauts + surcharges)
helm get manifest	Manifests Kubernetes générés
helm get notes	Notes post-installation
helm get hooks	Hooks de la release
helm get all	Tout ce qui précède

Glissez pour voir

Exemple : voir les values d'une révision précédente

helm get values mon-api -n demo --revision 1

Résultat :

USER-SUPPLIED VALUES:
null

La révision 1 n'avait aucune surcharge.

helm get values mon-api -n demo --revision 2

Résultat :

USER-SUPPLIED VALUES:
replicaCount: 2

La révision 2 a ajouté replicaCount: 2.

Limiter l'historique avec --history-max

Par défaut, Helm conserve les 10 dernières révisions. En CI/CD avec des déploiements fréquents, l'historique peut devenir volumineux.

helm upgrade mon-api stefanprodan/podinfo -n demo --history-max 3

Cette option purge automatiquement les révisions les plus anciennes pour n'en garder que 3 :

helm history mon-api -n demo

Résultat après plusieurs upgrades avec --history-max 3 :

REVISION  UPDATED                   STATUS      CHART           APP VERSION  DESCRIPTION
9         Sun Feb  1 18:28:56 2026  superseded  podinfo-6.10.0  6.10.0       Upgrade complete
10        Sun Feb  1 18:29:06 2026  superseded  podinfo-6.7.1   6.7.1        Rollback to 7
11        Sun Feb  1 18:29:17 2026  deployed    podinfo-6.10.0  6.10.0       Upgrade complete

Compromis rollback vs stockage

Un --history-max faible limite la capacité de rollback. En production, gardez au moins 5-10 révisions pour pouvoir revenir en arrière.

Rollback : revenir en arrière

Quand faire un rollback ?

Le rollback est votre filet de sécurité quand un upgrade dégrade l'application. L'objectif est de restaurer un état stable connu en quelques secondes, sans rejouer un déploiement complet. Les situations ci-dessous partagent le même signal : l'état actuel est cassé et vous disposez d'une révision précédente qui, elle, fonctionnait.

• L'application ne fonctionne plus après un upgrade
• Les pods sont en CrashLoopBackOff
• Les métriques montrent des erreurs en hausse
• Vous devez revenir rapidement à un état stable

Rollback vers une révision spécifique

helm rollback mon-api 2 -n demo

Résultat :

Rollback was a success! Happy Helming!

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

helm history mon-api -n demo

Résultat :

REVISION  UPDATED                   STATUS      CHART          APP VERSION  DESCRIPTION
1         Sun Feb  1 18:24:49 2026  superseded  podinfo-6.7.1  6.7.1        Install complete
2         Sun Feb  1 18:25:12 2026  superseded  podinfo-6.7.1  6.7.1        Upgrade complete
3         Sun Feb  1 18:26:56 2026  superseded  podinfo-6.7.1  6.7.1        Upgrade complete
4         Sun Feb  1 18:27:10 2026  deployed    podinfo-6.7.1  6.7.1        Rollback to 2

Le rollback crée une nouvelle révision

Remarquez que le rollback a créé la révision 4 avec la description "Rollback to 2". Helm ne modifie jamais l'historique : il ajoute toujours une nouvelle révision.

Rollback vers la révision précédente (sans numéro)

Sans numéro de révision, Helm revient à la révision immédiatement précédente :

helm rollback mon-api -n demo

Résultat :

Rollback was a success! Happy Helming!

helm history mon-api -n demo

Résultat :

REVISION  UPDATED                   STATUS      CHART          APP VERSION  DESCRIPTION
...
4         Sun Feb  1 18:27:10 2026  superseded  podinfo-6.7.1  6.7.1        Rollback to 2
5         Sun Feb  1 18:27:41 2026  deployed    podinfo-6.7.1  6.7.1        Rollback to 3

Rollback : ce qui est restauré

Lors d'un rollback, Helm restaure :

Élément	Restauré ?
Values (configuration)	✅ Oui
Version du chart	✅ Oui
Templates générés	✅ Oui
Ressources Kubernetes	✅ Oui (recréées/patchées)
Données des PVC	❌ Non (persistantes)
Données des bases de données	❌ Non (externes)

Glissez pour voir

Les données ne sont pas restaurées

Le rollback Helm ne touche pas aux données persistantes (PersistentVolumeClaims, bases de données). Si votre upgrade a corrompu des données, le rollback ne les restaurera pas.

Erreur : révision inexistante

helm rollback mon-api 99 -n demo

Résultat :

Error: release has no 99 version

Consultez helm history pour voir les révisions disponibles.

Options du rollback

Le rollback accepte les mêmes options de contrôle qu'un upgrade. La plus utile en production est --wait : sans elle, la commande rend la main dès que Helm a soumis les manifests, avant même que les pods soient réellement repartis, ce qui peut donner un faux sentiment de succès. Réservez --force et --recreate-pods aux cas où un simple patch ne suffit pas, car ils provoquent une coupure.

Option	Effet
--wait	Attend que les pods soient Ready
--timeout 5m	Timeout pour --wait
--force	Force la recréation des ressources
--recreate-pods	Supprime et recrée tous les pods

Glissez pour voir

Supprimer avec helm uninstall

Suppression standard

helm uninstall mon-api -n demo

Résultat :

release "mon-api" uninstalled

Cette commande supprime :

• La release de la base Helm
• Toutes les ressources Kubernetes créées par le chart
• L'historique des révisions

Vérification après uninstall

helm list -n demo
kubectl get all -n demo

Les ressources créées par la release ont disparu.

Conserver l'historique avec --keep-history

Pour garder une trace de la release supprimée :

helm uninstall mon-api -n demo --keep-history

Résultat :

release "mon-api" uninstalled

La release apparaît avec le statut uninstalled :

helm list -n demo --all

Résultat :

NAME      NAMESPACE  REVISION  UPDATED                   STATUS       CHART          APP VERSION
mon-api   demo       1         Sun Feb  1 18:29:52 2026  uninstalled  podinfo-6.7.1  6.7.1

L'historique reste consultable :

helm history mon-api -n demo

Résultat :

REVISION  UPDATED                   STATUS       CHART          APP VERSION  DESCRIPTION
1         Sun Feb  1 18:29:52 2026  uninstalled  podinfo-6.7.1  6.7.1        Uninstallation complete

Audit et conformité

--keep-history est utile pour l'audit : vous gardez une trace de ce qui a été déployé et quand, même après suppression.

Filtrer les releases par statut

Par défaut, helm list ne montre que les releases déployées, ce qui masque les échecs et les releases supprimées avec --keep-history. Ces filtres deviennent indispensables pour le diagnostic : --failed révèle un déploiement bloqué en failed qui n'apparaît pas dans la liste normale, et --uninstalled retrouve la trace d'une release effacée dont vous voulez consulter l'historique.

# Releases déployées uniquement (défaut)
helm list -n demo

# Releases avec échec
helm list -n demo --failed

# Releases supprimées (avec --keep-history)
helm list -n demo --uninstalled

# Toutes les releases
helm list -n demo --all

Ce qui n'est PAS supprimé

helm uninstall ne supprime pas :

Ressource	Pourquoi
PersistentVolumeClaims d'un StatefulSet	Créés par volumeClaimTemplates, ils sont gérés par Kubernetes et non par Helm. Un PVC ordinaire, lui, est supprimé par défaut : annotez-le helm.sh/resource-policy: keep pour le conserver
Namespace	Peut contenir d'autres ressources
CRDs	Peuvent être utilisées par d'autres releases
Ressources créées manuellement	Non gérées par Helm

Glissez pour voir

Pour supprimer le namespace et tout son contenu :

kubectl delete namespace demo

Options avancées pour la production

--atomic : rollback automatique si échec

L'option --atomic combine --wait et un rollback automatique si le déploiement échoue :

helm upgrade --install mon-api stefanprodan/podinfo \
  -n demo \
  --set image.tag=inexistant \
  --atomic \
  --timeout 30s

Si les pods ne deviennent pas Ready dans le timeout, Helm effectue automatiquement un rollback vers la révision précédente.

Indispensable en CI/CD

Utilisez --atomic dans vos pipelines pour éviter de laisser un déploiement cassé. Si l'upgrade échoue, l'environnement revient à son état précédent.

--dry-run : prévisualiser avant d'appliquer

helm upgrade mon-api stefanprodan/podinfo -n demo --set replicaCount=5 --dry-run

Cette commande affiche les manifests qui seraient générés sans les appliquer. Le status affiché est pending-upgrade.

Output JSON/YAML pour l'automatisation

# Liste des releases en JSON
helm list -n demo -o json

# Historique en YAML
helm history mon-api -n demo -o yaml

Utile pour parser les résultats dans des scripts.

Description personnalisée

Ajoutez une description pour tracer les déploiements :

helm upgrade --install mon-api stefanprodan/podinfo \
  -n demo \
  --description "Ticket JIRA-1234 - Ajout du health check"

helm history mon-api -n demo

Résultat :

REVISION  UPDATED                   STATUS    CHART          DESCRIPTION
1         Sun Feb  1 18:31:30 2026  deployed  podinfo-6.7.1  Ticket JIRA-1234 - Ajout du health check

Tableau récapitulatif des commandes

Ce tableau condense tout le cycle de vie en une antisèche à garder sous la main. Si vous ne deviez retenir qu'une ligne, ce serait helm upgrade --install : c'est la seule commande idempotente, celle qui fonctionne aussi bien au premier déploiement qu'aux suivants, et donc la seule à mettre dans un pipeline.

Commande	Effet
helm install <name> <chart>	Crée une nouvelle release (erreur si existe)
helm upgrade <name> <chart>	Met à jour une release existante (erreur si n'existe pas)
helm upgrade --install <name> <chart>	Crée ou met à jour (idempotent)
helm status <name>	Affiche l'état actuel de la release
helm history <name>	Liste toutes les révisions
helm get values <name>	Affiche les values personnalisées
helm get manifest <name>	Affiche les manifests Kubernetes
helm rollback <name> [revision]	Revient à une révision précédente
helm uninstall <name>	Supprime la release et ses ressources

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
cannot re-use a name	Release existe déjà	Utiliser upgrade --install
has no deployed releases	Release n'existe pas	Utiliser upgrade --install
release has no X version	Révision inexistante	Vérifier avec helm history
Pods en Pending après rollback	Ressources insuffisantes	Vérifier les quotas/nodes
PVC encore présent après uninstall	Comportement normal	Supprimer manuellement si souhaité

Glissez pour voir

---

Lab A5, Upgrade puis rollback

1. Installer une release stable

   kubectl create namespace helm-lab
   helm install mon-api stefanprodan/podinfo -n helm-lab --version 6.7.1

2. Vérifier l'état initial

   helm history mon-api -n helm-lab
   kubectl get pods -n helm-lab

3. Faire un premier upgrade (changement visible)

   helm upgrade mon-api stefanprodan/podinfo -n helm-lab --set replicaCount=3 --set ui.message="Version 2"

4. Observer la nouvelle révision

   helm history mon-api -n helm-lab
   helm get values mon-api -n helm-lab

5. Simuler un problème (image inexistante)

   helm upgrade mon-api stefanprodan/podinfo -n helm-lab --set image.tag=fausse-version

6. Observer l'état cassé

   kubectl get pods -n helm-lab
   # Un ou plusieurs pods en ImagePullBackOff

7. Rollback vers la révision stable

   helm rollback mon-api 2 -n helm-lab

8. Vérifier le retour à la normale

   helm history mon-api -n helm-lab
   kubectl get pods -n helm-lab
   # Tous les pods Running

9. Nettoyer

   helm uninstall mon-api -n helm-lab
   kubectl delete namespace helm-lab

Critères de réussite :

• helm history montre au moins 4 révisions
• Vous identifiez la révision problématique
• Le rollback ramène les pods en Running
• Vous comprenez la relation révision ↔ configuration

---

À retenir

• helm upgrade --install est la commande idempotente pour CI/CD
• Chaque opération crée une nouvelle révision dans l'historique
• helm history permet de consulter toutes les révisions
• helm rollback crée une nouvelle révision avec l'ancienne config
• helm uninstall supprime les ressources mais pas les données persistantes
• Utilisez --atomic en production pour rollback automatique en cas d'échec
• Limitez l'historique avec --history-max pour éviter l'accumulation

---

Prochaines étapes

Diagnostiquer et valider helm lint, template, --debug et dépannage

Revenir aux values Configurer proprement avec -f et --set

Parcours B : Créer des charts Anatomie et structure d'un chart Helm

×

📖 Voir la documentation →