DEV Community

Amaresh Pelleti
Amaresh Pelleti

Posted on • Originally published at devtoolhub.com

Helm 4 Migration Guide: What Breaks and How to Fix It Before EOL

#helm #kubernetes #devops #iac

Originally published on DevToolHub.

Helm 4 shipped in November 2025. Eight months later, most teams are still running Helm 3 in production CI/CD because it works. But Helm 3's final feature release lands September 9, 2026, and security patches stop completely on February 10, 2027.

This helm 4 migration is simpler than it looks. Your charts don't need rewriting — Helm 3 Chart API v2 charts are fully compatible with Helm 4. But the automation around Helm has four real breaking points that fail silently if you don't know where to look.

[IMAGE: articles/images/2026-07-05-helm-4-migration-guide-featured.png | alt: "helm 4 migration flow from Helm 3 to Helm 4 upgrade path"]

Why This Helm 4 Migration Matters Now

The EOL timeline has three stages, and they matter differently based on your situation:

  • September 9, 2026 — Final Helm 3 feature release (limited to Kubernetes client library updates only after this date)
  • February 10, 2027 — All security patches stop

If your organization runs regulated workloads with requirements around supported software, February 2027 is your hard deadline. But waiting until then means doing this migration under pressure, after 14 months of Helm 4 fixes shipped without you tracking them.

The better path: upgrade now, before September, so you're on supported software when new Kubernetes releases land and need updated client libraries.

What Actually Broke: The Four Real Changes

1. Post-renderers require plugin registration

In Helm 3, you could pass any executable directly to --post-renderer:

helm install myapp ./chart --post-renderer ./scripts/mutate.sh
Enter fullscreen mode Exit fullscreen mode

Helm 4 drops this. Post-renderers must now be registered as named Helm plugins and referenced by plugin name:

helm install myapp ./chart --post-renderer my-post-renderer
Enter fullscreen mode Exit fullscreen mode

If your pipeline calls --post-renderer ./path/to/script.sh, it fails on Helm 4. The error message doesn't say "plugin required," so this is easy to miss in a quick smoke test.

To wrap an existing script as a plugin, create a plugin.yaml:

name: my-post-renderer
version: "0.1.0"
usage: "Custom post-renderer"
description: "Mutation script for Helm output"
command: "$HELM_PLUGIN_DIR/mutate.sh"
Enter fullscreen mode Exit fullscreen mode

Install it with helm plugin install /path/to/plugin-dir, then update your pipeline to reference the plugin name instead of the script path.

2. Registry login requires domain names only

Helm 3 accepted both forms:

helm registry login https://registry.example.com  # Helm 3: works
helm registry login registry.example.com          # Helm 3: also works
Enter fullscreen mode Exit fullscreen mode

Helm 4 accepts domain names only — no protocol prefix:

helm registry login registry.example.com   # Helm 4: correct
helm registry login https://registry.example.com  # Helm 4: fails
Enter fullscreen mode Exit fullscreen mode

Check every CI/CD step that authenticates to a private OCI registry. The HELM_EXPERIMENTAL_OCI=1 environment variable is also gone — OCI is now stable and enabled by default, and setting that flag causes an error.

3. --atomic and --force are renamed

Two flags that appear constantly in production pipelines are deprecated in Helm 4:

Old flag New flag
--atomic --rollback-on-failure
--force --force-replace

The old flags still work in current Helm 4 releases but emit deprecation warnings. They become hard errors in a future minor version. If your pipeline treats warnings as failures — which many do — you'll hit breakage before that happens.

4. Go SDK import path (tool builders only)

If you've built tooling that embeds Helm as a Go library, update your import from helm.sh/helm/v3 to helm.sh/helm/v4. This only applies if you're writing code that imports Helm packages — not if you're using the CLI.

New Defaults That Will Catch You Off Guard

Server-side apply for new installs

Helm 4 uses server-side apply (SSA) for all new helm install operations. SSA handles field ownership conflicts more cleanly than client-side apply, so this is the right default. But it changes behavior in ways that matter.

For existing releases installed with Helm 3, Helm 4 retains client-side apply on upgrades. So you get SSA on new installs and client-side apply on upgrades of existing releases. To force SSA for an existing release, pass --server-side explicitly:

helm upgrade myapp ./chart --server-side
Enter fullscreen mode Exit fullscreen mode

Test this in staging first. SSA applies field management metadata that can surface ownership conflicts if other tools — ArgoCD, kubectl, Terraform — have also been managing those resources.

