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.
1. Tell the OCI shapes apart, and match each to its consumer
OCI is at both ends. A bundle in the Catalog is an OCI artifact that is ready to be uploaded and used. A release from ConfigHub is an OCI artifact that is ready to run.
This page keeps the word bundle for the first of those. A bundle holds the flattened objects of one entry and their record. It carries a plan where the entry needs one. The model page defines it.
OCI is the common transport in this catalog, not a universal execution model. A package can carry exact objects plus a plan and source records. Read the full passage.
The consumer still decides what runs. cub installer renders the objects, and ConfigHub stores and changes the records. Argo CD or Flux reconciles them, a cloud controller provisions infrastructure, and a model server answers inference requests.
The word OCI covers several related but different artifacts here, and five source documents name the roles differently. This catalog's own doctrine names four: a source or installer package, a literal configuration bundle, a portable deployment bundle, and a ConfigHub release bundle. The table below calls the last three an upload layout, rendered objects and a release. Read that four-row table.
An upload layout and rendered objects can carry the same Kubernetes objects in different OCI layer layouts. The consumer decides which layout it needs, so check the package you produce against the consumer that will use it.
The installer-package guide names three roles instead: an installer package OCI, a rendered OCI, and a ConfigHub release OCI. Read that table. An installer package can offer several presets, and a rendered OCI holds one chosen result. A ConfigHub release OCI holds the later revision after review, approval, or promotion.
The processing-model guide calls OCI the transport, not the processor and not the deployment proof. It names three roles again: a source package OCI, a literal configuration OCI, and a ConfigHub release OCI. Read that table. These artifacts can hold related objects but carry different manifests and digests, so a receipt names both identities rather than treating unlike digests as one.
The deployment guide narrows to the two artifacts a user meets directly: an installer-package OCI and a ConfigHub Space release OCI. Read that table. An installer package can offer several preset configurations, and a Space release holds one selected and reviewed configuration. An installer-package URL is never a Space-release URL.
A separate roadmap note adds a fifth table. It names a fourth role most others skip: a runtime image OCI, the application, model server, agent runtime, or sandbox image Kubernetes actually runs. Read that table. That image has a different job from every configuration shape below it. The site must not use the word OCI as if every artifact had the same job.
Nine shapes, side by side
Every claim in this table cites its own source doc. Where a fact is missing, the cell says so instead of guessing.
| Shape | Media type | Layout | Producer | Consumer | Registry | Signed by | Carries a plan |
|---|---|---|---|---|---|---|---|
| Installer / source package OCI | Not named; a multi-file OCI image (installer.yaml, presets, records/) | installer.yaml plus preset configs plus records/ (source-and-intent and Helm-render-intent files) | The catalog publisher, with npm run installer-oci:publish | cub installer setup --pull, cub installer inspect | Google Artifact Registry, public read | Yes: a dedicated Google service account, Sigstore keyless | Yes, as the files under its prerequisites/ directory |
| Upload layout (literal configuration) | Not named | Kubernetes YAML in a tar layer, or in one layer for each file; a different layout from the row below even for the same objects | Not named as one command in these docs | cub variant upload oci://… | Not named | Not stated | Only when the artifact holds plan documents |
| Rendered objects (rendered OCI) | Not named; described as “a standard OCI content layer” | One selected preset's exact non-secret Kubernetes objects | cub installer setup --output-oci | Argo CD, Flux, an anonymous pull, or cub variant upload | A local OCI layout, or an oci://host/repo:tag reference | Not stated | No |
| Release (Space release OCI) | Not named | The exact reviewed Units from one ConfigHub Space | cub release publish <space> | Argo CD, Flux, or another ConfigHub delivery path | oci://oci.hub.confighub.com:443/space/<space> | Not stated | Not stated |
| Bundle (certified bundle) | application/vnd.confighub.config.bundle.v1 | One gzipped, byte-reproducible tar layer: sorted names, zeroed owners, epoch timestamps | cub config check --out oci://…, cub app check --out oci://… | cub config verify, then cub variant upload oci://… | Today: provider-specific paths on two registries. Proposed: a stable oci://catalog.confighub.com/… endpoint | Open item: keyless cosign for a user's own output, the catalog's own key for its own | Where the entry needs one |
| Bundle receipt (referrer record) | application/vnd.confighub.record.v1+json | One JSON record, attached to the bundle's manifest digest as a referrer | The same command that pushes the bundle it describes | cub config verify, oras discover | The same registry as the bundle it describes | Not stated separately from the bundle | No. It is a record. |
| Stack index | An OCI image index; no dedicated type named | Entries are component bundles by digest; the manifest and check verdict attach to the index digest | cub stack publish <name> --out oci://… | Today: the Catalog itself. Planned: cub stack sandbox oci://…index@sha256:… | Wherever --out oci://… points | Not stated; the verdict is a record, not a signature | Not stated |
| Stack release (flattened stack image) | Not named | The whole stack rendered into one manifest, not an index | cub stack sandbox <name> --out oci://… | A reconciler; it pulls one manifest | Wherever --out oci://… points | Not stated | Not stated |
| Runtime image OCI | Not named | Not detailed in these docs | Not named; built outside this catalog | Kubernetes, as the workload it runs | Not discussed in these docs | Not addressed by this catalog's signing scheme | No |
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.
Which consumer needs which layout
cub installer setup --pullandcub installer inspectneed the installer-package layout, row one above.cub variant upload oci://…needs the literal-configuration-bundle layout, row two, or a certified bundle, row five. Every resource becomes its own Unit, except Secrets, which the upload skips.- Argo CD, Flux, an anonymous pull, or
orasandkubectlneed the portable-deployment-bundle layout, row three. cub config verifyneeds the certified-bundle layout with its receipt attached as a referrer, rows five and six.- A reconciler that pulls one manifest for a whole stack needs the flattened stack-release layout, row eight.
- The Catalog itself, or a future index-aware puller, needs the stack-index layout, row seven.
2. See how a certified bundle and a stack become one artifact
One shape carries this catalog's own certified bundles: an OCI artifact of type application/vnd.confighub.config.bundle.v1, whose layer is a reproducible tar.gz of rendered configuration. Its receipt attaches to the same digest as a referrer, of type application/vnd.confighub.record.v1+json. Read the design center's definition.
Verified means the bundle was pulled by digest, every listed file was re-hashed against the receipt, and the layer bytes matched. cub config verify does those three checks today. A signature is checked only where one is present, and signing itself remains an open item, covered below.
Three forms share one digest rule. A variant is a single image: one component at one recorded set of inputs. A stack is an index of images, with its manifest and check verdict attached to the index digest. A release is a flattened image, because a reconciler pulls one manifest, not an index. Read the full definitions.
One receipt links the three forms. The identity of a certified bundle is always its OCI manifest digest, and the object-set hash lives inside the receipt. It never substitutes for the manifest digest.
The stack manifest itself is a source file, and its published form is the index in row seven above. cub stack publish produces that index, and cub stack sandbox --out oci://… produces the flattened release in row eight. Read the full section. The Catalog holds indexes, not manifests, and a receipt links the index to its release.
Every digest, and what it pins
Five records can identify one configuration journey, and their hashes never identify the same bytes. Read the source table.
| Identity | What it pins | Example |
|---|---|---|
| Base-revision digest | The complete base record, including source inputs and processing context | A Helm variant-revision digest, or an AICR platform-index digest |
| Exact-object digest | The accepted Kubernetes object set, or the inventory that pins every object file | renderedObjectSetSHA256 for a Helm revision |
| OCI manifest digest | One transported artifact manifest; a source package OCI and a literal configuration OCI carry different roles and digests | The digest a registry returns |
| ConfigHub data hash | One retained Unit revision | The hash reported for a ConfigHub Unit |
| Release OCI digest | The immutable artifact published from one reviewed ConfigHub Space revision | The digest Argo CD or Flux consumes |
A receipt binds two of these identities by naming both and comparing the exact objects between them. It never calls unlike digests the same digest.
Where the receipt lives is still an open question
Two planning documents disagree about where a certified bundle's receipt belongs. The design center attaches it to the same digest as a referrer, discoverable through the OCI registry's own referrers API. Read that definition.
The certified-bundle spec instead says the catalog emits a receipt beside each published bundle, a separate committed record rather than an OCI-native referrer. Read that passage. This page records the disagreement rather than resolving it.
3. See what a signature actually proves
Every currently published installer package has a committed publication receipt, and the Google Artifact Registry repository grants roles/artifactregistry.reader to allUsers. Read the full access note.
A user can run cub installer inspect or cub installer setup --pull against the public catalog refs with no Google Cloud credentials. Write access stays private, so maintainers still need registry credentials to publish or replace a package.
A successful cosign verify proves four things. The named service account signed the exact OCI manifest digest. The signed payload records the expected package path and package SHA-256. The registry served the signature with no credentials when the receipt was written, and Sigstore recorded the signing event. Read the full list.
It does not show that a selected preset is suitable for a particular cluster. It also does not prove that a hook, CRD, Secret, or later rollout will succeed.
What is signed today
| Shape | Signed today? | Mechanism |
|---|---|---|
| Installer / source package OCI | Yes | Sigstore keyless cosign, a dedicated Google service account identity |
| Upload layout | Not stated | Not discussed in these docs |
| Rendered objects | Not stated | Not discussed in these docs |
| Release | Not stated | Not discussed in these docs |
| Bundle | Open item | Keyless cosign for a user's own output, the catalog's own key for its own; the mechanism already runs in CI for other artifacts |
| Bundle receipt (referrer record) | Not stated separately | Not discussed in these docs |
| Stack index | Not stated | The check verdict is a record, not a signature |
| Stack release | Not stated | Not discussed in these docs |
| Runtime image OCI | Not addressed here | Outside this catalog's signing scheme |
Check a claim yourself says which verify command fits each shape.
4. See how other tools already produce these shapes
The stack manifest is not the first tool to compose OCI-referenced configuration. Three tools already overlap with it directly. Read the full comparison.
Timoni
Timoni already ships OCI-referenced module bundles, a format this catalog already lists as one of its entries. The stack-manifest design calls it a natural producer for the manifest itself.
AICR
AICR is a manifest emitter rather than a competing format. Its profile-owned values and its refuse-on-conflict rule map onto the stack manifest's bindings and verdict. Its platformDigest is the same primitive as the composition digest.
Kubara
Kubara's own adoption step already compiles one OCI package per component and one digest-bound platform index. Destination bindings and secrets stay out of the portable packages. That index is a producer-private stack manifest. Its component packages match the components list here, and its platformDigest is the same primitive as the composition digest.
Stacks and fleets keeps the two stack OCI forms and the check that reads them before either is built. Run it with Flux, Argo CD, or kubectl carries the Argo CD 3.x and 2.x specifics and the exact manifests each controller needs.