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 the common transport in this catalog, not a universal execution model. A package can carry exact objects plus routes and source records. Read the full passage.
The consumer still decides what runs. cub installer renders the objects, 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. Read that four-row table.
The literal upload bundle and the portable deployment bundle 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, a rendered OCI holds one chosen result, and 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, a Space release holds one selected and reviewed configuration, and 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, and 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 |
|---|---|---|---|---|---|---|
| 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 |
| Literal configuration bundle (upload layout) | Not named | Kubernetes YAML laid out for per-file ingestion; 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 |
| Portable deployment bundle (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 |
| ConfigHub release bundle (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 |
| 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 --granularity per-file | 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 |
| 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 |
| Stack index | An OCI image index; no dedicated type named | Entries are component bundles by digest; the manifest and certify 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 |
| 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 |
| 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 |
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 ingested with--granularity per-file, row five.- 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 certify 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, and check one yourself
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 |
| Literal configuration bundle | Not stated | Not discussed in these docs |
| Portable deployment bundle | Not stated | Not discussed in these docs |
| ConfigHub release bundle | Not stated | Not discussed in these docs |
| Certified 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 certify 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 |
Choose the right verify command
Four commands check different OCI shapes, and none of them substitutes for another.
- Have an installer-package ref? Run
cub installer inspect <ref> --jsonfirst, to confirm the manifest and layer digests the publication receipt recorded. - Then run
cosign verifywith the identity, issuer, and annotations from the chart page, to confirm the named service account signed that exact digest. - Have a certified-bundle ref? Run
cub config verify oci://…@sha256:…. It pulls the bundle, finds its receipt, and re-hashes every listed file; it checks a signature only where one is attached. - Have the downloadable package index? Run
cosign verify-blob --bundle packages.sigstore.json …against the committed index signature.
These four commands cover the shapes listed above them. A ConfigHub release bundle, a stack index, a stack release, and a runtime image have no matching command here, because these docs describe no signing for those shapes.
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, and 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, with destination bindings and secrets excluded from 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 certify step that judges 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.