Les releases et leur cycle de vie

Pourquoi

Installer un chart n'est que le début de sa vie. Il faut ensuite le mettre à jour, voir ce qui tourne réellement, comprendre pourquoi une mise à jour a échoué, revenir en arrière un vendredi à 17 heures, et un jour désinstaller. Chacun de ces gestes s'appuie sur une même idée : Helm retient ce qu'il a fait. Sans cette mémoire, une mise à jour ne saurait pas quels objets supprimer, un retour arrière n'aurait rien à restaurer.

Cette mémoire est aussi la source de surprises. On croit relancer la même commande et l'on perd la moitié de sa configuration. On corrige un objet à la main en urgence et Helm écrase la correction, ou la garde, selon un mécanisme que peu de gens connaissent. On désinstalle et des objets restent. Cette leçon ouvre la boîte : ce que contient une release, où elle vit, comment une mise à jour est calculée, et les gestes sûrs.

Une précision de périmètre. Tout ce qui suit décrit des commandes qui parlent à un cluster, et le poste de rédaction n'en avait pas : les sorties de ces commandes sont décrites, jamais reproduites. Les rendus locaux (helm template) restent réels. Le code source de Helm 3.16.3 a été lu pour les comportements précis.

Les concepts

Une release et ses révisions

Chaque helm install crée une release à la révision 1. Chaque helm upgrade ou helm rollback crée une nouvelle révision, numérotée à la suite : une release qui a connu une installation, deux mises à jour et un retour arrière est à la révision 4. Rien n'est écrasé : chaque révision est un enregistrement complet, avec le chart, les valeurs et les manifestes de ce moment. Cela fait de l'historique un journal d'audit, et du retour arrière une simple opération de lecture et d'application.

Une révision a un état :

Les commandes d'inspection

Cinq commandes disent ce qui est installé. Elles ne modifient rien.

$ helm list --namespace traefik
$ helm status traefik --namespace traefik
$ helm get values traefik --namespace traefik
$ helm get manifest traefik --namespace traefik
$ helm get notes traefik --namespace traefik

• helm list affiche une ligne par release du namespace : nom, namespace, révision, date de mise à jour, état, chart (traefik-41.6.1) et version de l'application. Avec -A (ou --all-namespaces), tous les namespaces ; avec --all, y compris les releases dans un autre état que deployed ; avec --uninstalled, celles désinstallées dont l'historique est conservé. Sans -n, seul le namespace du contexte est listé : une release introuvable est souvent dans un autre namespace.
• helm status montre l'état de la dernière révision, la date, le namespace, puis les notes du chart. Avec --show-resources (Helm 3.13 et suivants), il liste aussi les objets de la release.
• helm get values affiche uniquement les valeurs que vous avez fournies à cette release, pas les défauts du chart. Avec --all, il affiche les valeurs finales fusionnées. Avec --revision N, celles d'une révision passée.
• helm get manifest affiche les manifestes tels que Helm les a envoyés à cette révision. C'est ce que rendrait helm template à l'époque, avec ces valeurs.
• helm get notes réaffiche les notes de fin d'installation. helm get hooks affiche les manifestes des hooks (leçon 8), et helm get all tout ce qui précède.

Ces commandes lisent l'enregistrement de la release, pas les objets du cluster. helm get manifest peut donc différer de la réalité si quelqu'un a modifié un objet depuis : c'est ce que Helm croit avoir déployé.

Mettre à jour : helm upgrade

$ helm upgrade traefik traefik/traefik --version 41.6.1 --namespace traefik -f traefik-values.yaml

La commande rend le chart avec les valeurs fournies, calcule la différence avec ce qui est en place (voir « Sous le capot »), applique les changements, et enregistre une nouvelle révision. Les options de helm install s'appliquent presque toutes : --wait, --timeout, --atomic (--rollback-on-failure avec Helm 4), -f, --set, --version.

helm upgrade échoue si la release n'existe pas. L'option --install fait un install dans ce cas, ce qui donne une commande rejouable : la même ligne fonctionne pour la première installation et pour toutes les mises à jour.

$ helm upgrade --install signalements ./signalements \
    --namespace signalements --create-namespace \
    -f valeurs-recette.yaml --atomic --timeout 5m

