feat: add helm-legacy track mode for Helm v4 compatibility by yxxhero · Pull Request #2466 · helmfile/helmfile

yxxhero · 2026-03-06T05:24:17Z

Summary

This PR adds support for trackMode: helm-legacy to address Helm v4 compatibility issues when migrating from Helm v3 to Helm v4.

Helm v4 + trackMode: helm-legacy: Uses --wait=legacy flag (maintains Helm v3 polling behavior)
Helm v3 + trackMode: helm-legacy: Falls back to regular --wait with a warning message
Any version + trackMode: helm: Uses --wait (default)
Any version + trackMode: kubedog: Uses kubedog tracking (skips --wait)

Changes

Core Implementation

Add TrackModeHelmLegacy constant in pkg/kubedog/options.go
Enhance appendWaitFlags() in pkg/state/helmx.go to:
- Detect Helm v4 when trackMode: helm-legacy is set
- Use --wait=legacy for Helm v4 + helm-legacy
- Show warning and fall back to --wait for Helm v3 + helm-legacy
- Accept helm parameter for version detection

Validation

Update validation in pkg/config/apply.go and pkg/config/sync.go
Use slices.Contains for cleaner validation
Add helm-legacy to valid track modes

CLI Flags

Update --track-mode help text in cmd/apply.go and cmd/sync.go
Clarify that helm-legacy is only available in Helm v4

Documentation

Add comprehensive documentation in docs/advanced-features.md
Explain track modes: helm, helm-legacy, and kubedog
Document use cases and compatibility requirements
Add examples for configuration

Tests

Add comprehensive test coverage in pkg/state/helmx_test.go
Test Helm v4 + helm-legacy scenario
Test Helm v3 + helm-legacy fallback with warning
Test helm-legacy without wait flag
Verify warning message content
Test all track modes with different Helm versions

Use Case

When migrating from Helm v3 to Helm v4, some charts may have compatibility issues with Helm v4's new watcher-based wait mechanism. For example, charts with broken livenessProbe configurations but no startupProbe may fail immediately with the new watcher.

Using trackMode: helm-legacy allows users to:

Maintain Helm v3 behavior during migration
Avoid breaking changes when upgrading to Helm v4
Gradually fix chart issues while keeping deployments working

Behavior Matrix

Helm Version	trackMode	wait flag	Result	Warning?
v4.x	helm-legacy	true	`--wait=legacy`	No
v3.x	helm-legacy	true	`--wait`	Yes
v4.x	helm	true	`--wait`	No
v3.x	helm	true	`--wait`	No
Any	kubedog	true	(no flag)	No
v4.x	helm-legacy	false	(no flag)	No

Testing

All tests pass:

✅ Unit tests for all scenarios
✅ Integration tests
✅ Warning message verification
✅ make check passes

Fixes #2464

yxxhero · 2026-03-06T05:32:51Z

@champtar
PTAL

Copilot

Pull request overview

Adds a new trackMode: helm-legacy option to help users migrating from Helm v3 to Helm v4 by selecting Helm v4’s legacy polling-based wait behavior (--wait=legacy) while keeping existing helm and kubedog modes intact.

Changes:

Introduces helm-legacy as a supported track mode and documents the intended behavior/compatibility.
Updates Helm upgrade flag construction to emit --wait=legacy on Helm v4 (and warn/fallback to --wait on Helm v3).
Expands unit test coverage for wait flag behavior across Helm versions and track modes.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/state/state.go	Passes the `helmexec.Interface` into wait-flag assembly for version-aware behavior.
pkg/state/helmx.go	Implements `helm-legacy` handling in `appendWaitFlags` and centralizes trackMode resolution.
pkg/state/helmx_test.go	Adds tests for Helm v4 legacy wait and Helm v3 fallback warning behavior.
pkg/kubedog/options.go	Adds `TrackModeHelmLegacy` constant alongside existing track mode constants.
pkg/config/sync.go	Extends `--track-mode` validation to accept `helm-legacy` (using `slices.Contains`).
pkg/config/apply.go	Extends `--track-mode` validation to accept `helm-legacy` (using `slices.Contains`).
docs/advanced-features.md	Documents the new track mode and Helm v4 legacy wait use case.
cmd/sync.go	Updates `--track-mode` help text to include `helm-legacy` (Helm v4 only).
cmd/apply.go	Updates `--track-mode` help text to include `helm-legacy` (Helm v4 only).

