Choosing Presets, Derived Variants, And Delivery Changes

UNOFFICIAL/EXPERIMENTAL

This document explains where a Helm change belongs before delivery.

The public word is preset. The repo word is base variant. Use a preset when the change asks Helm to render a different shape. Use a derived ConfigHub variant when the rendered shape is already right and you are changing the operating context after render.

For the short guide to creating variants through human, AI assistant, and bulk flows, see Creating Variants.

Three Decisions

Before delivery, ask three questions in order.

1. Does This Change Helm Render Inputs Or Object Shape?

If yes, use a catalog preset / cub installer base variant.

Presets are render-time install shapes. They are created from Helm chart inputs, values, overlays, capability profiles, target facts, generated facts, and lifecycle policy. They produce a new reviewed rendered object set.

The catalog does not claim to support every values combination. It supports useful chart-specific presets and records the values, generated output, and evidence for each one.

Use a preset for:

• enabling or disabling chart components;
• changing storage, ingress, TLS, RBAC, CRDs, webhooks, args, env, object count, topology, or lifecycle behavior;
• changing replica or HA settings when they alter topology, chart branches, services, PDBs, storage, or lifecycle behavior;
• choosing generated Secret versus existing Secret mode when the Helm render or object shape differs;
• applying a Helm values file or --set input that changes chart branches, object shape, object count, or lifecycle behavior;
• populating raw manifest, tpl, sidecar, config-block, or application config extension slots such as extraDeploy, serverBlock, or extra scrape config;
• applying a Kustomize overlay or post-renderer that materially changes the install shape;
• selecting a wrapper chart, umbrella chart, platform values, or customer overlay values that change the Helm-rendered object set;
• changing hook or lifecycle policy that affects what must happen at install, upgrade, test, or delete time.

The output is a reviewed rendered revision with equivalence checks, scans, gates, and receipts.

Example:

prometheus/default
prometheus/server-only-ephemeral

server-only-ephemeral disables bundled components and persistence. Those objects disappear from the render, so it is a preset/base variant.

2. Does This Refine A Reviewed Object Set After Render?

If yes, use a derived ConfigHub variant.

Derived variants start from an uploaded reviewed base or another derived variant. They clone ConfigHub Spaces and Units, preserve upstream links, and apply allowed post-render changes without running Helm again. They can cover more than metadata when the source base and Creator contract explicitly allow the changed paths, facts, functions, and checks.

Use a derived variant for:

• environment, region, customer, or target assignment;
• replica count when it is an approved edit to an already-rendered workload field;
• namespace or release-name fields when the base exposes them for post-render fill;
• labels and annotations used by ConfigHub views, filters, ownership, or promotion;
• approval gates, delete/destroy gates, and operation policy;
• observation policy and freshness expectations;
• links between Units and external inputs;
• target facts such as existing Secret names, hosted zones, endpoint IDs, account IDs, StorageClasses, or IngressClasses;
• placeholder, parameter Unit, or TransformPaths fills where the rendered fields already exist;
• narrow ConfigHub function changes that are approved for this component and do not change the install shape unexpectedly;
• MutationSources and receipts that explain every post-render field change.

The output is a downstream ConfigHub Space and Unit set that can be reviewed, published, approved, applied, and observed.

Example:

prometheus/server-only-ephemeral
-> prometheus/prod-us-east

The production variant can change target, labels, gates, fact bindings, approved field fills, checks, and observation policy. It keeps the same Prometheus install shape and does not rerender Helm.

3. What Must Be Settled Before OCI Delivery?

OCI delivery should publish the reviewed desired state that Kubernetes or GitOps will consume. Helm-rendered bases and derived post-render refinements must both be captured before the artifact is published or applied.

Before OCI delivery, settle:

• selected preset/base variant;
• any derived ConfigHub variant that changes target, fields, facts, labels, gates, links, checks, or delivery policy for this deployment;
• effective values and overlay digests;
• target fact bindings such as existing Secret name, StorageClass, IngressClass, CRD/API availability, or namespace expectation;
• generated fact bindings for generated passwords, certificates, random values, or time-derived values;
• capability profile such as Kubernetes version and API set;
• hook, CRD, webhook, and lifecycle disposition;
• rendered-object scans and gates;
• approval state;
• OCI artifact identity, digest, signature, and access method;
• GitOps controller configuration that points at the OCI artifact.

Some prerequisites may live outside the OCI artifact but still need explicit evidence before delivery. Examples include an existing Secret, a required CRD owner, a StorageClass, an IngressClass, a GitOps pull Secret, or an Argo/Flux controller in the target cluster.

Quick Routing Table

The OCI Boundary

After OCI publication, the artifact should be treated as the reviewed desired object set. Do not rely on an untracked GitOps patch, manual cluster edit, or post-render script to make it correct after publication.

If a change requires Helm to render different objects, send it back to the cub installer preset/base path and publish a new artifact. If a change is an approved post-render refinement of the reviewed object set, make it a derived ConfigHub variant and publish or apply that reviewed variant.

User-Facing Wording

The product should explain the route plainly:

This changes Helm render inputs or object shape, so it needs a new chart preset.

or:

This keeps the same install shape and applies approved post-render fields,
facts, links, targets, gates, or checks, so it can be a derived ConfigHub
variant.

or:

This is a delivery prerequisite. It must be satisfied or recorded before the
OCI artifact is used by Kubernetes.