Creating Custom Variants

This document explains how custom ConfigHub variants get created.

The Starting Point

First we make durable cub installer recipes and base variants.

A recipe/package base is the reviewed install shape for a component. It says:

• which chart or wrapper chart was used;
• which values were rendered;
• which Kubernetes objects were produced;
• which facts, checks, and receipts prove the base.

Examples:

redis/default
redis/reuse-existing-secret
external-dns/managed-aws

Those bases are important because they are reviewed. They are the trusted starting point for later variants.

Why We Need Custom Variants

After a base exists, teams still need real operational variants:

redis/prod-us-east
redis/prod-eu-west
external-dns/customer-acme-prod

These variants usually should not rerender Helm. They start from a reviewed ConfigHub base or from another existing ConfigHub variant, then apply the differences that are specific to an environment, region, target, or customer.

That is custom variant creation.

Simple version:

Create prod-us-east from redis/default.

Before ConfigHub creates it, the user should see:

• the reviewed base that will be copied;
• the new variant name, labels, and target;
• the environment, region, customer, or fact values being supplied;
• the Units, links, gates, and fields that will change;
• the checks that must pass;
• the receipts that will prove what happened.

Then ConfigHub creates the downstream Space, clones the Units, preserves the promotion links, applies the allowed changes, runs the checks, and records the receipts.

The rule is: preview first, check first, then create.

Creator Status

The formal thing underneath the user experience is the Variant Creator contract: machine-readable intent, allowed changes, preview, checks, gates, receipts, and UX/AX/FX equivalence.

Use these terms carefully:

The practical meaning is:

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.

Creator = product/UX concept.
Variant Creator contract = formal artifact.
cub variant create = current implementation substrate.

So user-facing docs can show a future or polished Creator flow, but should not claim that a finished GUI named Variant Creator already exists.

Recipe Base Or Custom Variant?

Use a recipe/package base when the choice changes the rendered Kubernetes objects.

Use custom variant creation when the choice customizes an already-rendered ConfigHub object set.

Examples:

• Generated Redis Secret versus existing Redis Secret changes the rendered chart shape. That belongs in a recipe/package base.
• Binding the name of an existing Secret can be a custom variant input if the reviewed base already has a field for that reference.
• ExternalDNS provider, sources, registry mode, domain filters, and TXT owner behavior usually change rendered args or env. Those belong in the installer base.
• Target, namespace, labels, approvals, gates, links, and observation policy are post-render ConfigHub concerns. Those belong in custom variant creation.

Variant Creator Contract

The simple story above needs a formal underpinning so every creation path uses the same rules, but that underpinning should not become a new variant backend.

Working name:

Variant Creator contract

The earlier notes used the name VariantCreationPlan. Read that as the old working name for this contract, not as a separate engine we tried to build. In this repo it was documentation only: no script, verifier, CLI, or backend code consumes it.

The contract is product/catalog metadata over existing ConfigHub primitives:

cub variant create
cloned Spaces and Units
upstream Unit links
labels, annotations, targets, gates, and permissions
placeholders
TransformPaths and NeedsProvides links
PostClone triggers
functions and checks
target facts
MutationSources and receipts

A blueprint is a named creation pattern inside the contract, such as environment-clone, promote-to-production, or customer-production-overlay.

The first concrete example is redis-variant-creation-plan.yaml.

It answers:

• which reviewed bases or existing variants can be used as the source;
• which blueprints can be used;
• which values, target facts, links, or placeholders must be filled;
• which paths, labels, annotations, targets, gates, links, or functions may change;
• what the preview must show before creation;
• which checks must pass;
• which receipts must be written.

The storage home can be decided later. It might live as metadata on the base Space, an AppConfig/Text Unit in the base Space, catalog metadata, or eventually a typed ConfigHub object.

The best near-term interpretation is:

Variant Creator contract = catalog/base-Space guidance that tells cub variant
create, PostClone triggers, TransformPaths, functions, gates, and the UX which
existing ConfigHub primitives to use.

It is not itself a TransformPaths link, a trigger, a function, or a new variant engine. It is the shared contract that selects and wires those pieces together.

The important point is that the contract gives ConfigHub one shared way to drive a human wizard, an agent task, and a fleet function while still composing existing ConfigHub primitives.

UX, AX, FX, And Proof Placement

The human product flow should stay simple:

choose the reviewed source
choose the destination variant
fill the values that matter to the user
review the visible changes
see whether creation is ready
create the variant

The same operation still needs machine-readable proof:

route check
rendered object digest check
Unit count check
upstream link check
target-fact check
scan and gate disposition
clone, mutation, check, approval, apply, and observation receipts

Those details should be available in expandable UI, audit views, receipts, CI, and agent output. They should not be the first-screen vocabulary for a user creating their first variant.

AX and FX can ask for the proof targets directly because agents and fleet functions need structured contracts. The product rule is still one model with three surfaces: a simple human flow, an agent task, and a fleet function.

How This Maps To ConfigHub Primitives

CLI+UI, AX, And FX

Custom variants should be creatable in three ways:

• CLI+UI: the user-led product experience;
• AX: an agent performs the same creation task;
• FX: a function creates one or many variants from rows of input.

These should not produce three different experiences. They should all get the user to the same UX: the same source, the same requested variant, the same preview, the same checks, the same created ConfigHub state, and the same receipts.

CLI+UI shape:

Create custom variant
From: redis/default
Name: prod-us-east
Target: redis-targets/prod-us-east
Values: namespace, Redis secret reference
Review: target, namespace, Secret reference, and production policy
Status: ready to create
Create

The review can include a details panel with Unit counts, changed paths, link changes, checks, and receipt links. The default view should explain the operation in product terms.

AX shape:

task: create_variant
from: redis/default
plan: environment-clone
name: prod-us-east
target: redis-targets/prod-us-east
values:
  namespace: redis-prod
  redisSecretRef: redis-existing-secret
requiredChecks:
  - no-unresolved-placeholders
  - target-facts-satisfied
  - unit-diff-reviewed
expectedReceipts:
  - clone
  - mutations
  - checks

FX shape:

function: create_variant
from: redis/default
plan: environment-clone
rows:
  - name: prod-us-east
    target: redis-targets/prod-us-east
    namespace: redis-prod-use1
    redisSecretRef: redis-existing-secret
  - name: prod-eu-west
    target: redis-targets/prod-eu-west
    namespace: redis-prod-euw1
    redisSecretRef: redis-existing-secret

The field names can change. The product rule should not: one creation model, three ways to invoke it.

Two Important Examples

There are two important examples.

1. Promotion

Variant Promotion Worked Example shows redis/default becoming a downstream prod-us-east ConfigHub variant.

This is the straightforward promotion case:

reviewed recipe/package base
  -> custom ConfigHub variant
  -> future base changes can be reviewed and promoted downstream

The custom variant does not rerender Redis. It clones the reviewed ConfigHub Units, gives the downstream Space its production identity, binds the target and environment-specific values, runs checks, and leaves receipts.

2. Kubara Customer Overlays

Kubara Customized Overlay Analysis shows how a managed app becomes a reviewed base before custom variants are created.

For Kubara-style managed apps, the reviewed base may be:

managed wrapper chart
  + platform values
  + customer overlay values
  + dependency closure
  + render context

That example tests a harder boundary. Some customer choices change rendered Kubernetes objects, so they belong in the maintained cub installer recipe/package. Other customer choices only select target, region, labels, fact bindings, gates, links, or already-rendered field values, so they belong in custom ConfigHub variants.

Together, the two examples test the same rule from different directions:

Use installer bases for render-time choices.
Use custom variants for post-render ConfigHub variation.