Helm Pain Points

UNOFFICIAL/EXPERIMENTAL

This project tracks Helm pain points in two ways.

First, it keeps a general matrix that explains how the model addresses common Helm problems:

data/pain-point-coverage/pain-points.csv
data/pain-point-coverage/summary.md

Second, each supported chart has its own pain report:

recipes/<repo>/<chart>/<version>/helm-pain-report.yaml

The general matrix says what kind of problem we are dealing with. The per-chart report says how that problem appears in a real chart and what the current disposition is.

The Short Version

Helm is a generator. One chart plus one set of values can produce many Kubernetes objects. Some values touch many objects and fields. After render, the output no longer explains clearly which input produced which field.

helm-expt addresses that by turning the render into explicit artifacts:

source lock
dependency lock
effective values
named base variant
rendered objects
object inventory
Helm-equivalence receipt
scan/gate receipts
pain report
optional live receipts

That does not solve every Helm problem by itself. It makes each problem visible and routes it to the right place.

Where The Answer Lives

General Model

The general answer is the same for every chart:

New to cub? Install the cub CLI first. You can pull and render public catalog packages without an account. Commands that save or change ConfigHub data require you to sign in.

Helm chart or wrapper chart
-> cub installer recipe/package
-> named base variant
-> exact rendered object revision
-> scans, gates, and receipts
-> ConfigHub Units and optional derived ConfigHub variants
-> OCI/GitOps handoff
-> cub-scout, controller, or other observation receipts

helm-expt is the public proof corpus: chart analysis, recipes, variants, rendered objects, receipts, and pain reports.

cub installer is the executable package path: setup, render, package, upload, and verify the reviewed bases.

ConfigHub Server is the managed operations layer: Units, variants, links, changesets, approvals, diffs, receipts, search, and governance.

GitOps controllers apply or pull the published desired state. cub-scout and other observers provide fresh live evidence. Workerless ConfigHub should not claim current cluster truth without a fresh observation receipt.

Per-Chart Proof

The general model is not enough by itself because Helm pain is chart-specific. Each maintained chart has a chart-level report:

recipes/<repo>/<chart>/<version>/helm-pain-report.yaml

That file answers:

What chart behavior caused pain?
Where did it land in the model?
Which variants are supported?
Which receipts prove the current claim?
What remains blocked, partial, or operator-reviewed?

Examples:

The 15 Pain Points

This is the user-facing view of the generated matrix in data/pain-point-coverage/pain-points.csv. The status column is deliberately conservative. "Strong" means there is current catalog evidence for the supported scope. "Partial" means the route is defined but still depends on live evidence, product work, or chart-specific review.

Go-templated YAML

Root cause: Helm templates are string-producing programs whose structure is discarded after render.

Current proof or representation: Render to explicit Kubernetes objects, keep object inventories, and record Helm-equivalence receipts. Status: strong-current-proof. Evidence: recipes/*/*/*/revisions/*/r001/receipts/helm-equivalence-receipt.yaml; data/outcome-coverage/base-outcomes.csv.

Handoff: ConfigHub stores rendered objects as typed Units with revisions, diffs, links, gates, and approvals. Installer packages the reviewed render as a named cub installer base. Live observation checks whether the applied objects exist and remain fresh.

Remaining gap: Complex template behavior is still chart-specific; provenance is not field-complete for every chart.

values.yaml sprawl

Root cause: Chart defaults, values files, globals, subcharts, and overlays make effective inputs hard to see.

Current proof or representation: Record effective values, value models, value-source maps where present, and named base variants. Status: strong-for-supported-bases. Evidence: recipes/*/*/*/effective-values*.yaml; recipes/*/*/*/variants/*/variant.yaml; data/outcome-coverage/base-outcomes.csv.

Handoff: ConfigHub turns chosen bases into managed variants with explicit parameters, labels, and links. Installer exposes supported bases rather than unbounded ad hoc values combinations. Live observation confirms target facts and live outcomes for a selected variant.

Remaining gap: Arbitrary user values and wrapper overlays need managed import or a new base variant.

State lives in cluster secrets

Root cause: Helm release history is stored as cluster state rather than a durable desired-state graph.

Current proof or representation: Keep pinned rendered object sets, receipts, source locks, dependency locks, and package receipts outside Helm release state. Status: partial-handoff. Evidence: data/outcome-coverage/chart-outcomes.csv; data/runtime-gitops/summary.md; data/live-kind-parity/summary.md.

