Helm Knowledge Patch

Helm Knowledge Patch

Use this patch

Load this patch for work involving:

• Helm 4 migrations, especially applications that embed the Go SDK;
• plugins, post-renderers, and plugin installation;
• install, upgrade, apply, wait, test, and server-side dry-run behavior;
• chart creation, templates, values coalescing, packaging, and caching;
• registry authentication and registry-backed dependencies;
• Kubernetes compatibility and maintained Helm 3 clients.

First identify whether the task concerns a chart, the CLI, an SDK integration, or a plugin. A Helm 4 migration does not by itself require every Helm 3 chart to change. Focus review on the affected integration points and behavior.

Reference index

Choose the relevant surface

Breaking changes and migration priorities

Review embedded SDK code

Helm 4 changes public SDK APIs. For applications that embed Helm:

1. Review calls against the Helm 4 API rather than assuming Helm 3 signatures.
2. Account for SDK support for multiple chart API versions.
3. Integrate logging through Go slog when Helm output must join the host application's logging pipeline.
4. Exercise the exact SDK paths used for server-side apply and waiting because their defaults and controls have changed.

Read migration-sdk-and-plugins.md before changing an embedded integration.

Recheck plugins and post-renderers

Helm 4 redesigns plugins to support WebAssembly. Post-renderers are plugins in the new model, so include both ordinary extensions and post-renderers in the migration inventory.

Upgrade older Helm 4 clients that install plugins, especially when plugin sources are not fully trusted. Plugin handling was hardened against both a missing-provenance bypass and version path traversal.

Stop passing deprecated template note flags

Remove these unused helm template flags from scripts and wrappers:

• --hide-notes
• --render-subchart-notes

They are deprecated and should not be preserved as required compatibility options.

Retest values coalescing

Do not assume the previous treatment of chart-default nil values:

• chart-default nil values are no longer copied into coalesced values;
• nil is preserved when the chart default is an empty map.

Inspect final coalesced values for charts whose overrides depend on nil cleanup or subchart coalescing.

Plan the Helm 3 support transition

Helm 3 receives bug fixes through July 8, 2026 and security fixes through November 11, 2026. Features are not backported during that transition, except for Kubernetes client-library updates needed to support newer Kubernetes versions.

Use those dates when deciding whether to maintain a Helm 3 path or complete a Helm 4 migration. Maintained Helm 3 clients should also pick up relevant provenance, OpenTelemetry, gRPC, and Go cryptography dependency updates.

High-use operations

Restore atomic installs

Use --atomic when a failed installation must roll back automatically:

helm install my-release ./chart --atomic

Align and retry server-side apply

Helm 4 supports server-side apply. Its SDK defaults are aligned with the CLI defaults, so remove compensating configuration that existed only to bridge a default mismatch. Keep explicit settings when the application intentionally overrides the shared behavior.

Server-side apply also retries Kubernetes conflicts. Concurrent resource updates are therefore less likely to abort an operation on the first conflict; retain normal operation bounds and error handling around retries.

Bound and diagnose waits

Helm 4 improves resource watching and waiting with kstatus. Use the available fine-grained context controls to bound or cancel waits, and preserve failed resource information for diagnosis. Do not add an outer infinite wait to compensate for older behavior; a failed resource no longer needs to leave Helm waiting forever.

Accept server-generated names in dry-runs

For --dry-run=server, accept rendered resources with metadata.generateName instead of metadata.name. The API server can generate the final name, so validation fixtures should allow this resource shape.

Collect all test-container logs

helm test fetches logs from every container in each test pod. Diagnostics can therefore include sidecars and other secondary containers. Preserve and inspect the complete log set rather than assuming only the primary container matters.

Carry registry configuration through delivery

Token-authenticated helm push requests both pull and push scopes. Upgrade when a registry rejects a push because token exchange did not request the full scope set.

During helm upgrade, the registry client is passed to downloader.Manager. Dependency downloads can therefore use the operation's registry credentials and client configuration.

Read operations-and-delivery.md before changing apply, wait, registry, test, or packaging workflows.

Chart creation and delivery

Create an experimental chart API v3 chart

Enable the experimental gate and select the API version explicitly:

HELM_EXPERIMENTAL_CHART_V3=1 helm create demo --chart-api-version v3

The option alone does not enable experimental chart API v3. Treat both the environment gate and the explicit version selection as required workflow inputs.

Iterate empty chart files safely

.Files.Lines can iterate a requested chart file even when it is empty. Charts with optional or generated files no longer need placeholder content solely to avoid a panic. Keep application-level handling when an empty file has a semantic meaning.

Use content-based caching

Helm 4 caches local data, including charts, by content. Identical content can share cached data independently of source location. Compare content when reasoning about reuse instead of assuming that every source path creates a distinct cached object.

Expect reproducible archives

Chart archive builds are reproducible and idempotent. Repeated packaging can be used in deterministic build and verification workflows. If builds differ, investigate the inputs and surrounding workflow rather than accepting archive nondeterminism as normal.

Read charts-and-values.md before changing chart creation, template automation, coalescing behavior, or file iteration.

Compatibility checks

Match the Kubernetes window

Helm 4 follows an n-3 Kubernetes compatibility policy and does not guarantee forward compatibility beyond the client version with which it was built. The Helm 4.2.x line uses Kubernetes 1.36 client libraries and supports Kubernetes 1.33.x through 1.36.x.

Check both the Helm client line and target Kubernetes version before treating an out-of-window pairing as supported.

Select supported release artifacts

Official Linux loong64 artifacts are available in the Helm 4.2 line. Prefer those release artifacts when targeting that platform.

Verification checklist

Before completing a Helm migration or behavior change:

• compile and test embedded code against the Helm 4 public SDK APIs;
• verify slog integration if Helm logging joins a host logger;
• exercise every plugin and post-renderer through the Helm 4 plugin system;
• update plugin-installing clients where validation hardening is absent;
• remove deprecated template note flags from automation;
• inspect nil overrides and subchart values after coalescing;
• test successful, failed, canceled, and context-bounded wait paths;
• compare explicit server-side apply settings with aligned CLI and SDK defaults, then test conflict handling;
• test install rollback with --atomic where atomicity is required;
• include a server dry-run fixture that uses metadata.generateName;
• include multi-container test pods when test diagnostics matter;
• verify push token scopes and authenticated dependency downloads;
• exercise .Files.Lines with an empty chart file;
• package the same chart repeatedly when deterministic archives matter;
• verify the Helm/Kubernetes pairing against the compatibility window;
• read the relevant full reference before changing compatibility logic.