Mise à niveau et migration Helm : guide opérationnel pratique

Introduction

Les mises à niveau et migrations Helm sont des tâches quotidiennes pour les opérateurs Kubernetes, mais elles restent une source majeure d'incidents de production et d'appels nocturnes. Une version qui fonctionnait sous Helm 3.9 peut se comporter différemment sous Helm 3.12 ; un chart qui semble simple peut embarquer des CRDs (Custom Resource Definitions) non prêtes pour la production ; une « mise à niveau rapide » peut se transformer en intervention d'urgence impliquant plusieurs équipes.

Ce guide vous propose une démarche reproductible et sûre pour les travaux de mise à niveau et de migration Helm. Il s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui exécutent Helm dans Kubernetes et souhaitent passer d'un « ça marchait sur ma machine » à un déploiement vérifié et récupérable. Vous apprendrez à inventorier votre état actuel avant de toucher quoi que ce soit, à préparer les changements de configuration en toute sécurité, à vérifier une mise à niveau avec des commandes concrètes et les sorties attendues, à diagnostiquer les échecs, à revenir en arrière ou récupérer lorsque les choses tournent mal, et à maintenir une liste de contrôle opérationnelle qui transforme chaque mise à niveau Helm en un événement contrôlé et auditable.

L'idée centrale est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter la récupération si l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant d'exécuter helm upgrade, vous avez besoin d'un inventaire précis de ce qui est installé, où cela s'exécute et quelles frontières de versions vous franchissez. Sauter cette étape revient à opérer sans avoir lu le dossier médical.

Capturer l'état actuel

Commencez par des commandes en lecture seule qui enregistrent la version actuelle du client Helm, la version du cluster Kubernetes et l'état de la release. Ne vous fiez pas à la mémoire ni à une capture d'écran du mois dernier ; le cluster évolue.

# Version du client Helm
helm version --short
# Exemple de sortie : v3.12.0+g1f7d5d5

# Version du serveur Kubernetes (via kubectl)
kubectl version --short
# Exemple de sortie : Client Version: v1.25.0, Server Version: v1.27.3

# Lister toutes les releases dans le namespace courant
helm list --namespace production
# Exemple de sortie :
# NAME      NAMESPACE   REVISION   UPDATED                                  STATUS     CHART           APP VERSION
# payments  production  12         2024-01-15 14:03:22.123456 +0000 UTC  deployed   payments-1.4.2 1.4.0

Enregistrez la sortie avec un horodatage et un identifiant unique pour le cluster et le namespace. C'est votre référence de base.

Identifier la topologie de déploiement

Cartographiez maintenant la release vers ses ressources sous-jacentes. Utilisez helm get pour extraire les manifestes rendus et voir ce que le chart a réellement déployé.

# Afficher les objets Kubernetes rendus pour la release
helm get manifest payments --namespace production | less

Recherchez :

• Les noms des Deployments, StatefulSets, DaemonSets, Services, Ingresses, ConfigMaps et Secrets.
• Les Custom Resource Definitions (CRDs) que le chart a pu installer. Les CRDs sont dangereuses car ce sont des ressources globales du cluster et elles ne sont pas supprimées par défaut lors de la désinstallation d'une release.
• Les demandes et limites de ressources qui pourraient empêcher l'ordonnancement ou provoquer une éviction pendant la mise à niveau.

Exemple de découverte critique : vous voyez une CRD nommée prometheusrules.monitoring.coreos.com installée par un ancien chart Prometheus Operator. Si vous migrez loin de ce chart, cette CRD peut subsister et bloquer l'installation du nouveau chart.

Comprendre les frontières de versions

Vérifiez la matrice de compatibilité Helm avant de mettre à niveau. Helm garantit la compatibilité entre le client et le serveur Kubernetes dans une plage étroite. Par exemple, Helm 3.9 prend en charge Kubernetes 1.21 à 1.24 ; Helm 3.12 prend en charge Kubernetes 1.24 à 1.27. Utiliser un client Helm plus récent que l'API du cluster peut provoquer un comportement inattendu.

Au sein d'un projet de chart, lisez les fichiers Chart.yaml et values.schema.json du chart pour voir les changements cassants entre la version installée et la version cible. Cherchez :