kstatus changes what --wait checks

Helm 4's --wait flag now uses kstatus for readiness detection instead of just checking pod status. kstatus requires the watch verb on Kubernetes resources. If your Helm service account doesn't have watch, --wait fails immediately after you upgrade the binary.

Before upgrading, check your Kubernetes RBAC configuration and ensure the Helm service account includes:

rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
Enter fullscreen mode Exit fullscreen mode

Without watch, the failure looks like a timeout at first glance, not a permissions error.

How to Install Helm 4

Helm 4 and Helm 3 coexist on the same machine, so you can install Helm 4 and test before switching over.

Via install script:

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh
Enter fullscreen mode Exit fullscreen mode

macOS via Homebrew:

brew install helm
Enter fullscreen mode Exit fullscreen mode

Debian/Ubuntu:

curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update && sudo apt-get install helm
Enter fullscreen mode Exit fullscreen mode

Fedora/RHEL:

sudo dnf install helm
Enter fullscreen mode Exit fullscreen mode

After installation, run helm version to confirm 4.x, then test your charts against a staging namespace:

helm install test-release ./your-chart --namespace staging --dry-run
Enter fullscreen mode Exit fullscreen mode

Charts from existing Helm 3 deployments work as-is in Helm 4. What you're testing is your pipeline scripts, not the chart files.

Fixing Your CI/CD Scripts for Helm 4

Go through every Helm call in your pipelines. For each one, check these specific patterns:

# Rename --atomic
helm upgrade myapp ./chart --atomic               # OLD — warning now, hard error later
helm upgrade myapp ./chart --rollback-on-failure  # NEW

# Rename --force
helm upgrade myapp ./chart --force                # OLD
helm upgrade myapp ./chart --force-replace        # NEW

# Fix registry login
helm registry login https://my-registry.io        # OLD — fails in Helm 4
helm registry login my-registry.io               # NEW

# Remove the OCI experiment flag entirely
export HELM_EXPERIMENTAL_OCI=1   # Remove this line — setting it causes an error in Helm 4
Enter fullscreen mode Exit fullscreen mode

For post-renderer scripts: wrap each one as a Helm plugin using the plugin.yaml format above. The actual script content doesn't change — only how Helm references it.

For a shift-left security pipeline that validates charts pre-deploy, check whether your static analysis tools (conftest, chart-testing) have released Helm 4 compatible versions.

Helm templates and commands syntax is unchanged in Helm 4 — the template engine, values handling, and chart structure are all the same.

[IMAGE: articles/images/2026-07-05-helm-4-migration-guide-diagram.png | alt: "CI/CD pipeline checklist diagram for upgrading to Helm 4"]

For the official timeline, see the Helm v3 End of Life announcement.

Frequently Asked Questions

Q: Do I need to rewrite my Helm charts for Helm 4?
A: No. Helm 3 Chart API v2 charts work with Helm 4 without changes. The helm 4 migration affects your CI/CD scripts and automation — not the chart files, templates, or values.

Q: Will existing Helm 3 releases break when I upgrade the Helm binary?
A: No. Helm 4 reads existing release history without issues. Upgrades of existing releases stay on client-side apply until you explicitly pass --server-side.

Q: What happens if I don't upgrade before September 9?
A: Helm 3 keeps working — it just won't receive Kubernetes client library updates after September 9. Security patches continue until February 10, 2027. The practical risk is that new Kubernetes API deprecations won't be handled in Helm 3 after that date.

Q: How do I verify whether kstatus will break my --wait?
A: Run kubectl auth can-i watch pods --as=system:serviceaccount:default:helm for your Helm service account. If it returns "no," add watch to the cluster role before migrating.

Q: Does Helm 4 change how classic chart repositories work?
A: No. HTTP chart repos work the same. OCI registry support is now stable and the default — you no longer need HELM_EXPERIMENTAL_OCI=1, and setting it causes an error.

Quick Summary:

  • Helm 3 final feature release: September 9, 2026. Security patches end February 10, 2027.
  • Post-renderers must be Helm plugins — executable paths no longer work
  • helm registry login requires domain names only — drop https://
  • --atomic → --rollback-on-failure, --force → --force-replace
  • kstatus for --wait requires the watch RBAC verb — check before migrating
  • Charts need zero changes — this helm 4 migration is entirely in your CI/CD scripts

Top comments (0)