Handoff: ConfigHub stores desired state, revisions, approvals, changesets, links, and operation receipts. Installer uploads reviewed objects as ConfigHub Units and package records. Live observation compares intended object sets with observed live resources.

Remaining gap: Queryable operation history and authority are ConfigHub Server concerns, not helm-expt alone.

Failed upgrades wedge releases

Root cause: Helm upgrade state and three-way merge can leave release state wedged or ambiguous.

Current proof or representation: Compute upgrade and rollback diffs where represented; record simulation receipts and risk notes. Status: partial. Evidence: recipes/*/*/*/operations/*/*receipt.yaml; data/variant-path-coverage/coverage-matrix.csv.

Handoff: ConfigHub operates on approved desired revisions with changesets and explicit rollback targets. Installer applies or uploads selected package bases rather than mutating Helm release state. Live observation checks convergence, drift, and stale live objects after upgrade paths.

Remaining gap: Real upgrade/prune behavior and rollback semantics require live controller evidence.

CRD handling

Root cause: Helm installs CRDs specially and does not manage CRD upgrades cleanly.

Current proof or representation: Expose CRDs in object inventories, provide no-crds bases where useful, and flag CRD lifecycle risk. Status: partial. Evidence: data/hook-lifecycle/summary.md; data/outcome-coverage/feature-outcomes.csv; recipes/*/*/*/helm-pain-report.yaml.

Handoff: ConfigHub gates CRD ownership and upgrade decisions before promotion. Installer packages CRD/no-CRD bases and preserves declared lifecycle policy. Live observation checks CRD presence, API availability, and webhook readiness.

Remaining gap: CRD upgrade behavior remains an operator-reviewed lifecycle path.

Subchart and dependency hell

Root cause: Umbrella charts, aliases, globals, and dependency closures hide where rendered objects come from.

Current proof or representation: Record dependency locks and chart dossiers; add scanner axes for alias, import-values, and library charts. Status: partial. Evidence: recipes/*/*/*/dependency-lock.yaml; data/chart-facts/chart-facts.csv; docs/reference/quirk-coverage.md.

Handoff: ConfigHub represents component relationships and cross-object links in the desired-state graph. Installer packages the reviewed dependency closure as the supported artifact. Live observation checks whether dependency-owned objects are healthy after apply.

Remaining gap: Dependency aliases and import-values need stronger scanner coverage.

No field-level governance

Root cause: Rendered YAML loses intent and field provenance unless captured at render time.

Current proof or representation: Record value-source maps where available and recover field reachability into graph fragments. Status: partial-strong-on-redis. Evidence: recipes/bitnami/redis/25.5.3/value-source-map.yaml; data/edge-recovery/edges.csv.

Handoff: ConfigHub uses Units, links, TransformPaths, functions, gates, and mutation sources for field-level control. Installer keeps package bases bounded and reviewed before upload. Live observation reports live drift at object/field level where supported.

Remaining gap: Field-complete provenance is not yet available for every chart.

No native secrets story

Root cause: Helm can generate or reference secrets, but GitOps and config stores need explicit secret handling policy.

Current proof or representation: Classify generated facts and target facts; provide generated-secret and existing-secret bases. Status: partial-known-gap. Evidence: recipes/bitnami/redis/25.5.3/install-checks.yaml; data/outcome-coverage/feature-outcomes.csv; data/live-helm-confighub-compare/summary.md.

Handoff: ConfigHub stores secret references, requirements, gates, and receipts rather than silently hiding credentials. Installer separates rendered Secrets from uploaded manifests where required and enforces externalRequires/preflight where available. Live observation checks required Secret presence and workload start success.

Remaining gap: Secret delivery on GitOps paths needs hard gates and production policy.

Hooks are brittle

Root cause: Helm hook resources depend on phase, ordering, cluster state, and delete policy outside plain desired YAML.

Current proof or representation: Detect hook-bearing charts and classify lifecycle routes; do not claim hook execution from render parity. Status: partial-doctrine. Evidence: data/hook-lifecycle/top100-hooks.csv; docs/user/hook-lifecycle-strategy.md.

Handoff: ConfigHub represents lifecycle actions, approvals, and receipts as explicit desired operations. Installer executes or hands off lifecycle steps only where the route is supported. Live observation checks post-hook resources, readiness, and failure conditions.

Remaining gap: Hook execution receipts are not complete for the hook-bearing catalog.

Multi-environment promotion is DIY

Root cause: Helm values files do not provide a durable variant model or promotion record.

Current proof or representation: Provide named bases, variant diffs, promotion examples, and target-bound derived variant receipts. Status: partial. Evidence: docs/user/creating-variants.md; docs/user/prometheus-overlay-promotion-example.md; data/derived-variant-target-bound/summary.csv.

Handoff: ConfigHub uses spaces, Units, labels, links, cub variant create, approvals, and changesets for derived variants. Installer supplies the reviewed base that derived variants clone or refine. Live observation checks each target after promotion.

Remaining gap: High-fanout propagation and override-protection need a stronger demo.

GitOps impedance mismatch

Root cause: Helm may render in different places, while GitOps controllers apply or re-render under their own context.

Current proof or representation: Render once, publish signed/pinned object sets, and prove the render under a declared flag profile. Status: partial-live-lane. Evidence: data/runtime-gitops/summary.md; data/live-helm-confighub-compare/summary.md.

Handoff: ConfigHub tracks desired revision and handoff target as managed state. Installer publishes/uploads package bases into ConfigHub/OCI paths. Live observation checks Argo/Flux sync and live object state.

Remaining gap: Controller-specific live proof is not complete for every base variant.

History without diffs

Root cause: Helm history records revisions but not durable object/field-level explanations.

Current proof or representation: Store variant revisions, object inventories, diffs, receipts, and operation simulations. Status: strong-static-partial-operational. Evidence: recipes/*/*/*/diffs/*.yaml; recipes/*/*/*/revisions/*/r001/variant-revision.yaml.

