The configuration processing model

Start with the question

The same four questions apply to Helm, AICR, Timoni, Kubara, installer packages, 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.

Three variant layers

The word variant can describe a choice at three different stages. Keep the layers separate:

The source provider curates the first layer. NVIDIA curates the built-in AICR catalog; another catalog provider can publish and review additional overlays and leaves. ConfigHub Workshop curates its Helm presets. A custom source variant must name its provider, intended target, and supporting evidence rather than borrowing the status of a similar upstream variant.

For an imported provider catalog, the source layer also records the provider's identity, catalog version, catalog-content digest, selected source variant, selection dimensions, and provider evidence. Those fields are copied into the retained base and ConfigHub upload receipt. They are not recomputed from the output objects, and they do not change when a ConfigHub derived variant is created.

AICR also makes the four assessment questions easy to distinguish. aicr snapshot and aicr diff report what differs between observed GPU nodes without selecting a recipe or deploying a bundle. They do not say which node is correct. To make that decision, compare each node with the source variant intended for its hardware and job. A node without Mellanox networking may correctly omit iommu=pt and nvidia_peermem; a provider-curated RDMA variant may require them. A recipe-dependent expected-resources check can run only after the declared components have been deployed. The same rule applies elsewhere: a Helm render is not destination acceptance, an OCI publication is not controller reconciliation, and an Argo CD sync is not proof that an application request succeeded.

The generated cross-format assessment cases test these boundaries, and every generated Catalog base records all four answers in spec.assessment.

The processing 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 processor 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 materialization 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 processor and not the deployment proof. We use three different OCI roles:

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
  -> materialize 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, Timoni, AICR, Kubara, OCI, and YAML use the same decisions. They do not use the same processor. Helm renders, Timoni builds, 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

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

Source-specific words

Recipe is not the general name for a configuration. Use it only when the source tool has a recipe. OCI and plain YAML use a source-and-intent record and an exact configuration revision instead.

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.

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. Timoni records the module or bundle OCI version and digest, typed schema, selected values, build receipt, and declared workflow. For AICR, it includes the native recipe, selected options, and generation receipts. Kubara records its selected source and generation inputs. Source OCI records the processor 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.

Materializing 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 materialized and 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 source variant 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 source variant.

If you start with Kubara or another generator: keep its native source and choices, run its declared processor, and link the resulting object digest to those inputs. Do not call that record a recipe unless the source tool does.

If you start with Timoni: pin the module or bundle OCI, keep its typed schema and selected values, build the exact objects, and record any ordered apply sets, waits, tests, or target lookups that must still run. The built objects are an exact configuration revision, not a Helm render variant.

Where each thing is, today

• Helm recipes and render records live in this repo. Every chart page links to them.
• The first Timoni source-and-intent record and exact object set live under examples/timoni/; the Catalog links to the retained evidence.
• AICR recipes remain AICR recipes. Other source-and-intent records live beside source receipts or base records. They use their own format rather than a fake Helm record or a generic "recipe" label.
• 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 materialized 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.