Change a config safely · ConfigHub Workshop

1. 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, plan step, 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.

2. 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) -> promote

A 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.

3. 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 mutations

You 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 apply

4. 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 steps, and upgrade checks.	kube-prometheus-stack