• Les changements dans les valeurs par défaut qui modifient les noms des ressources.
• Les nouveaux champs obligatoires dans le fichier de valeurs.
• La suppression ou le renommage de champs existants.
• Les modifications de champs immuables (par exemple, les modèles de revendication de volume d'un StatefulSet) qui forcent une suppression/recréation.

Documentez cela sous forme d'un petit tableau :

Définir le résultat attendu et le signal d'échec

Avant d'exécuter tout changement, écrivez exactement ce que vous attendez comme résultat et ce qui indiquerait un échec. Par exemple :

• Résultat attendu : helm list montre une REVISION augmentée de 1 et un STATUT deployed ; kubectl rollout status deployment/payments renvoie successfully rolled out.
• Signal d'échec : helm upgrade renvoie un code de sortie non nul ; kubectl get pods montre CrashLoopBackOff ou ImagePullBackOff pour les nouveaux pods ; helm list montre un STATUT failed.

Ce contrat explicite transforme un vague « est-ce que ça a marché ? » en un contrôle de réussite/échec.

Parcours de configuration sécurisé

Les mises à niveau Helm échouent souvent parce que quelqu'un a changé trop de choses à la fois. La solution consiste à échelonner les changements et à utiliser les mécanismes intégrés de Helm pour réduire le risque.

Utiliser des surcharges de valeurs explicites

Ne comptez jamais sur les valeurs par défaut pour ce qui compte. Fournissez toujours des surcharges via --set ou un fichier de valeurs. Préférez un fichier de valeurs pour tout ce qui n'est pas trivial, car il peut être versionné et revu.

Exemple de overrides.yaml minimal pour la mise à niveau d'un service de paiement :

# overrides.yaml
replicaCount: 3
image:
  repository: registry.example.com/payments
  tag: 1.6.0
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: "8080"   # note : chaîne, car le chart cible 1.6.0 attend une chaîne
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

Exécutez d'abord la mise à niveau avec un essai à blanc :

# Essai à blanc pour voir ce qui changerait
helm upgrade payments ./payments-chart --namespace production --values overrides.yaml --dry-run --debug

Puis appliquez réellement :

helm upgrade payments ./payments-chart --namespace production --values overrides.yaml --atomic --timeout 5m

Le drapeau --atomic annule automatiquement la release si la mise à niveau échoue, ce qui constitue un filet de sécurité simple.

Limiter le rayon d'impact avec des namespaces de préproduction

Si vous n'êtes pas sûr des changements du chart, testez la mise à niveau dans un namespace de préproduction dédié avant de toucher à la production. Vous pouvez utiliser le même chart et une copie du fichier de valeurs avec un tag d'image ou des limites de ressources différentes.

# Créer un namespace de préproduction
kubectl create namespace payments-staging

# Installer la nouvelle version du chart là-bas
helm install payments-staging ./payments-chart --namespace payments-staging --values staging-values.yaml

# Vérifier
kubectl --namespace payments-staging rollout status deployment/payments-staging

Cela ne teste pas les données de production ni les modèles de trafic, mais cela détecte les erreurs de syntaxe, les valeurs obligatoires manquantes et les erreurs de template évidentes.

Gérer correctement les secrets

Ne mettez jamais de vrais secrets dans un fichier de valeurs qui sera commité dans Git. Utilisez les Secrets Kubernetes ou un outil de gestion des secrets. Si le chart exige une valeur secrète pour la mise à niveau (par exemple, un changement de mot de passe de base de données), référencez un Secret existant au lieu de passer la valeur en ligne de commande.

Exemple de template qui attend un nom de secret :

# values.yaml
postgresql:
  existingSecret: "payments-db-credentials"
  secretKeys:
    adminPasswordKey: "password"

Assurez-vous ensuite que le Secret existe avant de mettre à niveau :

kubectl get secret payments-db-credentials --namespace production

S'il n'existe pas, créez-le avec les bonnes clés. Un échec de mise à niveau dû à un secret manquant est un échec courant et évitable.

Préserver l'historique et activer le retour en arrière

Définissez une limite d'historique raisonnable pour la release afin de pouvoir revenir en arrière si nécessaire. La valeur par défaut est 10, mais vous pouvez en vouloir davantage pour le débogage.

helm upgrade payments ./payments-chart --namespace production --values overrides.yaml --history-max 20

Après la mise à niveau, vous pouvez voir l'historique des révisions :

helm history payments --namespace production
# Exemple de sortie :
# REVISION  UPDATED                   STATUS      CHART           APP VERSION  DESCRIPTION
# 12        Mon Jan 15 15:02:11 2024  deployed    payments-1.6.0 1.6.0        Upgrade complete
# 11        Mon Jan 15 14:03:22 2024  superseded  payments-1.4.2 1.4.0        Upgrade complete

Cet historique est ce qui rend possible le retour en arrière.

Vérification et diagnostic

Après une mise à niveau, vous devez vérifier que la release n'est pas seulement « déployée » mais qu'elle fonctionne réellement. Le statut de Helm indique seulement que l'objet release a été mis à jour ; il ne garantit pas que les pods sont sains ou que le service fonctionne.

Commandes de vérification immédiates

Exécutez celles-ci immédiatement après la mise à niveau :

# 1. Vérifier le statut de la release
helm status payments --namespace production
# Chercher : STATUS: deployed, et la section NOTES avec des instructions post-installation spécifiques au chart.

# 2. Vérifier le statut de déploiement du Deployment principal
kubectl --namespace production rollout status deployment/payments
# Sortie attendue : deployment "payments" successfully rolled out

# 3. Vérifier tous les pods dans le namespace
kubectl --namespace production get pods
# Attendu : tous les pods en Running et Ready (ex. 3/3 Running)

Si un pod n'est pas prêt, décrivez-le et vérifiez les journaux :

kubectl --namespace production describe pod <pod-name>
# Regarder les Conditions, Events et Last State.
kubectl --namespace production logs <pod-name> --previous
# Affiche les journaux du conteneur planté précédent, utile pour les boucles de crash.

Validation fonctionnelle

Selon le service, exécutez un simple contrôle de santé depuis le cluster ou via un transfert de port.

# Transférer le port vers le service
kubectl --namespace production port-forward svc/payments 8080:8080 &

# Interroger un point de terminaison de santé
curl -s http://localhost:8080/health
# Attendu : {"status":"ok"}

# Tuer le transfert de port une fois terminé
kill %1

Pour une mise à niveau de base de données, exécutez une requête simple :

kubectl --namespace production exec -it <postgres-pod> -- psql -U myuser -c "SELECT 1;"
# Attendu : ?column? = 1

Surveillance et alertes

Vérifiez vos tableaux de bord de surveillance pour le taux d'erreur, la latence et l'utilisation des ressources. Comparez les métriques avant et après la mise à niveau. Si vous avez Prometheus, exécutez une requête instantanée pour les cinq minutes suivant la mise à niveau :

rate(http_requests_total{job="payments", status=~"5.."}[5m])

Si ce taux augmente, vous avez un problème même si les pods tournent.

Flux de travail de diagnostic en cas d'échec

Si quelque chose ne va pas, suivez un chemin systématique :

1. Regardez la sortie de Helm : helm upgrade imprime les erreurs et indique souvent la ressource exacte qui a échoué. Lisez les 20 dernières lignes.
2. Vérifiez le statut de la release : helm status <release> --namespace <ns> peut montrer un statut FAILED et des messages.
3. Inspectez les ressources Kubernetes : kubectl describe et kubectl get events --sort-by=.metadata.creationTimestamp dans le namespace.
4. Vérifiez les journaux des conteneurs : kubectl logs <pod>, et si le pod est en boucle de crash, ajoutez --previous.
5. Comparez avec la révision précédente : helm get manifest <release> --revision <previous-rev> --namespace <ns> pour voir ce qui a changé dans les objets rendus.
6. Regardez le diff des valeurs : helm get values <release> --namespace <ns> et comparez avec votre fichier de surcharges.

Exemple d'erreur courante :

Error: UPGRADE FAILED: cannot patch "payments" with kind Deployment: Deployment.apps "payments" is invalid: spec.selector: Invalid value: ... field is immutable

Cela signifie que le chart a tenté de modifier le sélecteur du Deployment, qui est immuable. La seule solution est de supprimer et recréer le Deployment, ce qui provoque une interruption. Pour éviter cela, vérifiez le journal des modifications du chart pour les changements de libellés de sélecteur avant de mettre à niveau.

Modes de défaillance et récupération

Même avec une planification soignée, les mises à niveau échouent. Sachez comment récupérer rapidement.

Modes de défaillance courants

1. Échec de tirage d'image : Le nouveau tag d'image n'existe pas dans le registre, ou le cluster n'a pas les identifiants de tirage. Les pods passent en ImagePullBackOff. Récupération : corrigez le tag ou le secret de tirage, puis relancez helm upgrade avec la même révision (ou utilisez --force si nécessaire).
2. Erreur de configuration : Une valeur a été mal définie, provoquant la sortie immédiate du conteneur. Les pods passent en CrashLoopBackOff. Récupération : corrigez le fichier de valeurs et relancez helm upgrade. Helm créera une nouvelle révision.
3. Épuisement des ressources : Les nouveaux pods restent en Pending en raison d'un manque de CPU/mémoire. Récupération : ajustez les demandes/limites de ressources dans les valeurs et mettez à niveau, ou réduisez manuellement les anciens pods (risqué).
4. Changement de champ immuable : Comme ci-dessus, tentative de modifier le sélecteur d'un Deployment ou le modèle de revendication de volume d'un StatefulSet. Récupération : supprimez la ressource et recréez-la via Helm (en acceptant une interruption), ou utilisez une stratégie de migration (par exemple, créez un nouveau Deployment avec un nom différent et basculez le Service).
5. Problèmes de CRD : Le chart installe une nouvelle CRD qui entre en conflit avec une existante. Récupération : vérifiez la propriété des CRD et supprimez la CRD conflictuelle si c'est sûr, ou utilisez une méthode d'installation différente.

Retour en arrière Helm : la récupération la plus rapide

Si la mise à niveau échoue ou que vous détectez un problème peu de temps après, la récupération la plus rapide est de revenir à la révision précédente.

# Revenir à la révision précédente
helm rollback payments 1 --namespace production
# Attendre le déploiement
kubectl --namespace production rollout status deployment/payments

L'argument 1 est le numéro de révision cible. Vous pouvez obtenir la liste à partir de helm history.

Le retour en arrière restaure la version précédente du chart et les valeurs. Notez que le retour en arrière n'annule pas les effets de bord externes (par exemple, les changements de schéma de base de données). Si votre chart a exécuté un job de migration qui a modifié la base de données, un retour en arrière du chart n'inversera pas le changement de base de données ; vous devez le gérer séparément.

Récupération au-delà du retour en arrière

Si le retour en arrière ne suffit pas (par exemple, la révision précédente est également cassée), vous devrez peut-être :

• Corriger manuellement les ressources Kubernetes : par exemple, supprimer un mauvais pod pour qu'un nouveau soit créé avec la même spécification.
• Utiliser --force pour recréer les ressources : helm upgrade --force supprime et recrée les ressources qui ne peuvent pas être mises à jour. Cela peut provoquer une interruption, donc à utiliser seulement si nécessaire.
• Restaurer à partir d'une sauvegarde etcd : Si l'état du cluster lui-même est corrompu, restaurez à partir d'une sauvegarde du cluster suivant votre plan de reprise après sinistre.
• Contacter le mainteneur du chart : Pour les bugs du chart, signalez le problème avec les journaux complets et votre fichier de valeurs (expurgé).

Revue post-incident

Après toute mise à niveau échouée, tenez une brève rétrospective sans blâme. Documentez :

• Quel était le changement prévu ?
• Quelle a été la défaillance observée ?
• Quelle a été la cause racine ?
• Quelle a été l'action de récupération et le temps de récupération ?
• Que faut-il changer dans le processus de mise à niveau pour éviter la récurrence ?

Ajoutez le résultat à votre runbook opérationnel.

Pièges courants et comment les éviter

Voici les erreurs les plus courantes commises par les opérateurs avec les mises à niveau et migrations Helm, avec leurs raisons et comment les éviter ou en récupérer.

1. Exécuter une mise à niveau sans essai à blanc

Pourquoi cela arrive : L'opérateur est pressé, ou pense que le changement est trivial. Comment l'éviter : Exécutez toujours helm upgrade --dry-run --debug d'abord. Cela rend les templates et montre exactement ce qui changerait. Examinez le diff pour les changements inattendus. Récupération : Si vous l'avez sauté et que la mise à niveau a échoué, revenez immédiatement en arrière puis exécutez l'essai à blanc pour comprendre ce qui s'est passé.

2. Ne pas vérifier la compatibilité des versions Helm et Kubernetes

Pourquoi cela arrive : La CLI Helm est mise à jour automatiquement, ou un nouveau cluster est provisionné avec une version différente. Comment l'éviter : Avant toute mise à niveau, exécutez helm version --short et kubectl version --short et comparez avec la matrice de compatibilité. Utilisez le bon client Helm pour la version du cluster. Récupération : Si vous avez utilisé un Helm incompatible, la mise à niveau peut avoir été partiellement appliquée ; utilisez helm rollback puis utilisez la bonne version de Helm pour refaire la mise à niveau.

3. Coder en dur des secrets dans les fichiers de valeurs

Pourquoi cela arrive : Commodité ; les développeurs mettent souvent un secret factice dans le dépôt et oublient de le remplacer. Comment l'éviter : Utilisez les Secrets Kubernetes existants et référencez-les par nom. Utilisez un outil comme sops ou sealed-secrets si les secrets doivent être stockés dans Git. Ne passez jamais de secrets via --set en ligne de commande (ils apparaissent dans l'historique du shell). Récupération : Si un secret a été exposé, faites-le tourner immédiatement, mettez à jour le Secret, puis exécutez une nouvelle mise à niveau qui utilise le nouveau secret.

