feat(hip): OCI Artifact Selection and Referrers Support

[lexfrei]

Summary

This HIP proposes three related enhancements to Helm's OCI support:

1. Artifact Selection from Image Index - Enable helm pull/install/dependency to select chart manifests from OCI Image Index by artifactType (with config.mediaType fallback)

2. Set artifactType on Push - Have helm push set the artifactType field in manifests for efficient selection

3. Referrers API Support - Add --subject flag to helm push for associating charts with container images

Motivation

Current workarounds for publishing charts and images together (tag suffixes like :v1.0.0-helm, separate paths) are unnecessary complexity. OCI 1.1 provides native artifact bundling - Helm should leverage it.

Related

• Issue: feat: Support selecting artifacts from OCI Image Index by artifactType helm#31582
• Reference Implementation: feat(registry): support selecting artifacts from OCI Image Index helm#31583
• Builds on: HIP-0006 (OCI Support)

Checklist

• HIP follows the template from HIP-0001
• HIP is in draft status
• Reference implementation exists

[TerryHowe]

I wasn't around for the helm OCI implementation, so I don't know the thinking, but I assumed application/vnd.cncf.helm.config.v1+json represented the format of the config blob. If that is the case, it is almost as if there would need to be a new type something like application/vnd.cncf.helm.manifest.v1+json

[lexfrei]

You're correct that application/vnd.cncf.helm.config.v1+json represents the config blob format. However, using the same value for artifactType is intentional per OCI spec.

The OCI Image Spec (descriptor.md) explicitly defines artifactType in Index descriptors as:

"This is the value of the config descriptor mediaType when the descriptor references an image manifest."

This design allows clients to select manifests from an Image Index without fetching them first - the artifactType in the descriptor tells you what kind of artifact it is by exposing the config.mediaType value at the Index level.

So the equality artifactType == config.mediaType is by design, not a naming collision:

• In Image Index descriptor: artifactType = identifier for selection
• In Image Manifest: config.mediaType = format of the config blob

Both happen to have the same value because OCI spec defines it that way. Creating a separate type like application/vnd.cncf.helm.manifest.v1+json would contradict the OCI artifact model and require IANA registration for no functional benefit.

Reference: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#properties

[TerryHowe]

I would think this would search for the first layer mediaType that is application/vnd.cncf.helm.chart.content.v1.tar+gzip

[lexfrei]

Layer mediaTypes are not exposed in Image Index descriptors - only these fields are available at the Index level:

• mediaType (of the manifest itself, always application/vnd.oci.image.manifest.v1+json)
• digest, size
• platform (for container images)
• artifactType (for artifacts, OCI 1.1+)
• annotations

To check layers[].mediaType, we would need to fetch every manifest in the Index first, then inspect each one. This defeats the purpose of efficient artifact selection.

The OCI artifact model specifically uses artifactType (derived from config.mediaType) because it's available at the Index level without additional round-trips.

Example Index descriptor:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:def456...",
  "size": 567,
  "artifactType": "application/vnd.cncf.helm.config.v1+json"
  // layers[] is NOT here - it's inside the manifest
}

The fallback path (checking config.mediaType when artifactType is absent) already requires fetching the manifest. Adding layer inspection would not improve selection accuracy but would add complexity.

Reference: https://github.com/opencontainers/image-spec/blob/main/image-index.md#image-index-property-descriptions

[sabre1041]

There are a number of concerns related to this proposal, both in complexity as well as desire as a feature within Helm. Support for this feature would not only impact all Helm users given there may need to be additional logic implemented to traverse OCI manifests which could slow down the performance of Helm, but require the use of multiple tools outside the helm ecosystem just to implement it.

In addition, since Helm, by nature uses templating languages and parameters, the Image that is actually utilized within the chart may not be the same as the image the chart is attached to. Also, many charts contain references to multiple images. What logic can be employed to suggest whether a chart should be associated to one image or another.

I am very interested in the desire for others in the community to support such a feature. Until there is a marked need, I would recommend holding off until such a time where demand does grow.

[sabre1041]

Suggested change

This proposal enables Helm to select chart manifests from OCI Image Index manifests and adds support for the OCI Referrers API. Currently, `helm pull` fails when encountering an OCI Image Index containing multiple artifacts. This HIP introduces artifact selection logic based on the `artifactType` field (with fallback to `config.mediaType`), sets `artifactType` during `helm push`, and optionally allows charts to be associated with container images via the `subject` field and Referrers API.

This proposal enables Helm to select chart manifests from OCI Image Index manifests and adds support for the OCI Referrers API. Currently, `helm pull` fails when encountering an OCI Image Index containing multiple artifacts. This HIP introduces artifact selection logic based on the `artifactType` field (with fallback to `config.mediaType`), sets `artifactType` during `helm push`, and optionally allows charts to be associated with container images via the `subject` field and the Referrers API.

[sabre1041]

Suggested change

	These workarounds introduce unnecessary complexity in CI/CD pipelines, break atomic versioning guarantees, and require additional tooling to keep artifacts synchronized. Tools like ArtifactHub, ArgoCD, and GitOps workflows would benefit from a single source of truth for versioned artifacts.
	These workarounds introduce unnecessary complexity in CI/CD pipelines, break atomic versioning guarantees, and require additional tooling to keep artifacts synchronized. Tools like ArtifactHub, Argo CD, and GitOps workflows would benefit from a single source of truth for versioned artifacts.

[sabre1041]

This has the potential to be resource intensive iterating through all of the associated manifests associated within an index