Copilot · 2026-03-06T05:36:04Z

 func (st *HelmState) shouldUseKubedog(release *ReleaseSpec, ops *SyncOpts) bool {
+	return st.getTrackMode(release, ops) == "kubedog"
+}
+
+func (st *HelmState) getTrackMode(release *ReleaseSpec, ops *SyncOpts) string {
 	trackMode := release.TrackMode
 	if trackMode == "" && ops != nil && ops.TrackMode != "" {
 		trackMode = ops.TrackMode
 	}
 	if trackMode == "" {
 		trackMode = st.HelmDefaults.TrackMode
 	}
-	return trackMode == "kubedog"
+	if trackMode == "" {
+		trackMode = "helm"
+	}
+	return trackMode


Track modes are compared/returned as raw strings (e.g., "kubedog", "helm", "helm-legacy") even though this PR introduces kubedog.TrackMode* constants. Using the shared constants (or returning a kubedog.TrackMode from getTrackMode) would reduce the chance of typos/drift between packages and keep the set of modes centralized.

Add support for trackMode: helm-legacy to use Helm v4's --wait=legacy flag, which maintains compatibility with Helm v3's wait behavior during migration. Helm v4 changed the default --wait behavior from polling to a watcher-based approach. This can cause issues with charts that have broken livenessProbe configurations without startupProbe. The --wait=legacy flag preserves the Helm v3 polling behavior for smoother migration. Changes: - Add TrackModeHelmLegacy constant in pkg/kubedog/options.go - Use kubedog.TrackMode constants instead of raw strings in helmx.go - Enhance appendWaitFlags to use --wait=legacy for Helm v4 when trackMode is helm-legacy - Add nil check for logger before logging warning - Add version check with warning when helm-legacy is used with Helm v3 - Update validation in pkg/config to accept helm-legacy track mode - Update command-line flags in cmd/apply.go and cmd/sync.go - Add comprehensive documentation in docs/advanced-features.md - Add thorough test coverage including warning message verification Behavior: - Helm v4 + helm-legacy: Uses --wait=legacy - Helm v3 + helm-legacy: Falls back to --wait with warning - Helm v4 + helm: Uses --wait (watcher mode) - Any + kubedog: Skips --wait flag Fixes #2464 Co-authored-by: Copilot <[email protected]> Signed-off-by: yxxhero <[email protected]>

yxxhero · 2026-03-06T05:47:53Z

✅ Addressed Copilot Review Feedback

Thank you @copilot for the thorough review! I've addressed all three comments:

1. ✅ Added nil check for logger (Line 227 in pkg/state/helmx.go)

Added guard to prevent panic when logger is nil:

if st.logger != nil {
    st.logger.Warnf("trackMode 'helm-legacy' requires Helm v4, falling back to regular --wait for release %s", release.Name)
}

2. ✅ Used TrackMode constants instead of raw strings

Refactored to use kubedog.TrackMode* constants throughout:

string(kubedog.TrackModeKubedog) instead of "kubedog"
string(kubedog.TrackModeHelm) instead of "helm"
string(kubedog.TrackModeHelmLegacy) instead of "helm-legacy"

3. ✅ Fixed documentation formatting

Fixed the extra leading space and capitalized the sentence in line 103:

Before: settrackMode: helm-legacy:
After: To use this mode, set trackMode: helm-legacy:

All tests pass and make check succeeds! 🎉

Copilot · 2026-03-06T05:48:00Z

@yxxhero I've opened a new pull request, #2467, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

champtar

@yxxhero not tested but look good to me !

yxxhero · 2026-03-07T12:40:15Z

@aditmeno

yxxhero requested review from aditmeno, itscaro, mumoshu, xiaomudk and zhaque44 as code owners March 6, 2026 05:24

yxxhero requested a review from Copilot March 6, 2026 05:29

Copilot started reviewing on behalf of yxxhero March 6, 2026 05:30 View session

yxxhero linked an issue Mar 6, 2026 that may be closed by this pull request

trackMode helm-legacy #2465

Closed

Copilot AI reviewed Mar 6, 2026

View reviewed changes

yxxhero force-pushed the feat/helm-legacy-track-mode branch from d2664df to 3b8421e Compare March 6, 2026 05:43

yxxhero force-pushed the feat/helm-legacy-track-mode branch from 3b8421e to 240874f Compare March 6, 2026 05:47

Copilot AI mentioned this pull request Mar 6, 2026

[WIP] Add support for helm-legacy track mode for Helm v4 compatibility #2467

Closed

yxxhero requested a review from Copilot March 6, 2026 06:38

Copilot started reviewing on behalf of yxxhero March 6, 2026 06:38 View session

Copilot AI reviewed Mar 6, 2026

View reviewed changes

champtar approved these changes Mar 6, 2026

View reviewed changes

xiaomudk approved these changes Mar 8, 2026

View reviewed changes

yxxhero merged commit c6e7249 into main Mar 8, 2026
20 checks passed

yxxhero deleted the feat/helm-legacy-track-mode branch March 8, 2026 03:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: add helm-legacy track mode for Helm v4 compatibility#2466

feat: add helm-legacy track mode for Helm v4 compatibility#2466
yxxhero merged 1 commit into
mainfrom
feat/helm-legacy-track-mode

yxxhero commented Mar 6, 2026

Uh oh!

yxxhero commented Mar 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Uh oh!

yxxhero commented Mar 6, 2026

Uh oh!

Copilot AI commented Mar 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

champtar left a comment

Uh oh!

yxxhero commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Uh oh!

Conversation

yxxhero commented Mar 6, 2026

Summary

Changes

Core Implementation

Validation

CLI Flags

Documentation

Tests

Use Case

Behavior Matrix

Testing

Uh oh!

yxxhero commented Mar 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yxxhero commented Mar 6, 2026

✅ Addressed Copilot Review Feedback

1. ✅ Added nil check for logger (Line 227 in pkg/state/helmx.go)

2. ✅ Used TrackMode constants instead of raw strings

3. ✅ Fixed documentation formatting

Uh oh!

Copilot AI commented Mar 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

champtar left a comment

Choose a reason for hiding this comment

Uh oh!

yxxhero commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants