Variants · Config Workshop

The Model In One Picture

A component is the thing being shipped. A variant is one named shape of that thing.

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 shape of that thing: base, dev, staging, prod-us, prod-eu, or customer-a.
Base variant	A Helm-rendered shape. Use it when values, chart version, CRDs, storage, HA mode, or Secret strategy change the Kubernetes objects.
Derived variant	A ConfigHub-managed shape 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.

This gives the team plain questions to answer: which shape are we using, where did it come from, what changed, and is it safe to promote?

The One Decision That Matters

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.

A Good Variant Flow

A good variant flow is plain: choose the base, name the real-world variants, preview the change, then promote only what was reviewed.

Step	What happens
Choose a base	Pick the closest proved install shape 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.

The command surface today is cub installer, cub variant create, Unit diffs, and cub variant promote. Product screens can make this friendlier, but the same data remains available for review.

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 Basic Flow

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.

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.

cub installer setup --pull oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/bitnami-redis:25.5.3 --base default --work-dir .tmp/redis
cub installer upload --work-dir .tmp/redis --space helm-redis-default
cub variant create prod-us-east helm-redis-default --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

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

More Detail

Creating variants explains the doctrine. cub variant command surface tracks the command vocabulary. Variant promotion receipts show the current evidence.