[release/13.4] Validate Helm CLI version (>= 4.2.0) before Kubernetes deploy#17542
Merged
Conversation
Aspire's Kubernetes deployment pipeline shells out to 'helm upgrade --install' for the main application chart and for any AddHelmChart(...) resources on a KubernetesEnvironmentResource. Previously we only checked that 'helm' was on PATH; we never asserted the installed Helm version was new enough for the flags and behaviors we depend on (e.g. '--server-side=true --force-conflicts' in the Helm 4 form). Missing or older Helm produced confusing low-level errors like 'unknown flag: --force-conflicts', 'Flag --force has been deprecated', or raw process-spawn failures. Changes: * Add internal HelmVersionValidator that runs 'helm version --short --client', parses the SemVer, and asserts a minimum of Helm 4.2.0. Throws a clear actionable InvalidOperationException (detected vs required + link to https://helm.sh/docs/intro/install/) when the version is too old, unparseable, or the command fails. * Wire the validator into the existing check-helm-prereqs-{env} pipeline step in HelmDeploymentEngine. One check per environment covers both the main chart deploy and AddHelmChart(...) flows since they all DependsOn this step. * Update the 'Helm CLI not found' message to also mention the minimum version requirement. * Remove the now-redundant ad-hoc 'helm version --short' probe at the top of HelmDeployAsync (the prereq step covers it with a much better error). * Promote FakeHelmRunner to a file-scoped test helper that emits canned 'helm version' stdout (defaults to v4.2.0+gfa15ec0) and supports a separate VersionExitCode, so any test exercising the deploy path automatically passes the prereq check. * Add HelmVersionValidatorTests covering: SemVer parsing of v3/v4/v5 outputs with and without '+gitsha' build metadata, rejection of unparseable output, threshold behavior for too-old versions (v4.1.0, v4.0.0, v3.18.0, v3.14.4), and that error messages include the detected version, the required version, and the install docs URL. * Document the Helm 4.2.0+ requirement in the Aspire.Hosting.Kubernetes and Aspire.Hosting.Azure.Kubernetes READMEs. Fixes #16977 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The validator was invoking 'helm version --short --client', but the --client flag was removed in Helm 4 (it existed in Helm 2 for the real client/server split, was kept as a no-op in Helm 3, and is unknown in Helm 4). Since this validator's purpose is to enforce Helm 4.2.0 or later, passing --client guarantees a failure against the very minimum version we require, surfacing the exact kind of confusing prereq error this step exists to prevent. Caught by dogfood testing of PR #17491 against a local Helm 4.2.0 install, which produced: Step 'check-helm-prereqs-k8s' failed: 'helm version --short --client' failed (Error: unknown flag: --client). Aspire requires Helm 4.2.0 or later. Switch to 'helm version --short', which produces identical output shape (e.g. v4.2.0+gfa15ec0) on Helm 3 and Helm 4. Add a regression test that records the arguments passed to the runner and asserts --client is never included. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three review items from the automated PR reviewer:
1. Gate destroy/uninstall on the same Helm prereq check as deploy.
Both 'destroy-helm-{env}' and 'helm-uninstall-{env}' invoke 'helm
uninstall', so a missing or too-old Helm would surface as a raw
process-spawn / unknown-flag error during teardown instead of the
actionable validator message. Add a 'DependsOn(check-helm-prereqs-
{env})' on both, and add a regression test that asserts the
dependency edge exists.
2. Fix the misleading comment above HelmVersionRegex. The regex is
intentionally unanchored so we tolerate banner/shim lines that
some shells, oh-my-zsh plugins, or asdf-style shims can prepend
to the version output. Update the comment to describe that
intent instead of claiming a start anchor that isn't there.
3. Shorten the Helm prerequisite bullets in both Kubernetes README
files. Keep the bullet to the requirement itself and move the
'why we validate up front' narrative into a short paragraph
below, matching the scannable style of the other hosting READMEs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The 11 DeployK8s* CLI E2E tests failed on commit d03916c because the container install scripts default HELM_VERSION to v3.17.3 — below the new HelmVersionValidator.MinimumHelmVersion (v4.2.0) that the check-helm-prereqs-{env} pipeline step now enforces. Centralize the version constants in a new tests/Aspire.Cli.EndToEnd.Tests/Helpers/KubernetesE2EVersions.cs so the default lives in one place (and points at the validator's documented minimum), then bump HelmVersion default v3.17.3 -> v4.2.0 (used by every DeployK8s* test and by the quarantined KubernetesPublishTests). HELM_VERSION / KIND_VERSION / KUBECTL_VERSION env-var overrides are preserved so CI can still bump to a newer point release without a code change. The AKS deployment workflow (deployment-tests.yml) still pins azure/setup-helm to v4.1.4 and needs the same bump to v4.2.0 to avoid breaking AKS scenarios under the new validator; that workflow file edit will land in a separate push that has 'workflow' OAuth scope. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Match Aspire.Hosting.Kubernetes' new minimum supported Helm version
(HelmVersionValidator.MinimumHelmVersion). The check-helm-prereqs-{env}
pipeline step now fails fast on older Helm CLIs, so leaving the AKS
deployment workflow pinned to v4.1.4 would break every AKS deployment
scenario. Also refresh the surrounding rationale comment, which still
referred to the historical v3.18 server-side narrative.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Address self-review follow-ups on PR #17491: - Per-chart `helm-uninstall-{name}` step (AddHelmChart(...).WithDestroy()) now depends on `check-helm-prereqs-{env}`. Previously only the env-level destroy/uninstall steps were gated, so chart teardown could still hit the cryptic spawn / unknown-flag error the validator exists to prevent. - Drop the standalone PathLookupHelper probe from the prereq step. The validator already wraps spawn failures with the same actionable hint, and routing everything through IHelmRunner lets tests inject a fake without needing real Helm on PATH (fixes 3 pre-existing K8s test failures in environments without helm installed). - Refresh validator catch comment + error wording accordingly. - Drop stale `--client` mention in FakeHelmRunner comment. - Add regression test PerChartHelmUninstallStep_DependsOnCheckHelmPrereqs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17542Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17542" |
Contributor
|
❌ CLI E2E Tests failed — 106 passed, 1 failed, 2 unknown (commit Failed Tests
View all recordings
📹 Recordings uploaded automatically from CI run #26517257157 |
davidfowl
approved these changes
May 27, 2026
aspire-repo-bot Bot
added a commit
to microsoft/aspire.dev
that referenced
this pull request
May 27, 2026
Aspire now validates the Helm CLI version (>= 4.2.0) upfront before deploying to Kubernetes. Missing or older Helm versions produce a clear actionable error instead of cryptic flag failures like 'unknown flag: --force-conflicts'. Update Prerequisites in both Kubernetes and AKS deployment docs to reflect this minimum version requirement. Documents changes from microsoft/aspire#17542. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
Pull request created: #1097
|
Contributor
Author
|
📝 Documentation has been drafted in microsoft/aspire.dev#1097 targeting Updated the Prerequisites section in two Kubernetes deployment pages to specify Helm v4.2.0 or later, reflecting the new upfront Helm version validation added in the source PR. Files modified:
Note This draft PR needs human review before merging. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport of #17491 to release/13.4
/cc @mitchdenny
Customer Impact
Testing
Risk
Regression?