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, registry authentication, or chart dependencies.
• Install, upgrade, apply, wait, test, and server-side dry-run behavior.
• Chart creation, values coalescing, packaging, caching, or .Files.Lines.
• Kubernetes compatibility and maintained Helm 3 clients.

Start by identifying whether the task concerns a chart, the CLI, an SDK integration, or a plugin. A Helm 4 migration does not imply that every Helm 3 chart needs changes; focus review on affected integration points and changed behaviors.

Reference index

Breaking changes and migration priorities

Review embedded SDK code

Helm 4 changes public SDK APIs, supports multiple chart API versions, and uses Go slog. For applications that embed Helm:

1. Review calls against the Helm 4 API instead of assuming Helm 3 signatures.
2. Account for SDK handling of multiple chart API versions.
3. Connect Helm logging to the host logger through slog where needed.
4. Exercise the SDK paths used for apply and wait behavior.

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

Recheck plugins and post-renderers

Helm 4 redesigns the plugin system around support for WebAssembly-based plugins. Post-renderers are plugins in Helm 4 as well. During migration:

• Inventory ordinary extensions and post-renderers together.
• Validate each integration against the Helm 4 plugin model.
• Upgrade older Helm 4 clients that install plugins, especially when plugin sources are not fully trusted.

The client upgrade matters because plugin handling was hardened against both a missing-provenance bypass and version path traversal.

Stop passing deprecated template note flags

Helm 4.2 deprecates these unused helm template flags:

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

Remove them from scripts and wrappers rather than preserving them as required compatibility options.

Retest values coalescing

Helm 4.2 changes nil handling during values coalescing:

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

Retest charts whose overrides depend on nil cleanup or subchart coalescing. Inspect final coalesced values instead of relying on the previous cleanup behavior.

High-use operations

Restore atomic installs

Helm 4.2 restores --atomic on helm install. Use it when an unsuccessful installation should roll back automatically:

helm install my-release ./chart --atomic

Align server-side apply behavior

Helm 4 supports server-side apply. Its SDK defaults are aligned with the CLI defaults in Helm 4.2, so do not compensate for a default difference that no longer exists. Keep explicit settings only when the application deliberately overrides the shared defaults.

Server-side apply also retries Kubernetes conflicts in 4.2.4. Prefer a client with that fix when concurrent resource updates otherwise abort operations on the first conflict.

Bound and diagnose waits

Helm 4 improves resource watching and waiting with kstatus. Fine-grained context options can bound or cancel waits, and failed resources no longer leave Helm waiting forever.

For wait-related work:

1. Use context controls to bound or cancel the operation.
2. Preserve failed-resource information for diagnosis.
3. Do not add an outer infinite wait to reproduce older behavior.

Accept server-generated names in dry-runs

--dry-run=server accepts rendered resources that set metadata.generateName instead of metadata.name. Validation and test harnesses should allow that shape when the API server will generate the final name.

Collect all test-container logs

As of 4.2.4, helm test fetches logs from every container in each test pod. Use those diagnostics when failures originate in a sidecar or another secondary container.

Keep registry clients and scopes available

For token-authenticated registry pushes, Helm 4.2.4 requests both pull and push scopes. Upgrade when a registry rejects a token exchange that lacks the complete scope set.

During helm upgrade, the registry client is also passed to downloader.Manager, making credentials and client configuration available while chart dependencies are downloaded.

Chart creation and delivery

Create an experimental chart API v3 chart

The SDK handles multiple chart API versions. When the experimental v3 gate is enabled, Helm 4.2 exposes helm create --chart-api-version:

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

Treat the environment gate and the explicit version option as a pair; the option alone does not enable experimental v3.

Use content-based caching

Helm 4 adds local content-based caching, including for charts. Identical content can share cached data independently of source location. Compare content when reasoning about cache reuse instead of assuming each path creates distinct cached data.

Expect reproducible archives

Chart archive builds are reproducible and idempotent in Helm 4. Repeated packaging can support deterministic build and verification workflows. If builds differ, investigate their inputs and surrounding workflow rather than accepting archive nondeterminism as expected.

Allow empty files in .Files.Lines

Helm 3.21.4 prevents .Files.Lines from panicking for an empty requested chart file. Charts that iterate optional or generated files no longer need to insert content solely to avoid that crash.

Compatibility and maintained clients

Match the Kubernetes window

Helm 4 follows an n-3 Kubernetes compatibility policy and makes no forward-compatibility guarantee beyond its compiled client version. Helm 4.2.x uses Kubernetes 1.36 client libraries and supports Kubernetes 1.33.x through 1.36.x.

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

Plan for the Helm 3 support sunset

Helm 3 receives bug fixes through July 8, 2026 and security fixes through November 11, 2026. Features are not backported during this 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.

Upgrade maintained Helm 3 clients for security fixes

Helm 3.21.4 changes provenance cryptography and updates OpenTelemetry, gRPC, x/crypto, and x/text to address the listed Go advisories. Upgrade maintained Helm 3 clients that need those dependency fixes; see the migration reference for the exact packages and advisory identifiers.

Select supported release artifacts

Helm 4.2 provides official Linux loong64 release artifacts. Prefer those 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 when Helm logging connects to a host logger.
• Exercise every plugin and post-renderer through the Helm 4 plugin system.
• Update plugin-installing clients where validation hardening is absent.
• Compare explicit server-side apply settings with aligned CLI and SDK defaults; test conflict retries where concurrent updates occur.
• Test successful, failed, canceled, and context-bounded wait paths.
• Test install rollback with --atomic where atomicity is required.
• Include a server dry-run fixture that uses metadata.generateName.
• Confirm helm test diagnostics include secondary containers.
• Exercise token-authenticated pushes and registry-backed dependency downloads.
• Remove deprecated template note flags from automation.
• Retest nil overrides, subchart values coalescing, and empty chart files.
• Package the same chart repeatedly when deterministic archives matter.
• Verify Helm and Kubernetes versions against the compatibility window.
• Read the relevant full reference before changing compatibility logic.