4. Ignorer le cycle de vie des CRDs

Pourquoi cela arrive : Les CRDs sont installées une fois et souvent oubliées ; les charts peuvent embarquer des CRDs dans un répertoire crds/ que Helm installe mais ne met pas à niveau ni ne supprime. Comment l'éviter : Vérifiez si votre chart inclut des CRDs. Si oui, mettez à niveau les CRDs manuellement avant de mettre à niveau le chart, ou utilisez un chart qui gère les CRDs comme des releases séparées. Ne laissez jamais un chart installer des CRDs pendant une mise à niveau sans examen. Récupération : Si de mauvaises CRDs ont été installées, vous devrez peut-être les supprimer et réinstaller la bonne version. Attention : supprimer une CRD supprime toutes les ressources personnalisées de ce type.

5. Mettre à jour trop de choses à la fois

Pourquoi cela arrive : Une nouvelle version de chart change aussi les valeurs, et l'opérateur modifie plusieurs autres paramètres en même temps. Comment l'éviter : Divisez la mise à niveau en étapes plus petites. D'abord mettez à niveau la version du chart avec les mêmes valeurs (si compatible). Ensuite changez les valeurs une par une. Utilisez le contrôle de version pour suivre les changements. Récupération : Si la mise à niveau combinée échoue, revenez en arrière puis essayez une approche par étapes.

