Installer Package OCI Refs

UNOFFICIAL/EXPERIMENTAL

The generated package index lists every current and retained package version. Published refs are in Google Artifact Registry with public read access. The local setup path does not require a ConfigHub account, a Google registry login, or a clone of this repo.

The user-facing command is:

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.

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/<repo>-<chart>:<version>@sha256:<manifest-digest>' \
  --base <preset> \
  --work-dir ./out \
  --non-interactive \
  --namespace <namespace>

For example:

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 ./out \
  --non-interactive \
  --namespace redis \
  --output-oci ./redis-rendered.oci

cub installer setup pulls the package into the work directory, writes the selected inputs under out/spec, and writes the rendered Kubernetes files under out/manifests. If the preset separates secret material, it also writes files under out/secrets. The optional --output-oci flag writes the exact non-secret rendered objects to a local OCI image layout or pushes them to an oci://host/repository:tag reference. The installer reads that artifact back and checks its object-set digest before returning.

Check The Package Before Rendering

Use the exact reference from the chart page or generated package index:

cub installer inspect 'oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/bitnami-redis:25.5.3@sha256:7ad5fa6de0aa9c29df8cd26650893ebae6ad149a7c5ac33a8beedf5b02e2ac33' --json

The version tag tells you which retained version you selected. The manifest digest after @ makes the reference immutable. cub installer refuses the pull if the registry cannot return that exact manifest. The inspect output also prints the manifest and layer digests recorded by the publication receipt.

This establishes which package bytes you received. Each published package also has a Sigstore signature for the exact manifest digest. The chart page provides the complete cosign verify command and links to the signature receipt.

The signature identifies the catalog publisher. It does not show that the configuration is suitable for your cluster. Use the same chart page for source, render, lifecycle, destination, and test evidence. See Verifying Catalog Package Signatures for the trust boundary and maintainer procedure.

What The Package Contains

An installer package is the catalog artifact for one chart version. It contains:

• the package metadata and installer.yaml;
• the available preset chart configurations, called bases in the repo;
• the files needed to render each supported preset locally;
• records/index.yaml, which lists the supporting record for every base;
• records/<base>/source-and-intent.yaml, which connects the selected source, exact objects, requirements, lifecycle work, checks, and evidence;
• records/<base>/helm-render-intent.yaml, which records the Helm chart, version, values, namespace, release name, capabilities, and source lock.

The files under records/ are supporting information. They are not Kubernetes objects and must not be applied to a cluster. Pull the exact package and read them locally:

cub installer pull 'oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/bitnami-redis:25.5.3@sha256:<manifest-digest>' \
  --work-dir ./redis-package

less ./redis-package/package/records/README.md

The package does not contain its own final manifest digest because that would create a circular hash. The publication receipt and package signature bind the finished package to its immutable digest after publication.

The package does not replace Helm charts. The catalog starts from ordinary Helm charts, then publishes reviewed package artifacts so users can pull the ready presets directly once they have access to the package registry.

The package should also make the install simpler. Most choices are fixed before publication: chart version, base shape, values profile, source lock, known CRD or hook decisions, and the evidence links. Only a small set of choices should be left for install time, such as namespace, target-specific facts, image overrides, or the name of an existing Secret. Those remaining choices should be documented and restricted instead of exposing the whole Helm values surface again.

This matters for fleets. A package release can be the thing a platform team signs off. ConfigHub can then record which package, preset, and allowed inputs a cluster, customer, or environment should run, and reconcile that desired record through the delivery system already in use.

Three OCI Roles

The catalog uses OCI for three different jobs:

The input and output may both be OCI without being the same artifact. The installer package can offer several presets and the files needed to render them. A rendered OCI contains one chosen result. A ConfigHub release OCI contains the later managed revision after variants, review, approval, or promotion.

To push the selected result directly:

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 ./out \
  --non-interactive \
  --namespace redis \
  --output-oci oci://REGISTRY/redis-reviewed:25.5.3

Registry write access is required for a push. A local --output-oci path needs no registry credentials. Input values and files under out/secrets are not published in the rendered OCI.

Publication Status

The generated package catalog records both the intended package ref and the publication status:

• published-receipt means a publication receipt is committed for that ref. Public catalog refs are also readable anonymously from the current Artifact Registry repository.
• assigned-ref means the catalog has assigned the package ref, but no publication receipt is committed yet.

Until a row has a publication receipt, maintainers can still use the local source package path under packages/... from a repo checkout. Users who are pulling from OCI should follow rows that have a published package, or treat an unpublished row as a preview of the intended address.

Public Pull Access

Publishing and public pull access are separate. For this catalog, both are now in place:

• every currently published package ref has a committed publication receipt;
• the Google Artifact Registry repository grants roles/artifactregistry.reader to allUsers;
• the project-level organization policy allows that public read binding for this public package project.

That means a user can run cub installer inspect or cub installer setup --pull against the public catalog refs without Google Cloud credentials. Write access is still private: maintainers need registry credentials to publish or replace packages.

The registry setting is deliberately narrow: the helm-expt Artifact Registry repository grants roles/artifactregistry.reader to allUsers. The project has a project-level organization-policy override that permits that public read binding. This does not grant anonymous write access, and it does not make other project resources public.

Anonymous read was checked with empty local auth state:

tmpd=$(mktemp -d); tmpc=$(mktemp -d)

DOCKER_CONFIG="$tmpd" CLOUDSDK_CONFIG="$tmpc" GOOGLE_APPLICATION_CREDENTIALS= \
  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 ./out \
    --non-interactive \
    --namespace redis

rm -rf "$tmpd" "$tmpc"

Where To Find The Refs

Use these generated files when you need exact refs for all chart versions:

• Installer OCI package summary
• Installer OCI package CSV
• Installer OCI package JSON

The verifier is:

npm run installer-oci:catalog:verify
npm run installer-oci:signatures:verify
npm run installer-oci:index-signature:verify

This checks that package refs, manifest and layer digests, immutable setup and inspect commands, package paths, bases, and publication statuses match the committed receipts. Its self-test also refuses invalid digests and any published setup command that falls back to a mutable tag:

npm run installer-oci:catalog:self-test
npm run installer-oci:signatures:self-test
npm run installer-oci:index-signature:self-test

The package and index consistency checks run in the normal repository gate. The dedicated signature workflow also uses pinned Cosign v3.1.3 to verify the committed Sigstore bundles cryptographically and to prove that changed payload or index bytes are refused.

Maintainers publish packages with:

npm run installer-oci:publish -- --package packages/bitnami/redis/25.5.3

or, for the full catalog:

npm run installer-oci:publish

The publish command requires registry credentials with package write permission. For GHCR, use a token with write:packages. After a successful push, the script writes a publication receipt under runs/installer-oci/...; regenerate the catalog so the row changes from assigned-ref to published-receipt.

For the full consumer pathway, see the upstream Package Consumer Guide.