Helm v4 : changements, breaking changes et migration depuis Helm v3

Helm v4 apporte des changements importants qui peuvent casser vos pipelines CI/CD si vous ne les anticipez pas. Ce guide liste tout ce qui change, avec les commandes exactes pour adapter vos scripts. Vous apprendrez à identifier les incompatibilités, tester votre migration en staging, et basculer sans incident en production.

Ce que vous allez apprendre

• Identifier les flags renommés et les corriger (--atomic → --rollback-on-failure)
• Migrer vos post-renderers vers le système de plugins
• Comprendre le nouveau comportement de --dry-run et --wait
• Activer Server-Side Apply (SSA) et gérer les conflits
• Adapter l’authentification OCI et utiliser les digests
• Planifier votre migration avec une checklist CI/CD

Support Helm v3 — dates à retenir

Helm v3 reste supporté :

• Bugfix : jusqu’au 8 juillet 2026
• Security fix : jusqu’au 11 novembre 2026

Planifiez votre migration avant la fin du support sécurité.

---

Ce qui casse en migration (checklist rapide)

Avant de lire le détail, voici une checklist des breaking changes à vérifier dans vos scripts :

Ce qui change	v3	v4	Impact
Rollback automatique	--atomic	--rollback-on-failure	Scripts CI/CD
Forcer remplacement	--force	--force-replace	Scripts upgrade
Post-renderer	--post-renderer ./script	--post-renderer plugin-name	Pipelines avec kustomize
Dry-run	--dry-run (booléen)	--dry-run=client|server	Tests avant déploiement
Wait	--wait (booléen)	--wait=watcher|legacy	Attente pods ready
Server-Side Apply	Opt-in	Activé par défaut	Conflits ownership
OCI login	URL complète acceptée	Domaine uniquement	Auth registries

Glissez pour voir

Commande rapide pour vérifier

Cherchez ces patterns dans vos pipelines :

grep -rn --include="*.yml" --include="*.yaml" --include="*.sh" \
  -E "(--atomic|--force[^-]|--post-renderer|--dry-run[^=])" .

---

Changements CLI majeurs

Flags renommés

--atomic → --rollback-on-failure

Le flag --atomic existe toujours mais est déprécié. Utilisez --rollback-on-failure :

Helm v3 (ancien)

helm upgrade --install myapp ./chart \
  --atomic \
  --wait \
  --timeout 5m

Helm v4 (nouveau)

helm upgrade --install myapp ./chart \
  --rollback-on-failure \
  --wait \
  --timeout 5m

Comportement : Si le déploiement échoue (pods non Ready dans le timeout), Helm effectue automatiquement un rollback vers la révision précédente.

Note importante

Quand --rollback-on-failure est activé, le flag --wait passe automatiquement en mode watcher (voir section Wait ci-dessous).

--force → --force-replace

Le flag pour forcer le remplacement des ressources a été renommé :

Helm v3 (ancien)

helm upgrade myapp ./chart --force

Helm v4 (nouveau)

helm upgrade myapp ./chart --force-replace

Quand l’utiliser : Forcer le remplacement complet d’une ressource au lieu d’un patch. Utile quand un champ immutable a changé.

Attention

--force-replace supprime et recrée la ressource. Cela cause une interruption de service pour les Deployments. Préférez recréer les pods via une annotation dans le template.

Nouveau flag --force-conflicts

En v4, un nouveau flag gère les conflits Server-Side Apply :

helm upgrade myapp ./chart --force-conflicts

Ce flag force l’application même si un autre controller (ArgoCD, Flux, kubectl) a modifié la ressource.

---

Post-renderer : migration vers plugins

Ce qui change

En Helm v3, vous pouviez passer un binaire externe :

# v3 : binaire direct (NE FONCTIONNE PLUS en v4)
helm template myapp ./chart --post-renderer ./kustomize-overlay.sh

En Helm v4, les post-renderers passent obligatoirement par le système de plugins :

# v4 : plugin installé
helm template myapp ./chart --post-renderer kustomize

Migrer un post-renderer existant

1. Convertir votre script en plugin Helm

   Créez la structure de plugin :

   mkdir -p ~/.local/share/helm/plugins/my-postrenderer

   Créez plugin.yaml :

   ~/.local/share/helm/plugins/my-postrenderer/plugin.yaml

   name: "my-postrenderer"
   version: "1.0.0"
   usage: "Post-render manifests with custom logic"
   command: "$HELM_PLUGIN_DIR/render.sh"
   postRenderer: true

2. Déplacer votre script

   Copiez votre script existant :

   cp ./kustomize-overlay.sh ~/.local/share/helm/plugins/my-postrenderer/render.sh
   chmod +x ~/.local/share/helm/plugins/my-postrenderer/render.sh

