Helm → ConfigHub customization decision tree

Status: working design reference. Sources: installer consumer guidance plus helm-expt docs/reference/customization-algorithm.md and docs/user/change-routing-before-oci.md.

Tags:

• [proven]: demonstrated by committed helm-expt proof or live evidence.
• [observed]: observed as a risk or recurring pattern.
• [design]: still a product decision or implementation gap.

The one rule

Don't ask users to abandon Helm behavior. Capture it, classify the change, render exact objects, prove Helm-equivalence, then deliver only digest-bound variants with receipts. The package source tree (./package/) is read-only to consumers - never kustomize edit it; the next setup --pull overwrites it.

The model behind the menu (chart → recipes → base variants → derived variants)

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.

1 Helm chart
 └─ N recipes  (incl. a default recipe)                     - the cub installer mapping(s)        [helm-expt]
      └─ N base variants, placeholdered  (incl. a default)  - render-time shapes; placeholders    [helm-expt]
         │                                                     are the fill surface. Each base is
         │                                                     rendered, Helm-equivalent, pinned.
         │                                                     (no-crds · existing-secret · ha · ingress-tls · …)
         └─ N×M derived variants                            - env / region / customer fills on a   [ConfigHub only]
                                                              chosen base (cub variant create;
                                                              no re-render). NAMED, LISTED, and
                                                              TESTED in helm-expt; instances live
                                                              in ConfigHub.

• helm-expt owns the recipes + base variants (rendered, equivalence-proven, placeholdered) and the names / list / tests of the derived variants.
• ConfigHub owns the derived-variant instances (the long tail).
• The render boundary is the rule: changes the rendered object set → a new base variant (re-render + Helm-equivalence); only changes operating context (target/env/region/gates/fills) → a derived ConfigHub variant (no re-render). This is Lens B below.

Support outcomes

A chart is supported when every Helm quirk it uses - lookup, hooks, .Capabilities, generated secrets, tpl, raw / post-renderers, CRDs / webhooks - is either modeled (static: declared fact · named capability profile · generated-fact receipt) or explicitly disclosed (operator-decision · honest blocker). Zero silent gaps. That faithful disclosure is the support - not a claim that runtime behavior was statically replicated.

For the public catalog outcome, the bar is higher:

Every supported default and declared main choice should have reproducible
render evidence plus live-cluster evidence. Missing live evidence stays visible
as `missing` lane backlog.

Analysis-tier rows can be proof-grade without live coverage. A chart choice should not be described as fully catalog-supported, production-supported, or live-verified until the relevant live lanes have committed receipts. Variant richness is an enhancement; every variant that is advertised as supported needs the same outcome tracking as the default.

Two complementary lenses (read both)

The consumer guide and the routing doc answer different questions. Use them together.

Lens A - "which knob do I turn?" (installer consumer guide: 3 override layers, use the lowest that fits)

Lens B - "where does the change live?" (helm-expt: 3 decisions, in order)

1. Changes rendered K8s objects? → cub installer base variant (re-render + Helm-equivalence).
2. Only changes how a reviewed set is operated (target/env/region/gates/labels)? → derived ConfigHub variant (clone Units, no re-render).
3. Neither, but required before delivery? → delivery prerequisite (facts, scans, gates, approval, OCI digest, controller config).

How they map: Lens-A Layers 1–2 (inputs / --set-image) are object changes → Lens-B base path. Layer 3 (post-install cub mutation) is a narrow post-render edit → Lens-B derived/operating (survives re-render). Plain user wording: "changes the Kubernetes objects → new installer base" vs "changes operating context → ConfigHub variant" vs "delivery prerequisite → satisfy/record before the OCI artifact is used."

Step 0 - pick a named fork (the menu the user sees first)

Every catalog-supported chart presents a small, predictable menu (shared vocabulary - HELM_FORK_VOCABULARY.md), not a values free-for-all:

• default - works out of the box, zero required input. (Start here.)
• parameterized - same shape as default, with the fill-safe fields exposed as placeholders to fill.
• standard forks (only those that apply): existing-secret · ingress-tls · ha · no-crds · minimal · tls. These change the rendered object shape, so each is a real, Helm-equivalent, pinned base. Forks compose (e.g. existing-secret + ingress-tls).

Pick one fork (or a composition), then customize within it by filling placeholders / facts (derived variant, no re-render). The forks below (F1–F3) are the checks each chosen fork must pass.

Early forks a newcomer hits FIRST (campaign-grounded)

What this command does. cub installer is a released, open-source plugin for the cub CLI. cub installer setup pulls a catalog package and writes its Kubernetes files locally. It does not apply those files to a cluster; use kubectl, Argo CD, or Flux for delivery. The generated scripts stop before doing any work when the plugin or kustomize is missing.

