Helm Import Contract · ConfigHub Workshop

cub helm template is the fast local render path:

chart + values + flags -> rendered Kubernetes objects on disk/stdout

It is useful for inspection, debugging, CRD/resource split checks, and as the regular Helm baseline for equivalence receipts.

cub helm install is the fast ConfigHub action path:

chart + values + flags
-> <component>-helm Space with a HelmSource Unit
-> <component>-base Space with rendered Kubernetes Units

That is useful for storing an arbitrary chart and its inputs without first building a maintained catalog package. The base is untargeted. If no namespace is supplied, it uses confighubplaceholder until a deployment variant supplies the real namespace.

The direct command drops Helm hooks by default. --include-hooks keeps them as ordinary resources but does not run their Helm lifecycle. It includes CRDs unless --skip-crds is set. It cannot render charts that require live lookup results or non-default capability information.

The maintained recipe path is different:

New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.

chart or wrapper chart
plus values, overlays, dependency closure, and render context
-> cub installer recipe/package
-> supported base variants
-> rendered object revisions
-> Helm-equivalence receipts
-> scans, gates, upload/publish receipts, and live evidence

Import is the bridge between those paths. It should let a user graduate from "render/load this chart now" to "maintain this chart as a reusable, variant-aware, proof-bound catalog entry."

One possible future product command is:

cub installer import helm

That command does not exist. Today this repo uses generators and proof scripts to create and check maintained recipe artifacts explicitly.

What Import Must Capture

Every maintained import must record:

Area	Required Artifact
chart identity	source lock with repository, chart, version, and digest
dependencies	dependency lock
render inputs	effective values, selected overlays, capability profile, target facts, generated facts policy
chart behavior	Helm pain report and control points
install shapes	supported base variants and package bases
rendered output	rendered objects, object inventory, and immutable revision
correctness	Helm-equivalence receipt comparing regular Helm output with `cub installer setup` output
safety	scan receipt and install gate
operation	ConfigHub upload/publish receipt, target facts, derived variant mapping, live or planned observation receipt

Here is what the command does. cub installer is an open-source plugin for the cub CLI. cub installer setup pulls a catalog package and writes its Kubernetes files locally, leaving delivery to kubectl, Argo CD or Flux. The generated scripts stop before doing any work when the plugin or kustomize is missing.

Where Choices Go

User Choice	Route
Helm values file or `--set` changes rendered objects	importer creates or updates a `cub installer` base variant
Kustomize overlay changes rendered objects	importer treats it as a recipe/base overlay with a digest and rendered diff
wrapper chart plus platform/customer overlay values	managed overlay import; classify platform-owned, customer-owned, and target facts before render
existing Secret, StorageClass, IngressClass, CRD, API, or namespace requirement	recipe requirement plus variant target-fact binding
generated password/cert/random/time value	generated fact before render, then bind immutably
environment, region, target, labels, gates, observation policy	derived ConfigHub variant after upload; no Helm rerender

The boundary is simple:

If the Kubernetes objects change, go through import / recipe / base variant.
If only the operating context changes, use a derived ConfigHub variant.

Golden Examples

Example	What It Shows
Redis	public chart import with `default` and `reuse-existing-secret` bases
ExternalDNS managed overlay	wrapper chart plus platform values plus customer overlay values
Redis prod-us-east Creator golden	post-render ConfigHub variant from a reviewed base

The generated workdown checks these examples in:

data/attack-plan-workdown/helm-import-contract.csv

Regenerate and verify:

npm run attack-plan:generate
npm run attack-plan:verify