UNOFFICIAL/EXPERIMENTAL
Render parity is only the first question.
For easy charts, proving that cub installer renders the same Kubernetes objects as Helm is enough to start. Serious charts also depend on things that are already true, or must become true, in the target cluster.
This repo calls those requirements target prerequisites.
Examples:
- CRDs must already exist before a CRDs-off base is applied.
- A Secret must exist when the chart is configured to reuse one.
- A webhook certificate may be generated by a controller after apply.
- An APIService may only become healthy after the backing service is ready.
- A Helm startup check may need to become a post-apply observation.
Requirements known when a base is created are recorded in its variant file. The generated render intent then shows them under targetFacts.declared. A review completed after a retained base was published can be recorded in config-catalog/target-fact-reviews.yaml instead. This adds the decision and evidence without changing the historical base and its checksums.
targetFacts.actions is different: it records work derived from a failed or blocked live run. An empty action list does not cancel a declared Secret or CRD requirement.
Do not add targetFacts: {} just to close a gap. If a review finds that the base needs no separate target prerequisite, record the empty declaration and a review together. The review must say what was checked and link to the evidence. Without that review, the gap stays open.
The useful product claim is not only:
we rendered the same YAMLIt is:
we rendered the same desired objects, named the target prerequisites,
staged or checked them, observed the live result, and recorded the boundary
of the claimWhy This Is Better Than Plain Helm
Plain Helm can succeed or fail while mixing several concerns into one install step: render, prerequisite setup, hook execution, controller readiness, and live cluster behavior.
The catalog splits those concerns apart.
| Concern | Catalog treatment |
|---|---|
| Rendered object set | Compare regular Helm with cub installer output. |
| Prerequisites | Record target facts such as required CRDs or Secrets. |
| Lifecycle behavior | Route hooks and controller-owned fields into observations or support decisions. |
| Live result | Run local, GitOps, parity, or cub-scout observation lanes. |
| Claim boundary | Keep pass, watch, blocked, and refused rows visible. |
That is where the value starts for hard charts. YAML parity is necessary, but it does not prove that the target was ready or that the workload became usable.
Real Examples
cert-manager
The default cert-manager base does not render CRDs. That is a normal Helm shape, but the target cluster still needs the cert-manager CRDs before the controller can be treated as working.
The catalog now records those CRDs as target facts on the default base, syncs them into the installer package, and proves the base in the strict two-cluster Helm-vs-installer lane.
Evidence:
- base target facts:
recipes/jetstack/cert-manager/v1.20.2/variants/default/variant.yaml - installer package requirement:
packages/jetstack/cert-manager/v1.20.2/installer.yaml - live parity receipt:
runs/live-kind-parity/jetstack-cert-manager-default/receipt.yaml - lifecycle observation:
runs/lifecycle-observations/cert-manager-eso/jetstack-cert-manager-default/receipt.yaml
Vertical Pod Autoscaler
The VPA chart uses a generated webhook TLS Secret. Treating that as invisible Helm behavior would make the install look simpler than it is.
The catalog records the Secret as a target fact and proves both VPA bases in the two-cluster parity lane.
Evidence:
- target fact in the recipe:
recipes/autoscaler/vertical-pod-autoscaler/0.9.0/variants/default/variant.yaml - live default receipt:
runs/live-kind-parity/autoscaler-vertical-pod-autoscaler-default/receipt.yaml - live no-CRDs receipt:
runs/live-kind-parity/autoscaler-vertical-pod-autoscaler-no-crds/receipt.yaml
OpenTelemetry Operator
The no-CRDs base is useful only if the target cluster already has the required OpenTelemetry CRDs and cert-manager prerequisites. Those are now explicit target facts, not hidden assumptions.
Evidence:
- no-CRDs target facts:
recipes/open-telemetry/opentelemetry-operator/0.114.0/variants/no-crds/variant.yaml - live no-CRDs receipt:
runs/live-kind-parity/open-telemetry-opentelemetry-operator-no-crds/receipt.yaml - live default receipt:
runs/live-kind-parity/open-telemetry-opentelemetry-operator-default/receipt.yaml
How To Use This As A User
Before deploying a base, check the per-chart catalog page and the variant file. The chart page links the matching render intent, where the declaration, rendered objects, lifecycle routes, and Argo CD or Flux handling are kept together.
If the base lists target prerequisites:
- Stage them before applying the base, or choose a base that includes them.
- Keep the prerequisite source visible in the pull request or ticket.
- Run the relevant live check after apply.
- Do not call the install production-supported until the target scope has a production support decision.
The routing rule is:
| Change or requirement | Put it here |
|---|---|
| It changes the Helm-rendered object set. | Recipe or base variant. |
| It must already exist in the target cluster. | Target prerequisite / target fact. |
| It is a post-render environment, region, customer, target, label, approval, or observation choice. | Derived ConfigHub variant. |
| It is produced by a controller after apply. | Lifecycle observation. |
| It is cluster-dependent hook behavior. | Hook lifecycle route, observation, or support decision. |
For the aggregate view, start with data/live-kind-parity/summary.md and data/master-catalog-matrix/summary.md.