feat: separate Kubernetes package version from orchestrator version

[wenhug]

What this PR does / why we need it:

Adds an optional kubernetesPackageVersion alongside the semantic orchestrator version. Kubernetes 1.37 beta node artifacts use distro-specific package identifiers (1.37.0~beta.0 for Ubuntu/Azure Linux RPMs and 1.37.0-beta.0 for Flatcar/ACL OCI tags), while AgentBaker version gates must continue to evaluate the stable 1.37.0 value. The new field is propagated through CSE package, credential-provider, network-isolated, Flatcar, and Azure Container Linux paths with a fallback to the orchestrator version.

Validation:

• go test ./pkg/agent
• ShellSpec: 194 examples, 0 failures
• shellcheck
• Azure Linux prerelease RPM cache and repo lookup tests

Which issue(s) this PR fixes:

N/A

[github-actions]

Windows Unit Test Results

  3 files   12 suites   49s ⏱️
389 tests 389 ✅ 0 💤 0 ❌
392 runs  392 ✅ 0 💤 0 ❌

Results for commit eb85ad8.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

This PR extends AgentBaker’s Kubernetes version plumbing to support prerelease artifact identifiers (package/OCI tag versions) without breaking existing logic that must continue to gate behavior on the stable semantic orchestrator version.

Changes:

• Adds KubernetesPackageVersion to the OrchestratorProfile datamodel and propagates it into Linux CSE parameters (with fallback to OrchestratorVersion).
• Updates Linux CSE scripts to prefer KUBERNETES_PACKAGE_VERSION for package/tag-based install paths while continuing to compare/gate using KUBERNETES_VERSION.
• Adds/extends ShellSpec and Go tests to cover prerelease package version handling across Ubuntu/Azure Linux RPMs and Flatcar/ACL OCI tag flows.

Reviewed changes

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

Show a summary per file

File	Description
spec/parts/linux/cloud-init/artifacts/cse_install_mariner_spec.sh	Adds ShellSpec coverage for Azure Linux prerelease RPM cache lookup and repo query/download behavior.
spec/parts/linux/cloud-init/artifacts/cse_config_spec.sh	Adds ShellSpec coverage ensuring prerelease package/tag versions are used for installs while stable versions are used for comparisons/gates; adds credential-provider coverage too.
pkg/agent/params.go	Adds kubernetesPackageVersion parameter emission with fallback to kubernetesVersion.
pkg/agent/datamodel/types.go	Extends OrchestratorProfile with optional kubernetesPackageVersion.
pkg/agent/baker_test.go	Adds/updates Go tests asserting KUBERNETES_PACKAGE_VERSION is emitted and can differ from KUBERNETES_VERSION.
parts/linux/cloud-init/artifacts/cse_config.sh	Uses KUBERNETES_PACKAGE_VERSION (fallback to KUBERNETES_VERSION) for package/tag-based kubelet/kubectl and credential-provider installation paths.
parts/linux/cloud-init/artifacts/cse_cmd.sh	Exposes KUBERNETES_PACKAGE_VERSION into the CSE environment via templated parameters.

[aks-node-assistant]

AgentBaker Linux Gate Detective

Run: https://msazure.visualstudio.com/CloudNativeCompute/_build/results?buildId=174782043
Failed job: Run AgentBaker E2E

Summary: Deterministic E2E validation regression in provision-config vs nbc-cmd env parity: KUBERNETES_PACKAGE_VERSION is present only in
bc-cmd, matching this PR's package-version/orchestrator-version split.

RCA: Surface: 21 E2E validation failures report provision-config vs nbc-cmd environment diff with only-in-nbc KUBERNETES_PACKAGE_VERSION. Corroboration: the broad leaf failures share the same env-diff signature, build metadata ties the run to PR #9102, and the wiki row is linux-e2e-nbc-provision-config-env-diff-kubernetes-package-version. Challenge: infra flakes/unrelated provisioning failures are less likely because the common diff is deterministic and aligned with the PR change.

Classification: PR-change-caused deterministic CSE/NBC env parity regression.
Confidence: High.
Strongest alternative: test expectation drift rather than product regression.
Recommended owner/action: PR owner/Node Lifecycle should update parity behavior or emit KUBERNETES_PACKAGE_VERSION consistently.
Evidence: build run above; PR metadata; wiki signature linux-e2e-nbc-provision-config-env-diff-kubernetes-package-version — https://dev.azure.com/msazure/09706533-03bf-4b43-9a9b-b49c75429646/_wiki/wikis/ed4a85e9-1085-4151-a39b-2753523eba2b?pagePath=%2FAKS%2FSIGs%20and%20Teams%2FAKS%20Components%2FSIG%3A%20Node%20Lifecycle%2FAI%20Agent%20Knowledge%2FAgentBaker%20Gate%20PR%20Pipeline%20Flakiness

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Aug 3, 2026, 10:52 PM

[Copilot]

Pull request overview

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

Files not reviewed (1)

• aks-node-controller/pkg/gen/aksnodeconfig/v1/config.pb.go: Generated file

[Copilot]

Pull request overview

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

Files not reviewed (1)

• aks-node-controller/pkg/gen/aksnodeconfig/v1/config.pb.go: Generated file

Suppressed comments (1)

aks-node-controller/parser/parser_test.go:414

• Test case name "omits the redundant package version" is misleading here: the package version is omitted because kubernetesPackage is empty/unset (not because it’s redundant vs kubernetesVersion). Renaming the case makes the intent clearer and avoids implying additional behavior (like omitting when equal).

		{
			name:              "omits the redundant package version",
			kubernetesVersion: "1.36.3",
		},