C'est la forme à retenir pour les scripts et les pipelines. Deux options en plus sont utiles : --history-max N limite le nombre de révisions conservées (10 par défaut), et --cleanup-on-fail supprime les nouveaux objets créés par une mise à jour qui échoue.

Comme pour l'installation, l'option --wait est décisive. Sans elle, helm upgrade rend la main quand l'API a accepté les objets, pas quand les nouveaux pods sont prêts. Une mise à jour peut afficher STATUS: deployed alors que le nouveau Deployment est bloqué en ImagePullBackOff. Avec --wait, Helm attend ; avec --atomic, il restaure la révision précédente si l'attente expire.

Lire l'historique, revenir en arrière

$ helm history traefik --namespace traefik

La commande affiche une ligne par révision : numéro, date, état, chart, version de l'application, et une description (Install complete, Upgrade complete, Rollback to 2, ou le message d'une erreur). Cet historique ne conserve que les révisions encore présentes : au-delà de --history-max, les plus anciennes sont supprimées.

Le retour arrière :

$ helm rollback traefik 2 --namespace traefik --wait

helm rollback <release> <révision> ramène la release au chart, aux valeurs et aux manifestes de la révision 2. Sans numéro de révision, il revient à la précédente. Un détail essentiel : le retour arrière ne remonte pas dans le temps, il avance. Il crée une nouvelle révision (la 5, si l'on en était à la 4) dont le contenu est celui de la révision 2, avec la description Rollback to 2. L'historique reste complet et linéaire, ce qui rend une enquête possible.

Ce que le retour arrière restaure : les manifestes et les valeurs de la révision cible. Ce qu'il ne restaure pas : les données des volumes, les migrations de base de données déjà exécutées, les ressources créées hors de la release (une CRD installée à part). Revenir à l'ancien Deployment de Signalements ne défait pas une colonne ajoutée en base par la migration de la nouvelle version, d'où la règle du cours Kubernetes : une migration doit rester compatible avec la version précédente.

Désinstaller

$ helm uninstall traefik --namespace traefik
$ helm uninstall traefik --namespace traefik --keep-history

helm uninstall supprime tous les objets créés par la release et, par défaut, tout son historique : les Secrets de release disparaissent aussi, et l'on ne peut plus revenir en arrière. Avec --keep-history, les objets sont supprimés mais les enregistrements restent, avec l'état uninstalled : helm list --uninstalled les montre, helm history aussi, et helm rollback peut même ressusciter la release.

Ce que uninstall laisse en place :

• Les définitions de ressources (CRD) installées depuis le répertoire crds/ du chart : Helm ne les supprime jamais, parce que supprimer une CRD supprime toutes les ressources de ce type du cluster, y compris celles créées par d'autres.
• Les objets portant l'annotation helm.sh/resource-policy: keep, que l'auteur d'un chart pose sur ce qu'il juge dangereux de supprimer (un volume persistant, par exemple).
• Les objets créés hors de la release, y compris les volumes créés dynamiquement par un StatefulSet (volumeClaimTemplates) : les PVC d'un StatefulSet ne sont pas supprimés avec lui.
• Les namespaces créés par --create-namespace.

Le dernier point, et celui qui pose problème en pratique : une désinstallation puis une nouvelle installation du même chart retrouvent des objets qui appartenaient à l'ancienne release. Lisez ce qui reste (kubectl get all,pvc,crd) avant de recommencer.

En pratique

Les enchaînements ci-dessous se rejouent sur le cluster kind formation, avec le chart de Signalements que vous écrivez à la leçon 4. Les sorties des commandes qui parlent au cluster sont décrites.

Un cycle complet

$ helm upgrade --install signalements ./signalements -n signalements --create-namespace \
    --set databaseSecretName=signalements-db --wait
$ helm history signalements -n signalements

La première commande installe (la release n'existe pas encore), à la révision 1. helm history montre une ligne : révision 1, état deployed, description Install complete.

Mettons à jour le nombre de répliques, puis l'image :

$ helm upgrade --install signalements ./signalements -n signalements \
    --set databaseSecretName=signalements-db --set replicaCount=3 --wait
$ helm upgrade --install signalements ./signalements -n signalements \
    --set databaseSecretName=signalements-db --set replicaCount=3 --set image.tag=9.9.9 --timeout 90s --wait

Le premier upgrade crée la révision 2 : le Deployment passe à trois répliques. Le second crée la révision 3 avec une image qui n'existe pas. Le Deployment crée un pod qui reste en ImagePullBackOff, et comme le Deployment est réglé sur maxUnavailable: 0, les anciens pods continuent de servir (leçon 5 du cours Kubernetes). Au bout de 90 secondes, helm upgrade s'arrête avec une erreur de délai d'attente (context deadline exceeded). La révision 3 est enregistrée à l'état failed : Helm a envoyé les objets, mais l'attente a échoué.

$ helm history signalements -n signalements

Vous devez y lire trois révisions : la 1 superseded, la 2 deployed, la 3 failed. Pourquoi la 2 est-elle encore deployed ? Parce que Helm ne marque une révision comme deployed que si l'opération réussit : la dernière réussie reste la référence. Pourtant, les objets du cluster sont ceux de la révision 3, avec l'image impossible à tirer. C'est un état incohérent à connaître : helm list dit « deployed, révision 3 failed » selon la colonne, et le cluster ne ressemble ni tout à fait à l'une ni tout à fait à l'autre.

On revient en arrière :

$ helm rollback signalements 2 -n signalements --wait
$ helm history signalements -n signalements

La révision 4 apparaît : état deployed, description Rollback to 2. La révision 3 reste failed dans l'historique, ce qui trace l'incident. Avec --atomic (ou --rollback-on-failure) sur la mise à jour, ce retour arrière aurait été fait automatiquement, et l'historique aurait montré la révision 3 en échec puis la 4 en retour arrière.

Retrouver ce qui a été déployé

$ helm get values signalements -n signalements --revision 2
$ helm get manifest signalements -n signalements --revision 2 | grep image:
$ diff <(helm get manifest signalements -n signalements --revision 2) \
       <(helm get manifest signalements -n signalements --revision 3)

La première commande affiche les valeurs fournies à la révision 2 (databaseSecretName et replicaCount), la deuxième l'image qui tournait, la troisième ce qui a changé entre la bonne et la mauvaise : ici, une seule ligne, l'étiquette de l'image. C'est la méthode d'enquête de tout incident lié à Helm.

Sous le capot

Le stockage des releases

Le client écrit l'enregistrement de la release dans un objet du cluster, choisi par la variable d'environnement HELM_DRIVER : secret (par défaut), configmap, ou sql pour une base externe. Le code de Helm 3.16.3 (pkg/storage/driver/util.go) sérialise la structure en JSON, la compresse avec gzip au niveau maximal, puis l'encode en base64 : c'est le contenu du champ release du Secret. Chaque révision a son propre Secret, sh.helm.release.v1.<nom>.v<révision>, d'où la limite de dix révisions par défaut : sans elle, l'espace et le nombre d'objets croîtraient sans fin. La documentation signale qu'un enregistrement de plus de 1 Mio ne tient pas dans un Secret (limite d'etcd), ce qui arrive avec de très gros charts.

Conséquence pratique : sauvegarder ou migrer une release, c'est sauvegarder ces Secrets. Et supprimer le namespace supprime l'historique avec lui.

Comment une mise à jour est calculée

C'est le cœur de Helm 3, et la page des changements depuis Helm 2 le résume : Helm « considers the old manifest, its live state, and the new manifest when generating a patch ». C'est la fusion à trois voies (three-way merge).

Pour chaque objet du nouveau manifeste, Helm dispose de trois versions :

1. L'ancien manifeste : ce que Helm avait envoyé à la révision précédente (lu dans l'enregistrement de la release).
2. L'état actuel : l'objet tel qu'il est dans le cluster, lu par l'API, avec les modifications d'autres acteurs.
3. Le nouveau manifeste : ce que le chart produit maintenant.

Il calcule un correctif qui, appliqué à l'état actuel, le rapproche du nouveau manifeste. Les règles, d'après le code (pkg/kube/client.go, qui s'appuie sur la fusion stratégique de Kubernetes) :

• Un champ qui diffère entre le nouveau manifeste et l'état actuel est réécrit avec la valeur du nouveau manifeste, même si l'ancien manifeste avait déjà cette valeur. C'est l'exemple de la documentation : quelqu'un met à zéro les répliques d'un Deployment à la main, la mise à jour suivante remet la valeur du chart.
• Un champ présent dans l'ancien manifeste et absent du nouveau est supprimé.
• Un champ absent des deux manifestes et ajouté par quelqu'un d'autre est conservé. C'est le cas d'un conteneur auxiliaire injecté par un service mesh, ou d'une annotation posée par un outil.
• Un objet absent du cluster est recréé : le code de mise à jour, quand il ne trouve pas l'objet dans le cluster, le crée. Si vous supprimez un Service à la main, la mise à jour suivante le recrée.
• Un objet présent dans l'ancien manifeste et absent du nouveau est supprimé de la release.

Tout cela s'applique au moment d'un helm upgrade et à ce moment seulement. Entre deux mises à jour, les modifications manuelles vivent en paix, et Helm n'en sait rien. Ce n'est pas de la réconciliation (leçon 1) : c'est un nettoyage opportuniste. Une conséquence souvent mal comprise : si vous corrigez un champ à la main et que le chart définit ce champ avec une autre valeur, la correction disparaît à la prochaine mise à jour, sans avertissement. Si le chart ne définit pas le champ, elle survit.

--reuse-values, --reset-values, et ce qu'on obtient sans option

Voici ce que fait helm upgrade des valeurs, d'après pkg/action/upgrade.go (Helm 3.16.3). Le cas par défaut surprend.

• Sans option, et sans aucune valeur fournie (ni -f, ni --set) : Helm réutilise les valeurs fournies à la révision précédente. helm upgrade signalements ./signalements seul conserve donc votre configuration.
• Sans option, avec au moins une valeur fournie : Helm n'utilise que celles-ci, plus les défauts du nouveau chart. Les valeurs de la révision précédente sont oubliées. Un helm upgrade ... --set image.tag=1.3.0 sans rappeler le reste des valeurs remet tout le reste aux défauts : les répliques redeviennent 2, le nom d'hôte de la route disparaît. C'est la cause la plus fréquente de mauvaise surprise, et la raison pour laquelle il faut toujours repasser le même fichier de valeurs.
• --reuse-values : « when upgrading, reuse the last release's values and merge in any overrides from the command line ». Il réutilise les valeurs précédentes et applique vos nouvelles par-dessus. Mais, d'après le code, il remplace aussi les défauts du chart par ceux de l'ancienne version du chart : si le nouveau chart ajoute une valeur (avec son défaut), elle n'existe pas dans le calcul. Le modèle qui la lit reçoit alors une valeur absente, et l'on obtient des erreurs du type nil pointer evaluating interface {}, ou, pire, un comportement par défaut silencieusement faux. À éviter lors d'un changement de version de chart.
• --reset-values : les valeurs reviennent à celles du chart, plus celles de la commande. C'est le comportement le plus prévisible quand on repasse son fichier de valeurs.
• --reset-then-reuse-values (Helm 3.14 et suivants) : « reset the values to the ones built into the chart, apply the last release's values and merge in any overrides from the command line ». Il prend les défauts du nouveau chart, puis y applique les valeurs de la révision précédente, puis la ligne de commande. C'est le seul mode qui combine « mon ancienne configuration » et « les nouveaux défauts ».

La pratique recommandée est de n'utiliser aucune de ces options : un fichier de valeurs versionné, repassé à chaque commande. La release devient alors fonction du chart et du fichier, rien d'autre.

Application côté serveur (Helm 4)

Avec Helm 3, Helm calcule lui-même le correctif (c'est la fusion à trois voies ci-dessus) et l'envoie : c'est l'application côté client (client-side apply). Helm 4 ajoute l'application côté serveur (server-side apply, SSA) : Helm envoie les manifestes complets à l'API, et c'est le serveur qui fusionne, en suivant pour chaque champ qui en est le propriétaire (le gestionnaire de champ, ici Helm). Si deux acteurs veulent écrire un même champ avec des valeurs différentes, le serveur signale un conflit au lieu d'écraser en silence. L'option --force-conflicts demande à Helm de prendre le champ de force.

Les règles de Helm 4, d'après sa documentation :

• Une nouvelle installation utilise l'application côté serveur par défaut.
• Une mise à jour suit la méthode de la release précédente : une release créée avec Helm 3 reste en application côté client après le passage à Helm 4. L'option --server-side permet de choisir explicitement.

Effets à anticiper : un champ modifié à la main par un autre outil peut maintenant produire un conflit à la mise à jour, là où Helm 3 l'écrasait ou le conservait selon la règle des trois voies. C'est plus sûr et plus bavard. Et un outil qui se pense propriétaire d'un champ (un autoscaler pour replicas, par exemple) ne sera plus écrasé par Helm si le chart ne le définit pas. Le changement n'est pas anodin ; testez-le sur un cluster de recette avant de basculer un parc.

Pièges courants

Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress. Une opération précédente a été interrompue (CI tuée, connexion perdue) : sa révision est restée à l'état pending-install, pending-upgrade ou pending-rollback, et Helm refuse d'en lancer une autre. Diagnostic : helm history montre la révision bloquée. Remèdes : helm rollback vers la dernière révision saine (si une existe), ou, en dernier recours, supprimer le Secret de la révision pending (kubectl delete secret sh.helm.release.v1.<nom>.v<N>) après avoir vérifié qu'aucune commande Helm ne tourne encore.

Error: UPGRADE FAILED: "x" has no deployed releases. La première installation a échoué, et aucune révision n'est deployed. Une mise à jour ne peut pas partir de rien : désinstallez (helm uninstall x), corrigez, réinstallez ; ou utilisez helm upgrade --install --atomic, qui nettoie lui-même.

rendered manifests contain a resource that already exists. Unable to continue with install: ... exists and cannot be imported into the current release: invalid ownership metadata. Un objet que le chart veut créer existe déjà et n'appartient pas à cette release : il lui manque les étiquette et annotations que Helm pose (app.kubernetes.io/managed-by: Helm, meta.helm.sh/release-name, meta.helm.sh/release-namespace). Soit vous renommez l'objet, soit vous l'adoptez en posant ces métadonnées à la main, soit, avec les versions récentes, vous passez --take-ownership à upgrade, qui ignore la vérification des annotations. Cette erreur apparaît typiquement quand des manifestes bruts sont convertis en chart.

Une mise à jour qui perd la configuration. Voir plus haut : --set sans repasser le fichier de valeurs. Vérifiez toujours avec helm get values après une mise à jour manuelle.

Prendre deployed pour « en bonne santé ». L'état d'une release dit que la dernière commande a réussi, pas que les pods tournent. Sans --wait, il dit même moins.

Sécurité

• Le Secret de release est un secret. Il contient le chart (modèles compris), vos valeurs et les manifestes rendus. Si un manifeste contient un Secret en clair (un chart qui crée un Secret depuis une valeur), son contenu est dans le Secret de release. Le droit de lire les Secrets d'un namespace donne donc accès à toutes les valeurs de toutes ses releases. Cloisonnez ce droit.
• L'historique garde les valeurs anciennes. Un mot de passe passé en valeur, puis changé, reste lisible dans les révisions précédentes tant qu'elles existent. Une rotation de secret s'accompagne d'une purge de l'historique (--history-max 1 temporairement, ou helm uninstall avec reconstruction) si le secret est passé par les valeurs, une raison de plus de ne pas le faire.
• helm rollback n'est pas un geste sans conséquence. Revenir à une version peut réintroduire une faille corrigée entre-temps. C'est un geste d'urgence, suivi d'une correction vers l'avant.
• Droits de la CI. Le compte qui fait helm upgrade doit pouvoir lire et écrire les Secrets de release et créer les objets du chart : c'est un compte puissant dans son namespace. Limitez-le à ce namespace, et ne lui donnez jamais de droits sur les autres.

En production

• Toujours helm upgrade --install --atomic --timeout dans les pipelines, avec le même fichier de valeurs à chaque exécution et une version de chart épinglée. C'est idempotent, et un échec ne laisse pas de demi-état.
• Aucune modification manuelle. Corriger un objet à la main en urgence est parfois nécessaire ; reportez ensuite la correction dans les valeurs ou dans le chart, sinon la mise à jour suivante la défait (ou, avec Helm 4 et l'application côté serveur, la signale en conflit).
• Limiter l'historique. --history-max 5 à dix est raisonnable : assez pour revenir de quelques révisions, sans accumuler les Secrets.
• Superviser les révisions en échec ou bloquées. Un pending-upgrade qui dure plus de quelques minutes est un incident de pipeline.
• Ne pas désinstaller une release de production pour la « refaire ». Avec des volumes, des CRD et des objets conservés, une réinstallation n'est pas un retour à zéro.
• Chez Lyneko, le rôle de helm upgrade est tenu par Argo CD, qui ne crée pas de release Helm : il rend les manifestes et les applique lui-même. helm list ne montre donc rien pour les applications déployées ainsi, et il n'y a ni historique Helm ni helm rollback : le retour arrière est un git revert (leçon 10). Ce que cette leçon vous apprend sert pour les installations manuelles de recette, pour comprendre les charts installés autrement, et pour toute équipe qui déploie avec helm upgrade depuis sa CI.

Exercices

1. Compter les révisions (niveau 100). Une release est installée (révision 1), mise à jour deux fois, puis on lance helm rollback signalements 1. À quelle révision est-on, quel est son état, et quelles sont les révisions superseded ?

2. Une mise à jour qui efface la configuration (niveau 200). Le fichier valeurs-prod.yaml fixe replicaCount: 4 et route.hostname: signalements.exemple.fr. Un collègue lance helm upgrade signalements ./signalements -n prod --set image.tag=1.2.1. Que deviennent le nombre de répliques et le nom d'hôte, et que fallait-il écrire ?

3. Que devient la correction manuelle (niveau 200). Pendant un incident, vous passez le Deployment à six répliques avec kubectl scale. Le chart définit replicas: {{ .Values.replicaCount }} (valeur 2). Quelle sera la valeur après un helm upgrade qui ne change que l'étiquette de l'image, avec Helm 3 ? Et si le chart ne définissait pas replicas du tout (laissé à un HorizontalPodAutoscaler) ?

4. Lire la mémoire d'une release (niveau 200). Écrivez la commande qui affiche, depuis le cluster, les valeurs fournies à la révision 2 de la release signalements du namespace prod, sans utiliser helm. Pourquoi un seul base64 -d ne suffit-il pas ?

Récapitulatif

• Une release a des révisions numérotées ; chaque install, upgrade et rollback en crée une, et le retour arrière avance (nouvelle révision) au lieu de reculer.
• helm list, status, get values, get manifest, get notes lisent l'enregistrement de la release, pas l'état réel des objets ; sans -n, seul le namespace du contexte est vu.
• helm upgrade --install --atomic --wait --timeout, avec le même fichier de valeurs et une version épinglée, est la commande rejouable des pipelines.
• Les releases sont stockées dans des Secrets sh.helm.release.v1.<nom>.v<N> (JSON compressé en gzip, encodé en base64) ; dix révisions sont gardées par défaut ; ces Secrets contiennent vos valeurs et se protègent comme tels.
• La mise à jour utilise une fusion à trois voies : ancien manifeste, état actuel, nouveau manifeste. Un champ défini par le chart est remis à sa valeur ; un champ que le chart ne définit pas est conservé ; un objet manquant est recréé. Tout cela n'a lieu qu'au moment d'un upgrade.
• Sans option, un upgrade avec au moins une valeur oublie les valeurs précédentes ; --reuse-values garde les anciens défauts du chart ; --reset-then-reuse-values combine ancien réglage et nouveaux défauts.
• helm uninstall supprime l'historique sauf --keep-history, et laisse les CRD, les objets resource-policy: keep et les volumes des StatefulSets.
• Helm 4 applique côté serveur pour les nouvelles installations et suit la méthode précédente pour les mises à jour ; les conflits de propriété sont signalés.

Pour aller plus loin

• La page Changes since Helm 2 de la documentation, pour les exemples officiels de la fusion à trois voies.
• Le fichier pkg/action/upgrade.go du dépôt helm/helm, et en particulier la fonction reuseValues, qui tient en trente lignes.
• La documentation de Kubernetes sur Server-Side Apply, pour comprendre la propriété des champs et les conflits.
• La leçon suivante, Écrire un chart, qui transforme les manifestes de Signalements en chart.