1. See the model
A component is the software being shipped. A variant is one named configuration of that component.
Component: payments-api
Variants:
payments-api/base
payments-api/dev
payments-api/staging
payments-api/prod-us
payments-api/prod-eu| Term | Meaning |
|---|---|
| Component | The thing you care about: Redis, ingress-nginx, payments-api, or a platform slice. |
| Variant | One named configuration of that component: base, dev, staging, prod-us, prod-eu, or customer-a. |
| Base variant | A configuration rendered from Helm. Use it when values, chart version, CRDs, storage, HA mode, or Secret strategy change the Kubernetes objects. |
| Derived variant | A ConfigHub configuration made from an existing base. Use it for environment, region, target, labels, approvals, and scoped post-render changes. |
| Promotion | A controlled way to carry a reviewed change from one variant to another, with a preview before anything is applied. |
The team can then answer four questions. Which configuration are we using, where did it come from, what changed, and is it safe to promote?
Three variant layers
The word variant can describe a choice at three different stages. Keep the layers separate.
| Layer | What it is | Example |
|---|---|---|
| Source variant | A provider-curated choice before materialization. Its provider records which target and use case it is for. | A Catalog Helm preset with recorded values, or an AICR leaf selected by service, accelerator, and platform. |
| Retained base variant | The exact objects produced from one source variant, with their digest, source link, and evidence. | One rendered Helm preset, or the Argo CD Applications produced from one AICR leaf. |
| Derived ConfigHub variant | A recorded change to a retained base for an environment, region, customer, or policy. | Development, staging, and production revisions linked to the same base. |
Four things called base
The word base names four different things on this site and in the CLI. Here is each one.
| Where you see it | What it means | Example |
|---|---|---|
--base flag | Picks a preset when you render or upload a package. | cub installer setup --base reuse-existing-secret |
| Base variant | The reviewed Helm render itself: the chart, values, and captured objects. | Redis default, Redis reuse-existing-secret |
| Package base | The folder inside the installer package that holds one preset's files. | packages/bitnami/redis/25.5.3/bases/default |
| Base Space | The ConfigHub Space created when you upload a base variant. It has no Target. | cub variant upload labels it Variant=base |
Two words worth defining
A recipe pins the source and the choices that produce exact objects: a Helm chart and its values, or an AICR recipe in its native format. Literal sources like OCI and plain YAML have no recipe; they are already an exact configuration.
Declared inputs are the named settings a package exposes for you to fill, such as a namespace or an existing Secret name. cub installer doc <pkg> lists them; a value outside that list is a hard error, not a silent Helm --set.
2. Decide where the change belongs
Ask whether Helm would render different Kubernetes objects. That one question decides where the change belongs.
| Action | Use it when | Examples |
|---|---|---|
| Make a base variant | The choice changes the objects Helm would create. | CRDs on or off, HA mode, generated Secret vs existing Secret, different values file. |
| Make a derived variant | The object set is already right, but it needs to live in a different place or policy context. | prod-us-east from a base, target binding, labels, approvals, observation policy. |
| Go back to the recipe | The requested change belongs before render, not after it. | New chart version, wrapper chart, customer overlay values, or a different rendered object set. |
| Settle a delivery prerequisite | Neither a base nor a variant edit, but it must be true before the OCI artifact ships. | Target facts, generated facts, capability profile, hook or CRD disposition, approval, OCI digest and signature. |
Ask three questions in order. Does the change alter what Helm renders? If not, does it only refine an already-rendered object? If neither, is it a prerequisite that must be true before the OCI artifact ships?
Changes Helm render inputs or rendered objects -> base variant.
Changes the operating context after render -> derived ConfigHub variant.
Needs a cluster or external system -> target fact, route, or setup step.Read the full routing rule for the complete decision tree and its delivery-prerequisite checklist.
Quick routing table
| User request | Route | Why |
|---|---|---|
| Use this values file | Base variant, unless it only fills an already-rendered field. | Values usually change template branches, object shape, or object count. |
| Promote a reviewed install to prod-us-east | Derived ConfigHub variant. | The install shape stays the same; only target, facts, and policy change. |
| Use an existing Secret | Base variant if it changes object shape; derived variant if the base already exposes the reference. | Secret material stays out of public proof, but object references must be explicit. |
| Change namespace, target, environment, or region labels | Derived ConfigHub variant. | These are clonable, fillable, and receipted without a Helm rerender. |
| Add a Kustomize patch that changes a Deployment field | Base variant for a broad patch; derived variant only for one narrow post-render field. | Broad patches belong in the reviewed rendered artifact. |
| Point Argo CD or Flux at the artifact | Delivery configuration, not a base or a variant. | The object set is already published; GitOps only consumes it. |
Firm answers for four fields
Some fields come up so often that they deserve a direct answer instead of another decision tree.
| Field | Firm answer |
|---|---|
| Image tag or digest | Bump it with cub installer setup --set-image NAME=REF, when the base declares an images: block. That is a declared-image override, not a new base variant or a ConfigHub edit. |
| Namespace | Set it with cub variant create --namespace on the cloned Units. That only works when the base already exposes the namespace as a fillable field; otherwise pick a base that does. |
| Replica count | A plain scale change is a derived variant or a Day-2 operation. It needs a new base variant only when it also changes topology, storage, chart branches, or lifecycle behavior. |
| StorageClass | A derived variant's target fact, when the base already exposes the field. It needs a new base variant when a different class needs a different rendered volume shape. |
What protection means
Protection is not one thing. Here are the three meanings this site uses.
| Protection | What it means |
|---|---|
| Protected local field | The environment variant owns this field. A source refresh does not overwrite it silently; overlapping changes require review. |
| Protected input | A credential or other sensitive value stays outside portable configuration. The objects contain a reference or requirement instead. |
| Prune-protected resource | The delivery path must not delete this object when it disappears from a later configuration. It does not protect individual fields. |
One worked example: ExternalDNS overlays
Changing provider, sources, registry, domainFilters, txtOwnerId, the IAM role annotation, RBAC, CRDs, or controller args and env needs a new base variant.
Changing customer, environment, region, target, approval gates, observation freshness, a required hosted zone, or a required external Secret reference belongs in a derived ConfigHub variant.
Read the full ExternalDNS example, including the checked golden files.
The OCI boundary, and changing one field without ConfigHub
Once an OCI artifact is published, treat it as the reviewed desired object set. A change that needs a different Helm render goes back to the cub installer base path and republishes. An approved post-render refinement becomes a derived ConfigHub variant, which then republishes or applies.
A third option skips ConfigHub for a one-off fix. Change one field directly on a literal configuration OCI. The command writes a new local image, records the input digest and the old and new values, and needs no ConfigHub account or cluster.
3. Follow a safe flow
A good variant flow stays plain. Choose the base, name the variants that exist in the real world, preview the change, then promote only what was reviewed.
| Step | What happens |
|---|---|
| Choose a base | Pick the closest tested configuration from the chart page. |
| Load it into ConfigHub | The rendered objects become managed config that can be named, compared, reviewed, and delivered. |
| Name the real-world variants | Create the dev, staging, prod, region, or customer versions people actually use. |
| Preview the difference | Look at the object and field changes before delivery. Small changes stay small. |
| Promote with a receipt | Move a reviewed change forward only after the preview, gates, and receipts say what will happen. |
Today you use cub installer, cub variant create, Unit diffs, and cub variant promote. The same changes remain available for review in ConfigHub.
For the exact commands with the why behind each flag, read After upload: create a variant and promote changes. It starts where a base variant's confighub.sh ends.
The whole chain, with the variants labeled
Variants appear at two levels, and they meet at upload.
chart -> base variant (chosen with --base) -> OCI package
-> upload -> base Space
-> derived variants (staging, production) -> promoteA base variant is a named way to render the chart's recipe, such as default, no-crds, or reuse-existing-secret. A derived variant is a ConfigHub Space cloned from your uploaded base for an environment; it never re-renders Helm.
The package is chosen and rendered before upload. cub installer upload stores the rendered Kubernetes objects and an untargeted installer-record Unit. The source package, chart, and templates stay in the package OCI; ConfigHub does not rerender them.
4. Run the commands
New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.
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.
cub installer setup --pull oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/bitnami-redis:25.5.3@sha256:a216ce212424e05b341ef5000f1798e6014b72b8bc3dce9f315285871037af2a --base reuse-existing-secret --work-dir ./redis-reviewed
cub installer upload --work-dir ./redis-reviewed --space helm-redis-base
cub variant create prod-us-east helm-redis-base --environment Prod --region us-east --target prod/prod-us-east
cub variant promote prod-us-east --dry-run -o mutationsYou see a base, a downstream variant, the changed paths, and a preview before promotion.
Expected output
created downstream variant
cloned Units linked to upstream Units
changed labels/target/gates only, unless an allowed mutation receipt says otherwise
promotion dry-run lists mutations before apply5. Tell what set a field
Use these steps to trace which layer actually set a field you are looking at.
- Open the base Space's
installer-recordUnit to see which package was uploaded. Catalog demo Spaces may also containreadmeand render-intent Units that explain the chart, values profile, and required setup. - Open the package's Helm render-intent record to see which Helm values and render settings produced the starting objects.
- Open the Kubernetes Unit's revision history for changes made in ConfigHub.
- Open the derived Space's upstream link to see which base it started from.
- Treat a value seen only in the live cluster as drift until the team records it as an intended revision or removes it.
Where each setting lives
There are four places to look.
| Place | What belongs there | How to see what is set now |
|---|---|---|
| Helm values | Choices that change what Helm renders: components, object count or fields, storage mode, CRDs, ingress, Secret strategy, hooks, service exposure, or topology. | Open the base variant's valuesProfile link in its HelmRenderIntent, then open the rendered YAML it produced. |
| ConfigHub changes | Exact post-render edits when the base is right but an environment, region, customer, policy, image, label, resource, or other object field must differ. | Open the Unit revision history or derived variant. The public catalog base itself has no ConfigHub edits. |
| Install work | Required Secrets, CRDs, target facts, hooks, setup jobs, certificates, cloud accounts, and other work around the objects. | Open the base variant's prerequisites and lifecycle routes. These are not hidden as values or post-render edits. |
| Live cluster | What actually ran. | Compare observations with the reviewed Units. A live-only edit is drift until it is recorded as an intended ConfigHub revision or removed. |
One field should not have two silent owners. If a new Helm render and a ConfigHub revision both change the same field, review the overlap before promotion, then read the full command walkthrough.
6. Understand a chart preset
The claim
The catalog does not try to prove every possible Helm values combination. Most charts expose too many switches for that to be useful or honest.
It claims something narrower and more practical.
- Users keep their Helm charts.
- The catalog offers ready-to-use chart presets for common operating choices.
- Each chart preset records the values and render inputs that produced it.
- The rendered Kubernetes objects are captured as generated output.
- Hooks, CRDs, setup jobs, generated Secrets, cloud accounts, and target prerequisites are recorded with the chart preset.
- Tests, receipts, and chart pages say what is proven, blocked, refused, or still waiting for more work.
| Chart preset | Typical reason |
|---|---|
default | Start from the chart author's normal path. |
no-crds | The target cluster or another controller owns the CRDs. |
crds-enabled | The package owns the CRDs for this install. |
reuse-existing-secret | Keep secret material outside the chart render. |
server-only | Run one useful component instead of the whole chart stack. |
ha | Use a reviewed high-availability configuration. |
internal-service | Keep the service private to the cluster or platform. |
What a chart preset records
| Item | Why it matters |
|---|---|
| Chart source and version | The upstream input is pinned. |
| Values profile | Reviewers can see which values were used. |
| Release name and namespace | The render can be repeated. |
| Capability profile | Kubernetes API assumptions are explicit. |
| Source lock | The chart and dependencies can be traced. |
| Render intent | The compact machine-readable record of the render inputs. |
| Render variant | The captured Kubernetes objects produced by the chart preset. |
| Installer package OCI ref | The public package address users pull with cub installer setup --pull oci://.... |
| Package base | The generated package users can inspect and try. |
| Evidence lanes | The checks, receipts, scans, and live observations for the row. |
| Chart extras | Hooks, CRDs, setup jobs, generated facts, target facts, and other work outside plain YAML. |
The short model
chart version
base variant: named Helm render choice
render intent: inputs needed to repeat the render
render variant: Kubernetes objects captured from that render
managed variant: ConfigHub version made after the render| Term | Plain meaning | Example |
|---|---|---|
| Preset / base variant | A named way to render a Helm chart. Preset is the public word; base variant is the repo word. | Redis default, Redis reuse-existing-secret |
| Render intent | The inputs needed to repeat that render. | chart version, values file, namespace, release name, capabilities, source lock |
| Render variant | The captured output from that render. | Redis release-objects.yaml plus variant-revision.yaml |
| Managed variant | A ConfigHub version made after the rendered objects are uploaded. | dev, staging, prod, per-region, per-customer |
Managed variant here is the same idea as the derived variant used elsewhere on this page; the render-intent guide uses its own name for it.
7. See what is inside ConfigHub
- Unit is a versioned, diffable piece of configuration. Rendered Kubernetes objects become Units when they are uploaded.
- Space groups the Units for one managed configuration, such as a base, development environment, production region, or customer.
- Base variant is the reviewed starting configuration. For a Helm source, it matches a supported render shape such as
no-crdsorreuse-existing-secret. - Derived variant is a ConfigHub clone for a specific environment, region, customer, or target. Its changes are exact object changes; Helm is not rendered again.
A base Space has no Target. cub variant upload creates it labeled Variant=base, and it holds one Unit per rendered object until you choose to deliver it.
What the package contains
An installer package is the catalog artifact for one chart version.
- The package metadata and
installer.yaml. - The available preset chart configurations, called bases in the repo.
- The files needed to render each supported preset locally.
records/index.yaml, which lists the supporting record for every base.records/<base>/source-and-intent.yaml, which connects the source, exact objects, requirements, lifecycle work, checks, and evidence.records/<base>/helm-render-intent.yaml, which records the Helm chart, version, values, namespace, release name, capabilities, and source lock.
Files under records/ are supporting information, not Kubernetes objects; do not apply them to a cluster.
8. Open worked examples
These examples show the same rule in different chart shapes.
| Example | What it shows | Open |
|---|---|---|
| Redis | Secret strategy changes the rendered objects, so it belongs in a base variant. | Redis |
| Prometheus | A small server-only base can become environment-specific ConfigHub variants. | Prometheus |
| kube-prometheus-stack | A serious chart needs variants that carry target facts, lifecycle routes, and upgrade checks. | kube-prometheus-stack |
9. Read the details
Creating variants explains the rules. cub variant commands lists the current commands. Variant promotion receipts show the current evidence.
The configuration model and vocabulary guide defines every term on this page. After upload walks through the exact commands. Helm chart presets and values and Helm render intents cover the render-time record in full.
The ConfigHub data model covers Units, Spaces, and targets in full. Choosing base variants, derived variants, and delivery changes and the custom overlay example cover routing in more depth. Change an OCI package without ConfigHub and installer OCI packages cover the package format.
Deciding whether to flatten covers the verdict a base needs before it ships as a bundle.