Customization Algorithm

UNOFFICIAL/EXPERIMENTAL

This document defines how a Helm-user customization becomes a ConfigHub variant, and where each piece of new information belongs.

For the full chart-to-recipe workflow, including the main "where pieces go" table, see Introduction To The Harness. For the short guide to variant creation through human, AI assistant, and bulk flows, see Creating Variants. For a concrete chart walkthrough, see Prometheus Overlay And Promotion Example. For wrapper charts, platform values, and customer values, see Custom Overlays. For the delivery boundary, see Choosing Base Variants, Derived Variants, And Delivery Changes.

The product rule is:

Do not ask users to abandon Helm chart behavior.
Capture the behavior, classify the customization, render exact objects, then
promote only digest-bound variants with receipts.

Inputs

A customization request can arrive from:

• a Helm values file;
• --set values;
• an umbrella chart dependency choice;
• a Kustomize overlay or patch;
• an existing Secret, ConfigMap, StorageClass, IngressClass, CRD, or API;
• a cloud/provider-specific setting;
• an operator lifecycle requirement;
• a user-submitted use case not already in the catalog.

Supported Overlay Modes

This project must support all common Helm customization inputs, but not by flattening them into one vague "variant" bucket.

Algorithm

1. Start from the chart recipe.

The recipe owns chart identity, source lock, dependency lock, value model, known control points, fact requirements, lifecycle policy, and allowed extension slots.

1. Classify the requested customization.

   values-only
   target fact
   generated fact
   capability profile
   lifecycle / hook / CRD policy
   extension slot
   Kustomize overlay / patch
   post-renderer or script
   operate / observation requirement

1. Decide whether it belongs in the recipe or the variant.

The user-facing decision should be phrased simply:

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.

   This changes Helm render inputs or object shape, so it needs a cub installer
   base.
   This is an approved post-render refinement of an uploaded base, so it can be
   a derived ConfigHub variant.

The supporting proof can record the exact digests, paths, facts, checks, and receipts behind that decision.

Recipe-level:

   chart source
   dependency closure
   value schema and known value paths
   fact requirements
   allowed extension slots
   lifecycle policy
   forbidden or review-only mechanisms

Variant-level:

   chosen values
   selected components
   target fact bindings
   capability profile
   generated fact bindings
   explicit overlays
   namespace and release name

1. Render a candidate variant revision.

The revision binds:

   recipe digest
   effective values digest
   capability profile digest
   target/generated fact binding digest
   renderer/version/flags digest
   rendered object set digest

1. Compare against regular Helm when Helm equivalence is expected.

Passing means:

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.

   regular helm template output
     == cub installer setup output
     plus allowed installer support objects

1. Scan the exact rendered objects.

Scans run on the rendered object set, not on a guess about values.

1. Gate the revision.

Gate decisions are:

   allow
   warn
   block

A warning can be acceptable for local proof but still blocked for production until review or observation requirements are satisfied.

1. Promote or reject the variant.

If broadly useful, the variant can become catalog-supported. If organization-specific, it remains a private/local variant. If unsafe or ambiguous, it is blocked with a reason.

1. Settle delivery prerequisites before OCI handoff.

OCI delivery should publish the reviewed object set that Kubernetes or GitOps will consume. Before that handoff, the route must be explicit:

   base variant selected
   derived ConfigHub variant selected, if needed
   target facts bound or deferred with a receipt
   generated facts bound
   scans and gates complete
   hook/CRD/lifecycle decision recorded
   approval state known
   OCI digest, signature, and access method recorded

If a late change requires Helm to rerender, changes object count or install shape, or touches fields outside the approved post-render contract, it routes back to the cub installer base path. If it is an approved post-render refinement, it can be a derived ConfigHub variant before publication or apply.

Where Common Customizations Go

Product Tier Routing

The same algorithm applies across product tiers, but the required product surface changes.

See Product Support Tiers For Helm Scenarios.

Hook Customization Rule

A request to enable, disable, replace, or rely on Helm hook behavior is not a normal values-only customization.

Treat it as:

lifecycle / hook policy
target fact or preflight requirement
execution-or-skip decision
observation requirement

The rendered normal object set can still be deterministic. The hook action is not proven until a lifecycle receipt records whether it ran, was skipped, was converted into a test/check, or was blocked.

Confidence Labels

Each variant should carry one of these statuses:

proof-grade
catalog-candidate
catalog-supported
deprecated
blocked

Proof-grade means the variant is mechanically proven. Catalog-supported means it is also the recommended, simple, safe experience for Helm users.