3. Vérifier l’installation

   helm plugin list

   Sortie attendue :

   NAME              VERSION   DESCRIPTION
   my-postrenderer   1.0.0     Post-render manifests with custom logic

4. Utiliser le plugin

   helm template myapp ./chart --post-renderer my-postrenderer

Passer des arguments au post-renderer

Utilisez --post-renderer-args :

helm upgrade --install myapp ./chart \
  --post-renderer kustomize \
  --post-renderer-args "--enable-helm" \
  --post-renderer-args "--load-restrictor=LoadRestrictionsNone"

Plugin kustomize officiel

Un plugin officiel helm-post-renderer-kustomize est disponible. Installez-le :

helm plugin install https://github.com/helm/helm-post-renderer-kustomize

---

Dry-run et validation

Nouveau comportement de --dry-run

En v3, --dry-run était un booléen. En v4, c’est une option à valeurs :

Valeur	Comportement	Connexion cluster
--dry-run=none	Exécution normale (défaut si omis)	Oui
--dry-run=client	Simulation côté client uniquement	Non
--dry-run=server	Simulation côté serveur	Oui
--dry-run (sans valeur)	Équivalent à --dry-run=client	Non

Glissez pour voir

Recommandation : Utilisez toujours la forme explicite pour éviter les ambiguïtés.

# Validation sans cluster (rapide, offline)
helm upgrade --install myapp ./chart --dry-run=client

# Validation avec le cluster (vérifie schémas, RBAC, quotas)
helm upgrade --install myapp ./chart --dry-run=server

Masquer les secrets en dry-run

Le flag --hide-secret masque les valeurs des Secrets dans la sortie :

helm template myapp ./chart --dry-run=client --hide-secret

Sécurité CI/CD

En CI/CD, utilisez toujours --hide-secret pour éviter de logger des credentials dans les artifacts de build.

---

Server-Side Apply (SSA)

Ce qui change

En v3 : Client-Side Apply (kubectl apply côté client) En v4 : Server-Side Apply activé par défaut (--server-side=true)

SSA délègue la logique de merge au serveur Kubernetes, ce qui apporte :

• Meilleure gestion des conflits : détection si un autre controller a modifié la ressource
• Ownership tracking : Kubernetes sait qui a créé chaque champ
• Dry-run serveur : validation plus précise

Gérer les conflits

Si un autre outil (ArgoCD, kubectl, opérateur) a modifié une ressource, vous verrez :

Error: UPGRADE FAILED: cannot patch "myapp" with kind Deployment:
Apply failed with 1 conflict: conflict with "argocd-application-controller"

Solutions :

1. Forcer l’ownership (si Helm doit prendre le contrôle) :

   helm upgrade myapp ./chart --force-conflicts

2. Désactiver SSA (temporairement, pour debug) :

   helm upgrade myapp ./chart --server-side=false

Attention avec ArgoCD/Flux

Si vous utilisez un outil GitOps, coordonnez l’ownership des ressources. Soit Helm gère tout, soit l’outil GitOps. Le mélange crée des conflits.

Vérifier le mode actuel

helm upgrade myapp ./chart --dry-run=server 2>&1 | grep -i "server-side"

---

Wait avec kstatus (watcher)

Nouveau comportement de --wait

En v3, --wait attendait que les ressources soient “Ready” selon une logique interne. En v4, vous choisissez la stratégie :

Valeur	Comportement
--wait=hookOnly	Attend seulement les hooks (défaut)
--wait=watcher	Utilise kstatus pour surveiller l’état réel
--wait=legacy	Comportement v3 (rétrocompatibilité)

Glissez pour voir

Pourquoi préférer watcher ?

Le mode watcher utilise kstatus qui comprend mieux l’état des ressources Kubernetes :

• Détecte les CRDs avec des conditions personnalisées
• Comprend les états intermédiaires (Progressing, Degraded)
• Gère les ressources non-standard (Argo Rollouts, Knative, etc.)

helm upgrade --install myapp ./chart \
  --wait=watcher \
  --timeout 5m

Note

Quand --rollback-on-failure est activé, --wait passe automatiquement en mode watcher.

Attendre les Jobs

Le flag --wait-for-jobs reste disponible :

helm upgrade --install myapp ./chart \
  --wait=watcher \
  --wait-for-jobs \
  --timeout 10m

---

OCI : authentification et digests

Changement d’authentification

En v4, helm registry login attend uniquement le domaine, pas une URL complète :

Helm v3 (acceptait)

# Fonctionnait en v3
helm registry login oci://ghcr.io/myorg/charts

Helm v4 (requis)

# v4 : domaine uniquement
helm registry login ghcr.io

Pattern CI/CD recommandé :

echo "$REGISTRY_TOKEN" | helm registry login ghcr.io -u "$REGISTRY_USER" --password-stdin

Installation par digest

