The redis worked example · ConfigHub Workshop

Each section below is a lane that still runs. The npm scripts are live (redis:verify-proof, redis:verify-package, redis:local-e2e, redis:verify-confighub-proof, and the variant lanes), so this is a description of current behaviour rather than a record of how things once were.

Later charts are generated from declarative specs through scripts/lib/proof-kit.mjs rather than hand-written, which is why no other chart has prose at this depth. Read this to understand what the kit produces.

The proof lane

From redis-proof-spec.md.

This spec defines the first main-path Redis proof. It must be agreed before creating recipes/bitnami/redis/25.5.3/ artifacts.

The purpose is not to prove the old top-20 archive. The old payload has been removed from the active tree. This proof renders Redis with regular Helm under pinned inputs, then verifies the current cub installer package against that baseline.

Product Claim

For bitnami/redis@25.5.3, ConfigHub must prove:

correct variant
safe operation
immediate proof

The first Redis proof contains two install variants:

default
reuse-existing-secret

Later slices can add ha.

Required Files

recipes/bitnami/redis/25.5.3/
  README.md
  helm-plan.yaml
  chart-dossier.yaml
  source-lock.yaml
  dependency-lock.yaml
  control-points.yaml
  value-model.yaml
  effective-values.yaml
  effective-values-reuse-existing-secret.yaml
  recipe.yaml
  diffs/default-to-reuse-existing-secret.yaml
  publication/installer-package-receipt.yaml

  variants/
    default/variant.yaml
    reuse-existing-secret/variant.yaml

  revisions/
    default/r001/
      variant-revision.yaml
      rendered/release-objects.yaml
      rendered/object-inventory.yaml
      receipts/helm-equivalence-receipt.yaml
      receipts/render-receipt.yaml
      receipts/scan-receipt.yaml
      receipts/install-gate.yaml

    reuse-existing-secret/r001/
      variant-revision.yaml
      rendered/release-objects.yaml
      rendered/object-inventory.yaml
      receipts/helm-equivalence-receipt.yaml
      receipts/render-receipt.yaml
      receipts/scan-receipt.yaml
      receipts/install-gate.yaml

packages/bitnami/redis/25.5.3/
  installer.yaml
  README.md
  bases/default/kustomization.yaml
  bases/default/upstream.yaml
  bases/reuse-existing-secret/kustomization.yaml
  bases/reuse-existing-secret/upstream.yaml

runs/redis-confighub/latest/
  upload-oci-receipt.yaml

Minimum Readiness Card

README.md must show the happy path before the artifact ladder:

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.

Chart: bitnami/redis 25.5.3
Variants: default, reuse-existing-secret
Status: usable with controls
Helm objects: default 14; reuse-existing-secret 13
ConfigHub/cub installer objects: default 15; reuse-existing-secret 14
Explained difference: installer namespace support object
Helm match: default 14/14; reuse-existing-secret 13/13 semantic object matches
Secrets: default renders 1 Secret; reuse-existing-secret requires target Secret
Scan/gate: exact rendered object digest bound; result explicit
Installer package: deterministic cub installer package with two bases
Next action: publish via configured ConfigHub OCI, or direct apply only for local/test
Proof: equivalence, render, scan/gate, package, upload/OCI receipts
Variant diff: default -> reuse-existing-secret explains removed Secret, changed
StatefulSets, and added target fact

If scan/gate is not executed yet, the card must say not-run or blocked. If the local scan runs and finds risks, the card must say warn and explain which scopes are blocked. It must not imply a pass.

Required Invariants

Source And Dependencies

source-lock.yaml identifies:
- chart repository: bitnami
- chart name: redis
- chart version: 25.5.3
- content URL: oci://registry-1.docker.io/bitnamicharts/redis:25.5.3
- chart digest/sha matching the captured source evidence
dependency-lock.yaml records the Redis chart dependency closure, including the Bitnami common library chart version.
source-lock.yaml and dependency-lock.yaml are referenced by recipe.yaml.

Variant

variants/default/variant.yaml records:
- variant name: default
- namespace: redis
- release name: redis
- values profile reference
- capability profile: Kubernetes 1.30.0
- hook policy: no-hooks
effective-values.yaml records the exact values used for the render and their SHA256.

5b. effective-values-reuse-existing-secret.yaml records the existing-secret values and must not store auth.password.

Unknown, dead, or ignored values are represented explicitly as unknown, not-checked, or none-detected; silence is not allowed.

6b. variants/reuse-existing-secret/variant.yaml records the target Secret requirement: namespace redis, name redis-existing-secret, key redis-password.

Rendered Revision