START - pull a public package → setup → upload → ConfigHub → OCI → Argo/Flux
│
├─ Fork 1 · NAMESPACE  (F1 / F1b)                                  [proven]
│   `installer setup --namespace <ns>`. Does the package honor it?
│   • Simple charts (18/20): yes (PR #95 set-namespace transformer) → any ns.
│   • Complex charts w/ ns refs embedded in spec (consul, kube-prometheus-stack):
│       install at the CANONICAL namespace. (helm-expt#96, F1b.)
│   GUARD: render must contain a single namespace; abort if >1.
│
├─ Fork 2 · IMAGE PINNING  (F2)                                   [observed]
│   Default bases ship floating/`:latest` tags (e.g. bitnami/nginx:latest) -
│   non-reproducible over digest-bound OCI delivery.
│   • Bump/pin via Layer 2: `installer setup --set-image NAME=myrepo/img@sha256:…`
│     - REQUIRES an `images:` block in the chosen base. If absent, it fails fast;
│     fall back to Layer 3 (`cub function do set-container-image`).
│   • Catalog gap: default bases should ship pinned digests (no helm-expt issue yet).
│
├─ Fork 3 · SECRETS  (F3)                                          [proven]
│   Does the base render a Secret?
│   • No (e.g. nginx http-clusterip) → proceed.
│   • Yes - default "static-passwords"/"default" base over OCI→Argo is
│       GREEN-BUT-BROKEN: `installer upload` never uploads rendered Secrets, the
│       pod sits in CreateContainerConfigError ("secret not found"), and Argo
│       still reports Synced (SILENT). Do NOT use the password-generating default
│       for GitOps delivery.
│       → Use the chart's existing-secret base + provide the Secret out-of-band
│         (kubectl / ExternalSecrets / Vault). [proven: postgresql, redis, mysql, mongodb → Ready]
│       → [design] required-secret validation gate +
│         typed secret reference system are the planned guards.
│
└─ then classify the change & route via the two lenses ↓

Classify the customization (sets base-vs-variant)

values-only · target fact (existing Secret/StorageClass/IngressClass/CRD) · generated fact (password/cert generated once, before render) · capability profile · lifecycle / hook / CRD policy · extension slot · Kustomize overlay / patch · post-renderer / script · operate / observation.

Day-2 lifecycle (from the consumer guide)

edit inputs / --set-image / cub mutation
        │
   installer plan        ← read-only diff per Space (Package=<pkg> filter); shows + ~ - and an Images: footer
        │
   installer upload      ← reconcile: opens ONE ChangeSet per Space; updates/adds/empties
        │                   (a Unit that left the render is EMPTIED, not deleted;
        │                    DestroyGate-guarded Units are refused)
        ▼
   revert: cub unit update --patch --restore Before:ChangeSet:<id> …   (printed by upload)
            • updates → reverted by the restore
            • creates → NOT auto-reverted (delete the Unit)
            • empties → restore the pre-empty revision (not in the ChangeSet)

Upgrade (re-pull a new version)

installer setup --pull oci://…:<new-ref> against the existing work-dir → schema-diff machinery: new-with-default adopted (logged), new-required-without-default prompted (non-interactive fails fast naming them), removed dropped, type-changed errors. Components: if prior selection == old default preset, adopt the new default preset. Then installer plan → installer upload --yes. Image-only upgrade = --set-image (no --pull needed).

Multi-package, signing, recovery

• Multi-package (parent declares deps): setup runs deps update automatically; installer upload --space-pattern '{{.PackageName}}-prod' gives each package its own Space. installer deps tree audits the DAG.
• Signing/trust: installer verify <ref> --key cosign.pub (or keyless); enforce on every pull via ~/.config/installer/policy.yaml (enforce: true).
• Recovery (lost work-dir): the installer-record Unit on ConfigHub holds the spec + upload.yaml; re-pull + cub unit data … installer-record + installer render.

Variant lineage & the OCI boundary

recipe → base variant (rendered shape; Helm-equivalent) → derived ConfigHub variant (operating context) → custom overlay (wrapper+platform+customer values; usually ConfigHub Server / managed tier). Each digest-bound to its parent. After OCI publication the artifact IS the desired object set - no untracked GitOps patch / manual edit / post-render script; object changes route back to the base path and republish.

Pipeline, confidence labels, tiers

render → compare vs helm template (equivalence) → scan rendered objects → gate (allow/warn/block) → promote/reject → settle delivery prereqs → OCI publish (digest+sig) → Argo/Flux. Labels: proof-grade · catalog-candidate · catalog-supported · deprecated · blocked. Tiers: public catalog proof → ConfigHub managed variants → managed overlay import → enterprise fleet.

What is grounded vs still open

• Proven (use with confidence): namespace routing for simple chart rows, the secret silent-fail risk and existing-secret fix paths, Helm-equivalence across the maintained proof rows, selected render-to-OCI-to-Argo runtime lanes, and rollback through ConfigHub revision in prior live evidence.
• Observed: Fork 2 (:latest).
• Not fully exercised live across the catalog: Layer-2 --set-image, derived/custom variants, hooks lifecycle, upgrade schema-diff, multi-package --space-pattern, and signing enforcement.
• Open work this maps to: namespace references embedded in object specs, proof regeneration coupling, typed secret references, required-secret validation, lifecycle/rollback contracts, and image pinning.

Sources

installer: consumer guide, author guide, and principles. helm-expt: docs/reference/customization-algorithm.md, docs/user/change-routing-before-oci.md, docs/user/creating-variants.md, docs/user/custom-overlays.md, docs/user/product-support-tiers.md, docs/user/hook-lifecycle-strategy.md. Generated evidence: data/status-dashboard/summary.md, data/outcome-coverage/summary.md, and data/live-kind-parity/summary.md.