The model, in detail

Start with the question

The same four questions apply to Helm, cub installer packages, AICR, Kubara, OCI, YAML, and retained ConfigHub revisions:

A Catalog entry can shorten any investigation, but it is never a prerequisite for inspecting or processing a user's own configuration. The answer to each question must state its required inputs, evidence state, and result state. If the required destination or deployment does not exist, the check is blocked or not run. It is not a failed configuration, failed workload, or failed conformance result.

The flattening sequence

The four questions sit above a more detailed sequence. A maintained configuration records:

1. the source, version, and choices;
2. the exact Kubernetes objects produced or read from that source;
3. whether those objects can be retained as deployable configuration, with any source tool removed from the delivery path;
4. CRDs, hooks, setup Jobs, certificates, Secrets, cloud resources, controllers, models, ordering, and other lifecycle work;
5. variants, comparisons, tests, approvals, and promotions; and
6. release, delivery, live observation, and rollback evidence.

A record can be complete through flattening and still have no destination or deployment proof. The Catalog must show that boundary rather than collapsing every stage into one status.

Where OCI fits

OCI is the transport, not the tool and not the deployment proof. We use three different OCI roles:

The OCI page lists each shape we publish or read, with its producer and its consumer. Every shape there has one of these three roles, or is a record about one.

These artifacts can contain related objects but have different manifests and digests. A receipt binds stages by naming both identities and comparing the objects; it never calls unlike digests the same digest.

Two connected tracks

The model tracks both the configuration and the work needed to use it.

configuration lineage
  source and intent -> exact base -> derived variant -> promoted release

lifecycle handling
  requirements -> route intent -> destination resolution -> execution -> receipt

The tracks meet more than once. Source processing reveals lifecycle requirements. A derived variant can add, remove, or change them. The final route is therefore resolved only after the exact variant, destination, and delivery runtime are known.

The full operating sequence is:

source + processing intent
  -> select and lock the inputs
  -> flatten the source into exact Kubernetes objects
  -> capture an exact configuration revision
  -> identify lifecycle requirements
  -> decide the flattening lane for the intended path
  -> retain a reviewed base
  -> derive or update a variant
  -> recheck affected requirements, ownership, and flattening assumptions
  -> resolve lifecycle routes for the variant, destination, and delivery runtime
  -> compare, test, approve, and promote
  -> publish an immutable release
  -> reconcile the objects and perform the lifecycle work
  -> observe the result and record receipts

Helm, cub installer, AICR, Kubara, OCI, and YAML use the same decisions. They do not use the same tool. Helm renders, cub installer flattens a package, and AICR or Kubara compose or generate. A step can be a recorded no-op: literal YAML already contains exact objects, for example. A source refresh, variant change, or new destination can send the process back to an earlier decision.

Rules that keep the model usable

• Keep the source identity, exact-object digest, OCI digest, ConfigHub data hash, and release digest separate.
• Decide flattening for one processing boundary. Flattening an AICR or Argo CD wrapper does not flatten the charts it still references.
• Record missing lifecycle information as a gap. Do not translate silence into "no route required."
• Recheck lifecycle requirements and field ownership after a variant changes.
• Resolve the route after the exact variant, destination, and delivery runtime are known. A base route intent is input to that decision, not its final answer.
• Promotion compares objects, lifecycle changes, and protected fields. Delivery then performs the selected route, and a receipt records the result.

The core words

The site calls an entry's routes its plan and one route a step.

In one sentence: flatten the source into exact objects, keep the source and lifecycle context, then retain reviewed changes as variants that can be promoted and delivered.

Data pack

A data pack is your overrides, written as data and laid over a source catalog. It is versioned, and one source can have several. This page also calls it a pack.

A pack holds presets. A Helm recipe is the chart plus one preset. Three presets give three recipes and three bundles. The ECK operator chart 3.4.0 is a real case.

1 chart version, eck-operator 3.4.0
  1 pack, the values for its three presets
    preset "default"   -> recipe -> bundle
    preset "ha"        -> recipe -> bundle
    preset "no-crds"   -> recipe -> bundle
                                    each bundle can have variants in ConfigHub

AICR has the same shape under other names.

An AICR recipe can use several overlays at once, because they stack. A source can also have more than one pack, such as NVIDIA's catalog with a company pack laid over it.

No Catalog entry is built from an AICR data pack today.

Recipe

A recipe is the pinned inputs that produce one base. Every format has one. A recipe is inputs. It is not the configuration they produce, which is the base.

The Catalog's records call the file that holds a recipe the source and intent record. Until 11 October 2026 this page kept the word recipe for sources whose own tool uses it. The word now covers every format, because NVIDIA's AICR and this repository's recipes/ directory already use it this way.

AICR's own words

NVIDIA's AICR has names for what comes before the bundle and for a deployment. This model uses them for AICR entries.

AICR has no word for the steps between a constraint and validation. Its installer carries them out in order. This model writes them down as the plan.

NVIDIA documents these words in its data extension guide.

Do not create a render variant for literal YAML or another source that did not render. Its source-and-intent record links directly to its exact configuration revision.

How AICR's three parts compare

AICR describes itself in three parts, a data pack, a resolved recipe and an evidence bundle. The first two are the same as here. AICR's third part is the record of one run on one cluster, so it belongs to a deployment. This model's third part is the configuration itself, which can be read, compared and changed before anything is installed. The variant is the part this model adds.

Two OCI forms are kept, by decision