[JulesdeCube]

It should not be an issue because manifest index are fetch ether by digest (sha256:abcdef12345678...) or by tag (that are just alias of direct manifest or manifests index)

in any case manifest index should contain artifact for the same version so:

• container image (we can consider that it don't go over 10 architectures)
• deployment artifact (docker-compose, helm, ...)
• the package application (npm, go package, dpkg, ...)

We have a maximum of 20 manifests that have a max size 4MB (defined in OCI 1.1 spec) this make the worse scenario 80MB of download. This is quite big but the worse case scenario.

Note that OCI 1.0 artifacts are usually link by tag. example for cosign:

An image with manifest sha256:abcdef12345678 will have it's sbom
at the tag sha256-abcdef12345678.sbom and it's signature at sha256-abcdef12345678.sig

[sabre1041]

What happens if theres a chart associated within the index image as well as in the referrers API? Since its found in the list of manifests within the index, is the associated artifact via the referrers ignored (ie first found wins)?

[JulesdeCube]

I don't think that we should add referrers API support.

The main use case is to link a helm chart to a container image but:

• helm chart can use multiple images and multiple tag of the same image and the OCI spec allow only one referrers, making referrers support at lease wonky
• Multiple helm chart version can use the same image (repo/tag/digest). If we use referrers the image will have references to multiple helm chart. The OCI spec don't define any order in witch the referrers API should send manifests making choosing the "right" (probably the latest) helm chart at lease slow, if not conflicting.

[sabre1041]

I agree that no changes should be made to the internal structure of the Helm chart itself (necessitating the need to register additional IANA types). This would require a HIP of its own

[sabre1041]

this manifest reference does not align with the helm push command mentioned previously

[JulesdeCube]

helm chart use semver version without any v in front of it:

Suggested change

	--manifest registry.example.com/myapp:v1.0.0-helm \
	--manifest registry.example.com/myapp:1.0.0 \

[JulesdeCube]

I have a question that this HIP don't answer:

In case an image index or an other manifest already exist for the given tag
Is helm push should:

• override a tag ?
• update image index to add it's self ?
• create new image index if config contentType isn't application/vnd.cncf.helm.config.v1+json ?

helm currently just override the tag but having a "smarter" logic don't seems to far fetch.

In case we don't want to implement this logic inside helm, helm should be able to push manifest without tag (As helm pull already work with digest)

[lexfrei]

@sabre1041 Fair concerns — and a couple come from the original framing, which I've reworked in the latest push. The "helm pull fails on an index" premise is gone: that was a regression, already fixed in v3.20.2/v4.2 (helm/helm#31776). The real gap is that selection is order-dependent and name-blind — for an index with more than one chart-shaped manifest, reversing the manifest order changes which chart you get, and the file is named from the reference rather than the selected chart, so you can end up with app-1.0.0.tgz that contains a different chart. The HIP makes selection deterministic (artifactType + name/version, error on real ambiguity); there's an offline reproduction in the Reproduction section.

On performance: selection reads artifactType off the index descriptors, so it fetches fewer manifests than today's path, which copies the whole graph and then picks by last-match-wins. Single-manifest charts — the vast majority — are untouched, and consuming is pure Helm; only assembling a multi-artifact index uses oras/crane, which is opt-in publisher-side and not something this HIP adds to Helm.

Concerns 3 and 4 are exactly why --subject is optional and takes a user-supplied digest — Helm makes no claim about which images a chart templates and doesn't auto-derive an association. The Referrers half is fully separable; the selection half stands alone and is where the value is, so it's worth judging on its own even if image-association stays out.

On demand: concrete need from a CNCF Sandbox project — Cozystack ships ~158 charts as one OCI artifact and 30+ images separately, with no per-component chart+image unit, which makes air-gapped mirroring two disjoint flows. Happy to gather more signal if that helps.

[lexfrei]

@JulesdeCube Good question, and a real gap — added a section for it (§4 "Push into an existing tag"). Short version: v1 keeps today's tag-overwrite behavior; Helm won't merge into or auto-create an index — assembling a multi-artifact index stays with external tooling (oras/crane) for now. Pushing by digest / without a tag is a clean enhancement (pull already works by digest), so I've listed it as an open issue rather than baking implicit index logic into helm push.

[lexfrei]

Since the June rework this stopped being theoretical. The selection gap this HIP describes turned out to be a live bug: on released 4.2.3, pulling from an index holding two charts can return the wrong one, same command, same digest, numbers and commands in helm/helm#32539. A fix for the selection half is up at helm/helm#32540.

Implementing it forced three corrections to the wording of section 1 here, all pushed. An explicitly declared chart artifactType now wins over a platform stamp, because the tooling that stamps a platform onto every entry is the tooling least likely to set artifactType. The config.mediaType fallback also runs on mixed indexes, not only fully legacy ones, since finding a chart is not finding the requested chart. And name and version have to be announced by one descriptor, because matching them independently can fabricate an identity no candidate has.

Two limits are now stated rather than left implicit: ambiguity is only detected among candidates that were examined, and the requested version chooses between candidates rather than validating a single one.

@sabre1041 your December points were answered in the June push and the premise you flagged is gone from the text. The CHANGES_REQUESTED is still standing, so a re-review would help.

@JulesdeCube section 4 answers the tag-overwrite part of your question. The two halves are independent, and the selection half now has running code and a demonstrated bug behind it.

Per HIP-1 the next step is a review; drafts get merged with a number and iterate from there. Anything I can do to help one happen?