Feature Summary

Unify all bundle component types as local Helm charts with numbered folders for explicit ordering, producing a fully self-contained bundle with a generic deploy script.

Tracking umbrella. The original scope has been decomposed into four sequenced sub-issues (each its own PR). This issue closes only when all four land.

Sub-issues

• [Feature]: Uniform numbered local-chart bundle layout + --deployer helm adoption #662 — Uniform numbered local-chart bundle layout + --deployer helm adoption (base format library; Kustomize wrapping; raw-manifest wrapping; mixed components emit primary + -post folders; deploy.sh becomes a generic Chart.yaml-presence loop)
• [Feature]: --vendor-charts opt-in flag for air-gap bundles #663 — --vendor-charts opt-in flag for air-gap bundles (Helm SDK in-process chart pull; audit log; collapses mixed components back into one wrapped chart with hooks)
• [Feature]: --deployer argocd adopts uniform local-chart layout #664 — --deployer argocd adopts uniform local-chart layout (path-based single-source Applications when Chart.yaml present; multi-source preserved otherwise; mixed-component fix-forward via injected -post Application)
• [Feature]: --deployer argocdhelm adopts uniform local-chart layout #665 — --deployer argocdhelm adopts uniform local-chart layout (transformation handles both input shapes; static layer moves per-component)

Strict ordering: 662 → 663 → 664 → 665. No breaking change for any current user until they explicitly opt into --vendor-charts.

Problem/Use Case

The current deploy script branches between three component types — Helm charts (registry-based), Kustomize builds, and raw manifests — each with different install mechanisms and special-case handling (CRD race workarounds, async operator skips, etc.). This makes the script complex and fragile.

Additionally, Helm charts are referenced by remote registry URL, so the bundle requires registry access at deploy time and isn't self-contained.

Design decisions driving the decomposition

The decomposition reflects three architectural choices surfaced during planning:

1. Separate "uniform layout" from "vendoring." The cheap, high-leverage refactor (every deployer consumes one format) is orthogonal to the costlier opt-in (vendoring upstream chart bytes). Splitting them lets the format refactor unblock [Feature]: Helmfile deployer for declarative, bash-free deployments #632 (helmfile deployer) and future deployers (Flux, etc.) without coupling it to bundle-time network / auth / size costs.

2. Chart.yaml presence signals local content. Every numbered folder is either a local chart (Chart.yaml present: wrapped Kustomize, wrapped raw manifests, vendored Helm, or an injected -post chart) or an upstream reference (Chart.yaml absent: pure Helm non-vendored). Deployers branch on that one fact. No umbrella-Chart.yaml-with-dependencies pattern — rejected to avoid reintroducing helm dependency update at deploy time.

3. Mixed components emit two folders in non-vendored mode. Rather than a "mixed" special case, the bundle layer emits NNN-<name>/ (primary upstream ref) + NNN'-<name>-post/ (injected wrapped chart for the raw manifests) — positioned to install in order via numeric prefix (and sync-wave+1 for Argo CD). The "mixed" concept disappears at the bundle layer. Vendored mode (--vendor-charts) collapses the two back into one wrapper chart with helm hooks.

Success Criteria

• All component types (Helm, Kustomize, raw manifests) produce bundle folders that every deployer can consume uniformly.
• Remote Helm charts can be pulled and vendored locally at bundle time via --vendor-charts (opt-in; air-gap deployable when set).
• Numbered folder prefixes provide explicit deployment ordering.
• Deploy script + Argo CD Application generation both branch on a single fact (Chart.yaml presence), not on component-type metadata.
• Bundle is fully self-contained and deployable without registry access when --vendor-charts is on.
• Zero breaking change for users who don't opt into --vendor-charts.

Component

Bundlers

Priority

Important (would improve my workflow)

Compatibility / Breaking Changes

• --deployer helm users see a new on-disk bundle layout (numbered folders; Chart.yaml + templates/ for wrapped components; primary + -post folders for mixed components). Bundles auto-regenerate; no hand-migration needed.
• Non-vendored --deployer argocd users see file-path renames only; Application shape unchanged for pure-Helm cases.
• Mixed components under --deployer argocd newly deploy their raw manifests (previously silently dropped — this is a fix-forward).
• --vendor-charts opt-in preserves the CVE-yank fail-loud signal for non-vendored bundles; vendored bundles silently deploy the frozen chart version, documented as an explicit tradeoff.

Related

• [Feature]: Helmfile deployer for declarative, bash-free deployments #632 — Helmfile deployer. Consumes the uniform layout from [Feature]: Uniform numbered local-chart bundle layout + --deployer helm adoption #662 as a clean input; parallel installs via needs: tracked there.
• [Feature]: Support dynamic install-time values in bundle output #515 — Dynamic install-time values (--dynamic flag). Already merged; preserved by every sub-issue via per-component cluster-values.yaml.
• Bridge Jobs for deploy/undeploy lifecycle flow control #610 — Bridge Jobs for deploy/undeploy lifecycle. Complementary but independent; Bridge Jobs for deploy/undeploy lifecycle flow control #610's readiness.yaml / cleanup.yaml convention lives at a different layer.