Helm v4 supporte l’installation par digest SHA256 pour des déploiements reproductibles :

# Par tag (peut changer si le tag est réécrit)
helm install myapp oci://ghcr.io/myorg/charts/myapp --version 1.2.3

# Par digest (immuable, recommandé pour prod)
helm install myapp oci://ghcr.io/myorg/charts/myapp@sha256:abc123...

Obtenir le digest d’un chart :

helm pull oci://ghcr.io/myorg/charts/myapp --version 1.2.3 2>&1 | grep Digest

Bonnes pratiques

En production, épinglez par digest pour garantir que le même chart est déployé partout, même si le tag est mis à jour.

---

Plan de migration recommandé

1. Auditer vos scripts

   Cherchez les patterns à mettre à jour :

   # Dans vos repos CI/CD
   grep -rn --include="*.yml" --include="*.yaml" --include="*.sh" \
     -E "(--atomic|--force[^-]|--post-renderer [^-]|--dry-run[^=])" .

2. Installer Helm v4 en parallèle

   Testez sans remplacer v3 :

   # Installer v4 dans un chemin dédié
   curl -fsSL https://get.helm.sh/helm-v4.1.0-linux-amd64.tar.gz | \
     tar -xz && mv linux-amd64/helm /usr/local/bin/helm4
   
   # Tester
   helm4 version

3. Tester en environnement de dev

   # Comparer les manifests générés
   helm3 template myapp ./chart -f values.yaml > v3-manifests.yaml
   helm4 template myapp ./chart -f values.yaml > v4-manifests.yaml
   diff v3-manifests.yaml v4-manifests.yaml

4. Migrer les post-renderers

   Si vous utilisez --post-renderer, convertissez en plugin (voir section dédiée).

5. Adapter les flags dans CI/CD

   Mettez à jour vos pipelines :

   .gitlab-ci.yml

   deploy:
     script:
       # Avant (v3)
       # - helm upgrade --install myapp ./chart --atomic --wait
   
       # Après (v4)
       - helm upgrade --install myapp ./chart --rollback-on-failure --wait=watcher

6. Déployer en staging

   Testez le cycle complet :

   • Install → Upgrade → Rollback → Uninstall

7. Basculer en production

   Une fois validé en staging, mettez à jour Helm et les scripts en production.

---

Dépannage v4

Symptôme	Cause	Solution
unknown flag: --atomic	Helm v4 avec ancien flag	Remplacer par --rollback-on-failure
unknown flag: --force	Helm v4 avec ancien flag	Remplacer par --force-replace
Apply failed with conflict	SSA détecte une modification externe	Utiliser --force-conflicts ou coordonner l’ownership
post-renderer plugin not found	Post-renderer non migré	Convertir en plugin Helm
Error: login requires exactly one argument	URL au lieu du domaine	Utiliser seulement le domaine (ghcr.io)
--dry-run flag needs an argument	Syntaxe v3	Utiliser --dry-run=client ou --dry-run=server
Pods non détectés comme Ready	Mode wait legacy	Utiliser --wait=watcher

Glissez pour voir

Vérifier la version de Helm

helm version

Sortie attendue (v4) :

version.BuildInfo{Version:"v4.1.0", GitCommit:"...", GoVersion:"go1.25.6", KubeClientVersion:"v1.35"}

Forcer le comportement v3 (temporaire)

Si vous devez rester compatible temporairement :

helm upgrade --install myapp ./chart \
  --server-side=false \
  --wait=legacy

Ne pas rester en mode legacy

Le mode legacy est fourni pour faciliter la migration. Planifiez la mise à jour de vos scripts pour utiliser les nouveaux comportements.

---

À retenir

Changement	Action requise
--atomic → --rollback-on-failure	Rechercher/remplacer dans tous les scripts
--force → --force-replace	Rechercher/remplacer
Post-renderer binaire → plugin	Créer un plugin Helm
--dry-run → --dry-run=client|server	Spécifier explicitement la valeur
SSA activé par défaut	Gérer les conflits ownership
--wait → --wait=watcher	Utiliser pour meilleure détection Ready
OCI login : domaine seul	Adapter les scripts de login

Glissez pour voir

Checklist migration CI/CD

1. ✅ Grep pour --atomic, --force, --post-renderer, --dry-run
2. ✅ Tester helm template v3 vs v4 (diff)
3. ✅ Migrer post-renderers en plugins
4. ✅ Adapter authentification OCI
5. ✅ Tester en staging (cycle complet)
6. ✅ Basculer production

---

Prochaines étapes

Référence commande Helm Toutes les options de helm install, upgrade, rollback

CI/CD avec Helm Patterns de déploiement et packaging

Déboguer Helm Méthode de triage et résolution d'erreurs

Formation Helm complète 12 modules progressifs avec labs

×

📖 Voir la documentation →