variant-revision.yaml binds:
- recipe digest
- variant digest
- effective-values digest
- renderer/toolchain digest or version
- rendered object set digest
rendered/release-objects.yaml contains the Helm-equivalent Redis release objects for the default variant.
rendered/object-inventory.yaml contains every rendered object identity: apiVersion|kind|namespace|name.
There are exactly 14 Helm release objects for the default variant.

10b. There are exactly 13 Helm release objects for the reuse-existing-secret variant, and no rendered Secret.

There are no duplicate object identities.

Helm Equivalence

helm-equivalence-receipt.yaml proves:
- regular Helm render SHA256: 362dbc4854421a23ea48da4ee7e72dbc98422fa9affc26ac372c761d4b90e10d
- regular Helm object count: 14
- cub installer setup object count including secrets/support objects: 15
- semantic object matches: 14/14
- allowed ConfigHub/cub-only object: v1|Namespace||redis
- separated secret count: 1
Every difference between Helm and cub output is classified as:
- semantic-normalization
- installer-support-object
- secret-separated
- risk
- blocked

13b. The reuse-existing-secret equivalence receipt must prove:

regular Helm object count: 13
cub installer setup object count including support objects: 14
semantic object matches: 13/13
separated secret count: 0
target Secret requirement recorded separately from rendered output

13c. diffs/default-to-reuse-existing-secret.yaml must be recomputable from both rendered object sets. It must show:

removed object: v1|Secret|redis|redis
added objects: none
changed objects: Redis master and replica StatefulSets
added target fact: Secret redis/redis-existing-secret key redis-password

Installer Package

13d. packages/bitnami/redis/25.5.3/installer.yaml must declare a real installer Package with bases default and reuse-existing-secret. 13e. cub installer package packages/bitnami/redis/25.5.3 must produce byte-identical .tgz files across two local runs. 13f. cub installer setup --base default must render the default variant and match Helm semantically, with only the namespace support object added. 13g. cub installer setup --base reuse-existing-secret must render the existing-secret variant and match Helm semantically, with only the namespace support object added.

ConfigHub Upload And OCI

13h. cub installer upload must create one visible ConfigHub Space per current Redis variant in the configured demo org. 13i. Each variant Space must contain 14 variant-labeled Kubernetes Units plus an installer-record Unit. 13j. Rendered Secrets must not be uploaded by the default variant. 13k. The reuse-existing-secret variant must leave redis-existing-secret as an expected target fact, not as rendered or stored secret material. 13l. ConfigHub's hosted OCI endpoint must return a unit-level OCI manifest for a representative Redis Unit, with secret and bearer token omitted from the receipt.

Scan And Gate

scan-receipt.yaml is bound to the rendered object set digest.
scan-receipt.yaml must state scanner name/version/policy digest when run.
If no scanner has run, scan-receipt.yaml must say result: not-run.
install-gate.yaml must derive its decision from available receipts: allow, warn, or block.
install-gate.yaml must not allow a production gate when scan result is not-run; it may allow only local-test if explicitly marked.
When the deterministic local scan is present, scan-receipt.yaml must bind scanner name/version, policy bundle digest, finding counts, and findings to the rendered object digest.
When any high finding exists, install-gate.yaml must block production and may allow only local-test.

Proof Commands

The first implementation must add commands or scripts that prove:

npm run verify
npm run redis:compare

and a new Redis proof verifier, for example:

npm run redis:verify-proof
npm run redis:verify-package

The Redis proof verifier must fail if:

any referenced digest changes;
object count changes without receipt update;
the namespace support object is not explicitly classified;
scan/gate status is missing or falsely implies success;
any required file is absent.
the durable Redis installer package changes without receipt update;
cub installer package stops being byte-deterministic;
either package base stops matching the corresponding Helm-equivalent variant revision.

Non-Scope For First Redis Slice

The first Redis proof does not need to complete:

HA variant
upgrade/rollback simulation receipts

Those are required later, but they must not block the first Redis proof as long as their status is explicit.

The installer package lane

From redis-installer-package-spec.md.

This spec defines the next executable Redis proof slice: turn the existing Redis variant revisions into a real cub installer package, then verify that the package remains deterministic and Helm-equivalent.

This is not the old archived top-20 pathway. The package source is generated from the current Redis proof revisions:

