How The Harness Works · Config Workshop

Generated at: 2026-07-30T12:38:02.000Z UTC · source: committed helm-expt evidence for this rendered repository document.

UNOFFICIAL/EXPERIMENTAL

The Helm experiment harness turns public Helm charts into reviewed cub installer packages, checks the rendered Kubernetes objects against regular Helm output, and records the evidence needed to manage those objects in ConfigHub.

The useful unit is the rendered object set for a named base variant. A user can inspect that object set, compare it with Helm, scan it, upload it to ConfigHub, create derived ConfigHub variants with approved post-render refinements, and attach receipts for what was rendered, mutated, checked, approved, applied, or observed.

Seven-Stage Lifecycle

The harness uses the same seven stages for every chart:

Stage	What it manages	User value
1. Acquire and pin	Chart source, dependencies, digests, provenance.	The input is fixed and reviewable.
2. Render and capture	Helm render inputs, generated facts, capability profile, render parity.	The Kubernetes objects are known before install.
3. Shape base variants	Supported install shapes such as `default`, `existing-secret`, `no-crds`, or HA.	Choices are named variants, not scattered values files.
4. Scan and gate	Exact rendered objects, policy findings, install decision.	Checks run on the output that will be used.
5. Settle prerequisites	Target facts, preflight needs, approvals, signatures, delivery requirements.	External dependencies are visible before deploy.
6. Publish and deploy	OCI/GitOps/apply handoff and lifecycle routing.	The handoff has evidence and ordering.
7. Observe and operate	Live state, freshness, drift, promotion, upgrade, rollback.	Day-1 and day-2 operations have receipts.

Render parity is the first trust boundary:

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.

regular Helm render and cub installer render produce the same Kubernetes object
set under recorded inputs, except for explicitly classified support objects or
intentional differences.

Render parity proves the desired non-hook object set. Hooks, webhook readiness, controller-populated fields, GitOps sync, drift, and upgrade behavior require lifecycle, handoff, or observation receipts.

The detailed doctrine is Seven-Stage Helm Lifecycle. For the user-facing proof boundaries across the tools, see Chain Of Proof.

User Value

Helm often compresses install, render, release history, and cluster-side effects into one workflow. The harness separates those concerns so each one can be reviewed and checked.

Helm lifecycle stage	Common pain	Harness output	User value
Discover chart	Popular charts still hide behavior.	Catalog entry, chart dossier, pain report, support scope.	Known risks are visible before install.
Choose install shape	Values files hide intent and variants are ad hoc.	Named installer bases such as `default`, `existing-secret`, `no-crds`, or HA.	The install shape is explicit.
Add values or overlays	It is unclear whether a change needs a new render.	Helm render and object-shape changes go through `cub installer`; approved post-render refinements go through derived ConfigHub variants.	Customization has a clear route.
Render	Templates, capabilities, `lookup`, generated values, and dependencies are implicit.	Source locks, dependency locks, effective values, capability profile, target facts, generated facts.	The render can be reproduced and explained.
Compare	Teams often review values instead of exact objects.	Helm-equivalence receipt and classified differences.	Approval is based on Kubernetes objects.
Review and scan	YAML review is noisy and scans can drift from the install output.	Object inventory, rendered scans, gates bound to manifest digests.	Misconfig checks run on the exact output.
Upload and manage	Helm release history is limited as a governance record.	ConfigHub Units, labels, revisions, links, receipts.	Teams can diff, search, approve, and audit config.
Create derived variants	Copying values files across environments loses provenance.	`cub variant create` clone/link plus guided variant creation.	Environment, region, and customer variants can be previewed and checked.
Deploy or hand off to GitOps	Desired, applied, and live state blur together.	OCI/GitOps handoff plus apply, publish, and observation receipts.	Teams know what was handed off and what was observed.
Observe live state	Observation freshness decays.	cub-scout, GitOps, or controller receipts with timestamps and TTL.	Evidence has an explicit freshness boundary.
Upgrade, patch, or roll back	Chart drift and release-state coupling make day-2 changes risky.	Upgrade/rollback receipts, production dispositions, legacy patch review.	Change is managed as a proven variant revision.
Hooks and lifecycle actions	Hooks depend on cluster state and phase.	Hook inventory, lifecycle policy, Argo/GitOps translation where safe, blockers where unsafe.	Lifecycle risk is visible before production use.

