Feature Summary

Introduce a uniform numbered local-chart bundle layout (NNN-<component>/) and adopt it in --deployer helm. Chart.yaml presence in a numbered folder signals that local chart content exists; deployers branch on that single fact rather than on component-kind metadata.

Parent: #516.

Problem / Use Case

Today's --deployer helm branches its generated deploy.sh on three component kinds (Helm / Kustomize / raw manifests) with distinct install mechanisms and per-case special handling. This makes the script complex, fragile, and hard to share with #632 (helmfile deployer) or a future Flux deployer. A uniform numbered local-chart layout lets every deployer consume one shape and eliminates component-type branching from the install path.

Scope A (this sub-issue) is a pure format refactor — no vendoring of upstream Helm chart bytes. Vendoring lands separately in the follow-up.

Proposed Solution

Per-component output (the "Chart.yaml = local chart content" rule):

• Helm-only, non-vendored: NNN-<name>/values.yaml + cluster-values.yaml. No Chart.yaml. Upstream chart reference encoded in the generated deploy.sh.
• Raw-manifest-only (always wrapped): NNN-<name>/Chart.yaml + templates/*.yaml (rendered via existing pkg/manifest pipeline).
• Kustomize (always wrapped; kustomize build at bundle time): NNN-<name>/Chart.yaml + templates/manifest.yaml.
• Mixed Helm + raw manifests, non-vendored — emits two numbered folders: a primary NNN-<name>/ (values-only, no Chart.yaml, upstream ref) and an injected NNN'-<name>-post/ wrapped chart (Chart.yaml + templates/) positioned immediately after. The injected -post folder is what deploys the raw manifests. Every folder still follows the Chart.yaml-presence rule — the "mixed" concept disappears at the bundle layer.

New internal package (working name pkg/bundler/localformat/) owns the layout writer. Reuses existing helpers from pkg/manifest, pkg/component, and pkg/bundler/deployer (SafeJoin, WriteValuesFile, ordering).

--deployer helm rewired to call the library. deploy.sh is a true generic loop — one branch on Chart.yaml presence, no manifests/ pre/post special-casing:

for dir in [0-9]*/; do
  name="${dir#*-}"; name="${name%/}"
  if [[ -f "${dir}/Chart.yaml" ]]; then
    helm upgrade --install "${name}" "./${dir}" -f "${dir}/values.yaml" -f "${dir}/cluster-values.yaml" ${COMPONENT_WAIT_ARGS}
  else
    helm upgrade --install "${name}" "${upstream_chart}" --repo "${upstream_repo}" --version "${upstream_version}" -f "${dir}/values.yaml" -f "${dir}/cluster-values.yaml" ${COMPONENT_WAIT_ARGS}
  fi
done

Mixed components are naturally handled: the primary folder installs the upstream chart, the injected -post folder (Chart.yaml present) installs the wrapped-manifests chart right after. No manifests branch in deploy.sh at all.

Component-specific special-cases (kai-scheduler async skip, DRA kubelet-plugin restart, skyhook taint cleanup, orphaned-CRD scan, CRD-race retry) stay as name-matched blocks around the loop. Simplifying those is a non-goal — see #632.

Success Criteria

• New pkg/bundler/localformat/ package produces the numbered layout deterministically across all per-component shapes above, including the two-folder emission for mixed components.
• --deployer helm emits the new layout by default; existing values-override / dynamic-values / node-scheduling flags keep working.
• deploy.sh branches only on Chart.yaml presence (no component-type metadata, no manifests/ pre/post).
• Raw-manifest-only and Kustomize components are wrapped as minimal charts.
• Mixed components emit primary + -post injected folders with sequential numbering.
• KWOK e2e (make kwok-e2e RECIPE=eks-training) passes end-to-end with regenerated deploy.sh.
• make qualify clean; test coverage gate satisfied on changed packages.
• docs/user/cli-reference.md updated for the new bundle layout and the post-install-only timing for mixed-component manifests.

Alternatives Considered

• Umbrella Chart.yaml with dependencies: pointing at upstream for every Helm component. Rejected: introduces helm dependency update at every deploy for zero functional gain in non-vendored mode; re-exposes Argo CD's per-version helm.enableDependencyUpdate surface in downstream deployer work.
• Bundle both scope A (layout) and scope B (vendoring) in one PR. Rejected: couples cheap format refactor with costlier vendoring machinery (auth, bundle-time network, audit logging, size).

Component

Bundlers (gpu-operator, network-operator, etc.)

Priority

Important (would improve my workflow)

Compatibility / Breaking Changes

--deployer helm users see a new on-disk bundle layout:

• Numbered folder prefixes (001-gpu-operator/ instead of gpu-operator/).
• Raw-manifest-only and Kustomize components now contain a Chart.yaml + templates/ instead of manifests/.
• Mixed components now emit two numbered folders — primary (upstream ref, no Chart.yaml) and an injected -post chart for raw manifests.
• Raw manifests for mixed components apply post-install only (today's CRD-race pre-apply optimization is dropped; post-apply is what guarantees convergence).
• Existing CLI flags and API surface unchanged.

Bundle is still non-vendored; helm upgrade --install still needs registry access at deploy time. Document in release notes + docs/user/cli-reference.md.

Operational Considerations

• No new runtime dependency. Kustomize handling uses either the existing Kustomize Go library or shells out (decided in-PR based on existing code patterns).
• Bundle size grows modestly due to generated Chart.yaml files.

Are you willing to contribute?

Maybe, with guidance