recipes/bitnami/redis/25.5.3/revisions/*/r001/rendered/release-objects.yaml

The durable package source lives at:

packages/bitnami/redis/25.5.3/

Product Claim

For bitnami/redis@25.5.3, the current installer package must prove:

correct variants
safe operations
immediate proof

The package contains two real installer bases:

default
reuse-existing-secret

The current executable selection UX is:

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:7ad5fa6de0aa9c29df8cd26650893ebae6ad149a7c5ac33a8beedf5b02e2ac33 --base default --work-dir <work> --non-interactive --namespace redis
cub installer setup --pull oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/bitnami-redis:25.5.3@sha256:7ad5fa6de0aa9c29df8cd26650893ebae6ad149a7c5ac33a8beedf5b02e2ac33 --base reuse-existing-secret --work-dir <work> --non-interactive --namespace redis

Required Files

packages/bitnami/redis/25.5.3/
  installer.yaml
  README.md
  bases/default/kustomization.yaml
  bases/default/upstream.yaml
  bases/reuse-existing-secret/kustomization.yaml
  bases/reuse-existing-secret/upstream.yaml

recipes/bitnami/redis/25.5.3/publication/
  installer-package-receipt.yaml

Required Invariants

installer.yaml declares a real installer Package.
The package name is bitnami-redis and version is 25.5.3.
Exactly one base is default: default.
The default base points at the default Redis rendered object set.
The reuse-existing-secret base points at the existing-secret rendered object set.
cub installer package produces byte-identical .tgz files across two local runs from the same source tree.
The package receipt records every package source file and SHA256.
The package receipt records the deterministic .tgz SHA256.
cub installer setup --base default renders all 14 Helm Redis objects, plus only the installer namespace support object and one separated Secret.
cub installer setup --base reuse-existing-secret renders all 13 Helm Redis objects, plus only the installer namespace support object and no separated Secret.
Every cub installer difference from Helm is semantic-equivalent or explicitly classified as the namespace support object.
OCI publication is a real gated command, not a fake transcript. It runs only when a registry ref is supplied:

REDIS_INSTALLER_OCI_REF=oci://<registry>/<repo>:<tag> npm run redis:publish-package

Proof Commands

npm run redis:generate-package
npm run redis:verify-package
npm run redis:compare
npm run verify

The default npm run verify must include redis:verify-package.

Non-Scope For This Slice

This slice does not require a live ConfigHub OCI endpoint to be running. If a registry ref and credentials are available, npm run redis:publish-package must package, push, inspect, and write a publication receipt under runs/. Without a registry ref, publication remains unrun rather than simulated.

The local end-to-end lane

From redis-local-e2e-spec.md.

This slice proves the Redis default and reuse-existing-secret rendered objects can run in a local Kubernetes cluster.

It is intentionally local. It does not prove ConfigHub OCI publication, GitOps handoff, or production readiness.

Scope

Input:

recipes/bitnami/redis/25.5.3/revisions/default/r001/rendered/release-objects.yaml
recipes/bitnami/redis/25.5.3/revisions/reuse-existing-secret/r001/rendered/release-objects.yaml

Output:

runs/redis-local-kind/latest/observation-receipt.yaml
runs/redis-local-kind/reuse-existing-secret-latest/observation-receipt.yaml
runs/redis-local-kind/latest/kubectl-objects.txt
runs/redis-local-kind/latest/redis-pong.txt

Cluster Rule

Use a dedicated local kind cluster:

helm-expt-redis

The e2e script may create this cluster if it is missing. It must not mutate any other cluster context.

Apply Rule

The rendered Redis release objects do not include the installer Namespace support object. For local e2e only, apply:

v1|Namespace||redis

before applying release-objects.yaml.

This is the same intentional cub-only support object already classified in the Helm equivalence receipt.

Required Checks

The e2e proof must:

Verify the rendered object SHA256 before applying.
Create/use only the helm-expt-redis kind cluster.
Check that a default StorageClass exists. If it does not, the script may install the pinned local-path provisioner for this dedicated kind cluster and must record that target fact in the receipt.
Create the redis Namespace support object.
For reuse-existing-secret, create the required target Secret redis-existing-secret with key redis-password before applying the release objects, and record it as a target fact.
Apply the exact rendered release objects.
Wait for:
- statefulset/redis-master
- statefulset/redis-replicas
Wait for the four Redis PVCs to be Bound.
Run a Redis client command that returns PONG.
Write an observation receipt with:
- observer name/version
- cluster kind/name
- observed timestamp
- rendered object digest
- variant revision reference
- result
- freshness TTL
- target facts, including default StorageClass
- required Secret target fact for reuse-existing-secret
- checked resources
- bound PVC evidence
- PONG evidence digest

Gate Rule

Local e2e success may satisfy local-test.

It must not override the production block from the scan gate. Production remains blocked until high scan findings are fixed or explicitly waived.

The local scan lane

From redis-local-scan-spec.md.

This slice replaces the Redis placeholder scan with a deterministic local scan that is bound to the rendered object digest.

The goal is not to replace Trivy, Snyk, kube-linter, Kubescape, Checkov, or ConfigHub policy functions. The goal is to prove the receipt/gate model with a small scanner that always runs in this repo and catches real Redis risks.

Scope

Input:

recipes/bitnami/redis/25.5.3/revisions/default/r001/rendered/release-objects.yaml

Output:

recipes/bitnami/redis/25.5.3/revisions/default/r001/receipts/scan-receipt.yaml
recipes/bitnami/redis/25.5.3/revisions/default/r001/receipts/install-gate.yaml

Scanner Contract

The scanner name is:

helm-expt-local-rendered-object-scan

The scanner must:

Bind findings to renderedObjectSetSHA256.
Emit a stable policyBundleDigest.
Emit deterministic finding IDs, severities, object identities, and messages.
Fail verification if the scan receipt digest does not match the rendered object set.
Fail verification if the install gate allows production while any high finding exists.

Minimum Rules

V0 rules:

Rule	Severity	Purpose
`mutable-image-tag`	high	Catch unpinned or `latest` images.
`pdb-unhealthy-pod-eviction-policy`	medium	Catch PDBs missing explicit unhealthy pod eviction behavior.
`service-selector-has-workload-match`	high	Catch Services whose selector matches no workload pod template.
`workload-service-account-exists`	high	Catch workloads using a ServiceAccount absent from the rendered set.

Expected Redis Findings

For bitnami/redis@25.5.3 default, V0 is expected to produce:

high: 2
medium: 2
low: 0
info: 0
result: warn

Expected finding types:

two mutable-image-tag findings for Redis StatefulSets using registry-1.docker.io/bitnami/redis:latest
two pdb-unhealthy-pod-eviction-policy findings for Redis PDBs

Because high findings exist, the install gate must:

decision: warn
allowedScopes: [local-test]
blockedScopes: [production]

This is the right outcome: the proof is correct and useful precisely because it shows the chart is not production-clean under this policy yet.

The default variant

From redis-default-variant-spec.md.

The first Redis proof variant must be named default, not standalone.

Reason:

bitnami/redis@25.5.3 default render includes:
- redis-master StatefulSet with 1 pod
- redis-replicas StatefulSet with 3 pods

Calling this standalone is misleading. It weakens trust because the proof label would contradict the rendered objects.

Required Rename

Rename:

variants/standalone/variant.yaml
revisions/standalone/r001/

to:

variants/default/variant.yaml
revisions/default/r001/

All receipts, run evidence, README cards, verifier scripts, and e2e scripts must refer to the default variant.

Invariant

The verifier must prove:

variant metadata.name == default
variant revision path == revisions/default/r001/variant-revision.yaml
observation receipt variantRevision points at revisions/default/r001/variant-revision.yaml

No proof file should present the default Bitnami Redis render as standalone.

The variant diff

From redis-variant-diff-spec.md.

This slice makes the easy variant path visible.

Input:

default/r001 rendered object set
reuse-existing-secret/r001 rendered object set
reuse-existing-secret target fact requirement

Output:

recipes/bitnami/redis/25.5.3/diffs/default-to-reuse-existing-secret.yaml

The diff must show:

removed Helm object: v1|Secret|redis|redis
added Helm objects: none
changed Helm objects:
- apps/v1|StatefulSet|redis|redis-master
- apps/v1|StatefulSet|redis|redis-replicas
added target fact: Secret redis/redis-existing-secret key redis-password

The verifier must recompute the object-level diff from the two rendered object sets and reject the artifact if the summary lies.

The reuse-existing-secret variant

From redis-reuse-existing-secret-variant-spec.md.

This slice proves the first easy variant path after default.

The variant is named reuse-existing-secret.

Purpose:

Move Redis credential ownership out of Helm-generated Secret output and into
an explicit target secret requirement.

Helm Values

The variant must set:

auth:
  existingSecret: redis-existing-secret
  existingSecretPasswordKey: redis-password

It must not set or store auth.password.

Required Files

recipes/bitnami/redis/25.5.3/
  effective-values-reuse-existing-secret.yaml
  variants/reuse-existing-secret/variant.yaml
  revisions/reuse-existing-secret/r001/
    variant-revision.yaml
    rendered/release-objects.yaml
    rendered/object-inventory.yaml
    receipts/helm-equivalence-receipt.yaml
    receipts/render-receipt.yaml
    receipts/scan-receipt.yaml
    receipts/install-gate.yaml

Invariants

The verifier must prove:

variant metadata.name == reuse-existing-secret
rendered Helm object count == 13
rendered Secret count == 0
target secret requirement is recorded
regular Helm output and cub installer setup output are semantically equivalent
cub installer adds only the Namespace support object

The proof must make the happy path visible:

default variant: Helm renders Redis Secret
reuse-existing-secret variant: Helm does not render Redis Secret
safe operation: target must provide redis-existing-secret/redis-password