Helm Charts and OCI Artifacts

Breakwater's registry stores more than container images. You can push Helm charts, sign images and charts, and attach SBOMs and attestations, all with the standard tools. Your customers' licenses control access to all of it.

All examples use registry.breakwaterapp.com and your vendor token (vtok_...). See Auth Tokens for creating one.

Tested Clients

cosign v3 changed its default signing mode, and we haven't tested that default yet. If you use cosign v3, verify a signed test image as a customer would before relying on it.

Pushing Helm Charts

Charts live in a repository like images do. Helm names the repository after the chart, so pushing webapp-1.2.0.tgz to oci://registry.breakwaterapp.com/acme stores it in acme/webapp.

echo "<secret>" | helm registry login registry.breakwaterapp.com -u <username> --password-stdin
helm package ./webapp --version 1.2.0
helm push webapp-1.2.0.tgz oci://registry.breakwaterapp.com/acme

Create the repository and attach it to a product like any other (see Repositories and Products). A chart's version is its tag, so license tag patterns such as >=1.0, <2.0 apply to chart versions.

Signing with cosign

Sign by digest, not by tag:

docker login registry.breakwaterapp.com -u <username>
cosign sign --key cosign.key registry.breakwaterapp.com/acme/webapp@sha256:<digest>

This is cosign's classic mode: the signature is stored under a sha256-<digest>.sig tag. Customers verify it with a plain cosign verify.

For OCI 1.1 mode, the signature is stored as a referrer of the image instead:

COSIGN_EXPERIMENTAL=1 cosign sign --key cosign.key \
  --registry-referrers-mode=oci-1-1 \
  registry.breakwaterapp.com/acme/webapp@sha256:<digest>

Customers then verify with cosign verify --experimental-oci11. Attestations (cosign attest) are tested in classic mode; OCI 1.1 mode attestations haven't been tested.

COSIGN_REPOSITORY (storing signatures in a separate repository) is not supported. Signatures must live in the same repository as the image.

Signing with Notation

Log in and configure a signing key first (notation login registry.breakwaterapp.com -u <username>, then notation key add or notation cert generate-test --default <name> for testing):

notation sign registry.breakwaterapp.com/acme/webapp@sha256:<digest>

Customers verify with notation verify and a trust policy that trusts your certificate.

Attaching SBOMs

Attach an SBOM to an image with ORAS:

oras attach --artifact-type application/spdx+json \
  registry.breakwaterapp.com/acme/webapp@sha256:<digest> \
  sbom.spdx.json:application/spdx+json

Docker BuildKit builds with --sbom=true embed the SBOM in the image index instead; no extra step is needed.

How License Patterns Apply

Signatures, SBOMs, and attestations follow the image or chart they're attached to. A customer who can pull v1.2 can fetch and verify its signature and SBOM; a customer who can't pull v2.0 can't see anything attached to it. You can't sell a signature or SBOM separately from the image it describes. See Tag Patterns for how chart versions with build metadata are matched.

The sha256-... Tags in Your Tag List

After signing or attaching, you'll see tags named sha256-<hex> in your repository. These are fallback indexes that Breakwater maintains so signatures and SBOMs survive registry cleanup. Docker BuildKit --sbom builds add one per build, and Notation may rewrite them too (harmless). Don't delete them by hand: deleting one makes its signatures and SBOMs eligible for cleanup.

Customers don't see these tags in their tag lists unless their license covers the image they belong to.

Storage

Signatures and SBOMs attached to an image stay stored as long as their sha256-... tags exist, even after the image itself is untagged and garbage-collected. They count toward your storage usage until the tag is removed.

Pull History

Attached artifacts are not counted as pulls. See Pull History.