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