Handoff: ConfigHub provides queryable revision history, changesets, approvals, and diff views. Installer records package/action receipts. Live observation records observed live receipts against intended revisions.

Remaining gap: Fleet-wide query and operation history belong in ConfigHub Server.

Templating language limits

Root cause: Complex helper macros, tpl, raw manifests, and conditionals make behavior hard to audit.

Current proof or representation: Surface tpl/raw/extension slots and keep supported bases bounded. Status: partial. Evidence: data/outcome-coverage/feature-outcomes.csv; recipes/*/*/*/helm-pain-report.yaml.

Handoff: ConfigHub moves post-render customization to typed Units, links, functions, and views where possible. Installer rejects or gates unbounded extension slots for supported catalog entries. Live observation checks live effects of extension-derived objects.

Remaining gap: Not every template-language feature is field-provenanced yet.

Dry-run does not match reality

Root cause: Admission, defaulting, controllers, webhooks, and API availability affect stored/live state after render.

Current proof or representation: Keep render proof separate from live proof and record target facts/capability profile. Status: partial-live-dependent. Evidence: docs/user/verification-lanes.md; data/live-kind-parity/summary.md; data/lifecycle-observations/cert-manager-eso/summary.md.

Handoff: ConfigHub gates promotion on target facts, approvals, and observation policy. Installer runs preflight and target-fact collection where available. Live observation checks live state, freshness, API readiness, and workload health.

Remaining gap: Admission/defaulting parity is target-specific and requires live observation.

Chart ownership and fork burden

Root cause: Small local changes often force teams to fork charts or maintain fragile overlays.

Current proof or representation: Route shape-changing changes to new bases and post-render changes to derived ConfigHub variants. Status: partial-product-lane. Evidence: docs/user/change-routing-before-oci.md; docs/user/custom-overlays.md; docs/user/creating-variants.md.

Handoff: ConfigHub supports Creator flows, TransformPaths, functions, labels, links, and approvals over rendered Units. Installer provides maintained public and managed recipe bases. Live observation confirms the derived or promoted variant reached the target.

Remaining gap: Creator UX and managed imports are product work beyond current static catalog proof.

What To Read

Examples

Redis is the fast teaching chart. It shows the difference between a generated credential base and a reuse-existing-secret base.

kube-prometheus-stack is the main hard chart. It shows why the model matters for CRDs, webhooks, RBAC, dependencies, high object count, and blast radius.

The user should not need to read every receipt. The catalog should answer:

What variant should I use?
What objects will it install?
What Helm pain is known for this chart?
What has been proven?
What still needs a human decision or live evidence?