Every Helm entry is in OCI inside its chart's installer package. Where the flattening verdict permits, the entry also has a published bundle, which is one preset's flattened objects and its plan. Each entry page says which it has.

This was decided, and it is recorded in three places.

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.

Those records call the installer package's route render-late. A package holds objects that Helm has already rendered. The render that remains is the one cub installer setup does on your machine, and it runs no Helm.

Older sections of this page call a generator a source tool, and call generating flattening. The records use those words.

The earlier five stages

Earlier pages named five stages, Source → Base → Variant → Deliver → Run. They map onto the five words like this.

Two tools are involved in a bundle, at different stages. The generator produces the objects. cub variant upload then makes the base Space from them. Earlier pages named only one of the two.

The source and intent record

Every maintained base needs a record that explains where its objects came from and which choices produced them. We call this the source and intent record.

This is a role, not one file format. For Helm, the record is a HelmRenderIntent. it includes the native recipe, selected options, and generation receipts. Kubara records its selected source and generation inputs. Source OCI records the tool it contains or references. Literal OCI and plain YAML name their source digest or checksums, object inventory, remaining inputs, prerequisites, checks, and later transformations. Today, that information may live in a source Unit, Space metadata plus a committed receipt, or a generated base-variant record.

The record should let a new reader answer five questions:

1. What source produced these objects?
2. Which values or choices were used?
3. Which exact object digest did those choices produce?
4. What must exist or run before delivery?
5. Which checks and receipts support the result?

All maintained examples should answer those questions. Chart-specific records for hooks, CRDs, Secrets, setup jobs, and target facts are added when the configuration needs them; they are not copied into examples where they do not apply.

An arbitrary upload does not gain facts that ConfigHub cannot know. Generic checks can be attached automatically. A source adapter or review must supply the source details and any chart-specific lifecycle work; otherwise the missing information is recorded as a gap.

The four record layers

F1-F4 describe the records a reader can inspect. They are not four moments on a clock. F3 lifecycle information is discovered at the base and resolved again after a derived variant and destination are selected.

Flattening is not deployment. F2 produces or reads configuration files. F4 can deliver reviewed objects to live infrastructure. A base variant Space therefore has no Target until you choose to deliver it.

When routes are decided

A route copied from the base is not automatically resolved. Changing only the target can change the route even when the Kubernetes objects stay identical.

Digest roles

Several records can identify one configuration journey. Their hashes do not identify the same bytes, so the role must always be stated.

Do not describe these as "the same digest." A receipt binds two stages by naming both identities and comparing the exact objects between them. The Catalog records digestRole and digestRecord beside every base and object-set digest.

How this guide uses action words

The word check is broad. The guides use a more exact word when the difference matters.

How common sources answer the four questions

Flattening is evaluated at each processing boundary. An AICR Application set can be flattened while the Helm charts referenced by those Applications remain render-late. An OCI artifact can carry source material, literal configuration, or a ConfigHub release; its media type and source record must say which role it has.

The Catalog currently includes concrete records for Helm, Timoni, AICR, cub installer source OCI, Kubara, Sveltos, literal configuration OCI, and plain YAML. The generic model is ahead for a non-installer source OCI and for ConfigHub-release re-entry as a new base. The generated alignment report gives the current counts and gaps.

The same objects in familiar terms

If you think in plain Helm: the recipe is your pinned chart and values. A base variant is the output of helm template for one values choice, kept as reviewable files. A derived variant gives one environment its own recorded version of those objects and keeps its changes through upgrades.

If you think in Kustomize: a base variant plays the role of a base, and a derived variant plays the role of an overlay. The base is already rendered rather than patched at build time. The derived variant is a ConfigHub Space with revisions, gates, and an upstream link rather than a directory convention.

If you start with literal YAML or configuration OCI: the objects are already already flat. Record their source and digest, attach any required routes, then retain them as a base. Do not pretend they passed through Helm.

If you start with AICR: use snapshot and diff first when the question is about existing GPU-node state; that path needs no recipe. The result tells you what differs, not what the node should contain. Select the provider-curated leaf variant for the service, accelerator, operating system, workload intent, platform, and relevant hardware before judging the difference. Keep that recipe and its provider with the generated output, then retain the exact objects as a base variant. Record required controllers and setup as lifecycle work. Run variant-dependent resource checks only after those components have been deployed. Later environment changes are derived ConfigHub variants; they do not silently rewrite the selected AICR recipe.

If you start with Kubara or another generator: keep its native source and choices, run its declared tool, and link the resulting object digest to those inputs. That record is its recipe.

If you start with a cub installer package: pull the package by its digest, choose a preset, and run cub installer setup. It flattens that preset into object files. Load them, or the published OCI bundle, into ConfigHub as a base.

Where each thing is, today

• Helm recipes and render records live in this repo. Every chart page links to them.
• Installer packages live under packages/. Each chart version has one, and it holds every preset already flattened.
• AICR recipes remain AICR recipes. Other recipes live beside source receipts or base records, as source-and-intent records. Each uses its own format rather than a fake Helm record.
• Base variants live in packages or exact object sets. After upload, each becomes a root Space in ConfigHub.
• Derived variants, promotions, delivery, and observations live in ConfigHub. Follow variants after upload and the evidence links on each chart page.

When you browse a ConfigHub org, you see the flattened objects as Units, derived Spaces, revisions, and links from F2 through F4. The source-specific intent and processing records remain linked from the base. A package upload also has an installer-record Unit that identifies the package that produced it.