build: upgrade Helm from 3.18.4 to Helm 4

[markmandel]

Summary

Helm 4 was released in late 2025 and includes significant improvements around security, server-side apply, OCI digest support, and a stable SDK API. This is not an immediate concern — Helm 3 charts remain fully compatible with Helm 4, and we want to be thoughtful about the transition. We'd love to hear from the community: are you already upgrading to Helm 4? Please leave a comment if so!

Current state

• build/build-image/Dockerfile: ENV HELM_VER 3.18.4
• build/e2e-image/Dockerfile: ENV HELM_VER 3.18.4
• test/upgrade/Dockerfile: ENV HELM_VER=3.18.4

---

Breaking changes to address

1. --atomic flag renamed to --rollback-on-failure — Used in multiple places:

   • build/Makefile:459 — helm upgrade --install --atomic
   • test/upgrade/main.go:328 — upgrade --install --atomic
   • site/content/en/docs/Installation/upgrading.md:86 — user-facing docs

2. --force flag renamed to --force-replace — Audit all Makefile and CI scripts.

3. Server-side apply default for new installs — New installations default to server-side apply. Existing Helm 3 releases on upgrade will retain client-side apply unless --server-side is passed. Verify e2e and upgrade test behaviour.

4. Post-renderer changes — Now requires a plugin name rather than an executable path. Audit any post-renderer usage.

5. helm registry login format — Now accepts domain only, not full URL. Audit OCI-related scripts.

---

Documentation to update

• site/content/en/docs/Installation/Install Agones/helm.md — Add installation instructions for both Helm 3 and Helm 4 during the transition period.

---

Opportunities to adopt

• OCI digest pinning — Charts can now be installed by digest (@sha256:...) for stronger supply chain security.
• Multi-document values — Evaluate splitting complex values.yaml configurations.
• WebAssembly plugin runtime — Optional Wasm-based plugins for enhanced security isolation.

---

Tasks

• Bump HELM_VER in build/build-image/Dockerfile, build/e2e-image/Dockerfile, and test/upgrade/Dockerfile
• Replace --atomic with --rollback-on-failure in build/Makefile, test/upgrade/main.go, and site/content/en/docs/Installation/upgrading.md
• Audit all helm invocations for other deprecated flags (--force, etc.)
• Update site/content/en/docs/Installation/Install Agones/helm.md to include installation instructions for both Helm 3 and Helm 4
• Run helm lint and full e2e + upgrade test suite against Helm 4

---

References

• https://helm.sh/docs/overview/