6. Ne pas définir de délai d'attente de vérification

Pourquoi cela arrive : Helm attend indéfiniment que les ressources deviennent prêtes, ce qui peut bloquer le terminal et le pipeline CI. Comment l'éviter : Définissez toujours --timeout à une valeur raisonnable (par exemple 5m0s). Utilisez --atomic pour un retour automatique en cas d'échec. En CI, n'exécutez jamais Helm sans délai d'attente. Récupération : Si une mise à niveau précédente est bloquée, vous pouvez l'interrompre (Ctrl+C) puis vérifier le statut de la release ; Helm la marquera comme échouée si elle a expiré, et vous pourrez revenir en arrière.

7. Oublier de mettre à jour le runbook opérationnel

Pourquoi cela arrive : La mise à niveau réussit, donc personne ne documente le nouvel état. Comment l'éviter : Après chaque mise à niveau réussie, mettez à jour l'inventaire des versions, la révision connue comme bonne et toutes les étapes opérationnelles modifiées dans votre runbook. Récupération : Si non documentées, les futures mises à niveau deviennent des devinettes. Commencez par capturer l'état actuel et reconstruire l'inventaire.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant, pendant et après chaque mise à niveau ou migration Helm. Chaque élément a un propriétaire explicite (une personne, pas une équipe) et une cadence de révision.