The pattern is:

chart
-> cub installer recipe/package
    -> named base variants
    -> exact rendered objects
    -> scans, gates, and receipts
    -> ConfigHub Units
    -> derived ConfigHub variants with approved post-render fields, facts, targets, gates, links, and checks
    -> live or GitOps observations

Current Evidence

The current repo verifies:

100 recipe/package proof artifacts
20 top-chart catalog entries with bespoke variants
20/20 top-20 charts with at least one local kind live/e2e receipt
20/20 top-20 charts with chart-level ConfigHub upload, scan, and safe-ops receipt sets
20 per-chart Helm pain reports
top-500 catalog analysis
hook/lifecycle risk estimate for the top-500 scan
latest-version candidate proofs for 6 moved top-20 charts

Per-base lane status is tracked separately. A chart can have a chart-level proof set while one of its bases still needs ConfigHub, local live, GitOps, parity, or lifecycle evidence.

The remaining work is productization: turning repo-proven scripts into product surfaces for import, analysis, preflight, compare/prove, scan, and variant creation.

Stage 1 - Chart Intelligence

Chart intelligence records what the chart is, which inputs are being used, and which Helm behaviors need control points.

Inputs:

public chart or wrapper chart
chart version
values and overlays when supplied
dependency closure
target capability assumptions

Artifacts:

source-lock.yaml
dependency-lock.yaml
effective-values.yaml
helm-pain-report.yaml
helm-plan.yaml
chart-dossier.yaml
top500 catalog analysis

Current implementation:

AI-assisted chart analysis
repo generators
repo verifiers

Roadmap surface, not a current command in this repo:

cub installer analyze

This is where hidden chart behavior becomes visible before install.

Stage 2 - Recipe And Package Construction

Recipe and package construction turns the chart and selected inputs into a durable installer artifact.

Artifacts:

packages/<repo>/<chart>/<version>/installer.yaml
recipes/<repo>/<chart>/<version>/recipe.yaml
variants/<variant>/variant.yaml
install-checks.yaml where available
target fact requirements
generated fact policy
capability profile

Current implementation:

repo generators create cub installer packages and chart-specific recipe artifacts

Roadmap surfaces, not current commands in this repo:

cub installer import helm
cub installer preflight

helm template is the quick local render path. It is useful for inspection, debugging values, CRD/resource split checks, and Helm-equivalence baselines.

cub variant upload is the quick one-shot ConfigHub load path. It is useful when the goal is to create ConfigHub Units from rendered files or a literal OCI bundle now.

A cub installer recipe/package is the reusable catalog artifact. Import is the planned bridge from the fast Helm command paths into the maintained recipe/package path. It is not a current command in this repo.

Stage 3 - Render, Compare, And Prove

The render stage checks that the cub installer path produces the expected Kubernetes objects.

Artifacts:

rendered/release-objects.yaml
rendered/object-inventory.yaml
helm-equivalence-receipt.yaml
render-receipt.yaml
scan-receipt.yaml
install-gate.yaml
variant-revision.yaml

Current implementation:

npm run verify
per-chart compare/proof scripts
tamper-detection self-tests
verify-install helpers for user-side Redis checks

Roadmap surfaces, not current commands in this repo:

cub installer compare
cub installer prove
cub installer scan

The proof unit is the exact rendered object set.

Stage 4 - ConfigHub Upload, Governance, And Derived Variants