Liste de contrôle pré-mise à niveau

Liste de contrôle pendant la mise à niveau

Liste de contrôle post-mise à niveau

Utilisez cette liste de contrôle comme modèle. Adaptez-la aux conventions de nommage et aux outils de votre organisation, mais conservez les vérifications essentielles.

Conclusion

La mise à niveau et la migration Helm sont une compétence qui récompense la préparation et punit les raccourcis. La différence entre une mise à niveau de routine et une panne de production se résume souvent à savoir si vous avez vérifié la compatibilité des versions, exécuté un essai à blanc, défini un délai d'attente et préparé un plan de retour en arrière.

Dans ce guide, vous avez appris un flux de travail opérationnel complet : inventorier votre environnement, préparer les changements de configuration en toute sécurité, vérifier la mise à niveau avec des commandes et les sorties attendues, diagnostiquer les échecs méthodiquement, récupérer rapidement avec un retour en arrière ou d'autres moyens, et codifier le processus avec une liste de contrôle qui nomme les propriétaires et les cadences.

L'étape suivante consiste à appliquer cela à votre environnement. Choisissez une release Helm à faible risque, suivez la liste de contrôle et effectuez une mise à niveau sûre. Enregistrez l'état actuel, exécutez les vérifications documentées, comparez les résultats avec les signaux attendus et notez toute surprise. Ensuite, étendez aux releases plus critiques, en gardant toujours la même discipline.

Rappelez-vous : un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. C'est ainsi que vous rendez les mises à niveau Helm ennuyeuses, et en opérations, ennuyeux est bon.