After rendered objects are reviewed, ConfigHub stores them as Units and gives teams revision history, labels, links, approvals, scans, and variant operations.

Artifacts:

ConfigHub proof transcripts
upload receipts
function-scan receipts
safe-ops receipts
server-side variant clone receipts
variant creation guidance

Current implementation:

cub installer upload
cub variant create
cub variant promote
cub unit list/data/tree/diff/revision
cub changeset and unit approve/apply/cancel lanes where proven
ConfigHub function scans

Roadmap surfaces, not current commands in this repo:

Creator preview
Creator check
variant diff
variant update/rebase
operation receipts

cub variant create provides the clone/link substrate. cub variant promote provides the upstream-to-downstream catch-up command. The product layer should make the safe variant-creation and promotion paths easy to preview, check, and explain.

Stage 5 - Live, GitOps, And Lifecycle Evidence

Live evidence records what happened after apply, publish, or GitOps sync.

Artifacts:

local kind observation receipts
production disposition reports
observation freshness SLO
hook lifecycle strategy
GitOps/cub-scout references

Current implementation:

local kind live/e2e receipts for top-20
optional cub-scout object-set, workload, and prerequisite receipts in live run dirs
workerless observation guidance

Roadmap surfaces, not current commands in this repo:

cub observe
cub target observe
GitOps compatibility reports
hook/lifecycle receipts
upgrade and rollback receipts

ConfigHub stores desired/config truth and submitted observation receipts. Runtime claims depend on fresh receipts from GitOps controllers, cub-scout, CI, operators, or human-triggered checks.

Stage 6 - Scale, Maintenance, And Commercial Lanes

The scale lane keeps the public proof honest and identifies work that belongs in managed or commercial product workflows.

Artifacts:

root CATALOG.md
per-chart CATALOG.md
top500 catalog analysis
catalog promotion review
production disposition lane
legacy patch review
latest top-20 refresh snapshot
latest top-20 candidate proofs
wave-2 variant work orders
commercial support-tier guidance

Current implementation:

generated and verified corpus outputs
top-20 supported for local/test scope
latest-version refresh before catalog roll-forward
100 proof-grade packages
top-500 planning analysis

Roadmap surfaces, not current commands in this repo:

cub catalog search/show/install
managed private import
managed overlay import
patch and lifecycle intelligence workflows

The public catalog proves the method on popular charts. Managed workflows extend the same method to private charts, overlays, old versions, hooks, production windows, and fleet operations.

Roadmap Tracking

The user docs explain the model and the current evidence. The execution queue and issue mirror live in planning docs:

Planning file	Use it for
Next 20 Tasks	Prioritized workstream queue.
Issue Backlog	Current issue mirror and capability roadmap.
Current Handover	Current status for another engineer or agent.

The original proof gates for Redis, schemas, effective values, generated facts, capability profiles, top-N harness, freshness, and upgrade/rollback receipts are closed and verified by the current harness. The remaining work is mostly productization and coverage depth: importer/analyzer/preflight/proof/scan surfaces, derived-variant Creator flows, production decisions, and live lanes.

Summary

Helm remains the chart source. helm-expt proves a durable path from public Helm charts to cub installer recipes, ConfigHub variants, rendered object sets, scans, gates, receipts, and live observations.

The harness proves this today with 20 top charts and 100 recipe/package artifacts. The next product work is importer/analyzer/preflight/proof/scan support in cub installer and Creator flows over cub variant create.

Doctrine Checkpoints

If it changes Helm render inputs, object shape, object count, or lifecycle
semantics, route through cub installer.
If it refines already-rendered ConfigHub Units through approved post-render
fields, facts, links, targets, gates, functions, or checks, use cub variant
create plus guided variant creation.
If it depends on live cluster state, require target facts, preflight,
lifecycle receipts, or fresh observations.
If it is chart-specific pain, record it in helm-pain-report.yaml.
If it is a general pattern, put it in the maintained product guidance.