Extension of Read Only Support for Index Based OCI Artifacts in OCM CLI

[jakobmoellerdev]

Objective

Enable the legacy ocm CLI to discover and read OCM component versions stored as OCI Image Indexes instead of top-level manifests, preserving compatibility with new repository formats introduced in the “Future Format Considerations” proposal.

Scope

Add read-only support for index-based component versions to the api/ocm/extensions/repositories/genericocireg package and associated CLI commands (ocm get componentversion, ocm download resource, etc.).
Writing (publishing) to the index-based format is out of scope.

Deliverables

1. Index Detection and Resolution

   • Modify genericocireg.RepositoryAccess to:

     • Detect when the top-level descriptor is an application/vnd.oci.image.index.v1+json.
     • Iterate over index manifests to locate the manifest matching the component version tag or matching annotations (org.opencontainers.image.ref.name).
     • Use that manifest as the component descriptor source.

   • Fallback: if no match, continue using the existing manifest-based logic.

2. Artifact Reading Compatibility

   • Extend AccessSpec handling to support localBlob entries where mediaType ∈ {application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json}.
   • On read, synthesize an ArtifactSet from native OCI manifests to maintain backward compatibility with existing consumers (as in PR #1646).
   • Ensure that globalAccess (when present) is exposed transparently without breaking current resolution logic.

3. CLI Integration

   • Update read commands to use the new resolution path:

     • ocm get componentversion
     • ocm get resource
     • ocm download resource

   • Ensure transparent behavior: user input and flags remain unchanged.

4. Tests

   • Add integration tests for:

     • Reading a manifest-based component version (baseline).
     • Reading an index-based component version referencing a descriptor manifest.
     • Reading resources with localBlob referencing a native OCI Artifact.

   • Validate equivalence of ocm get output and artifact set synthesis results.

5. Documentation

   • Update CLI help text and docs/extension-oci.md:

     • Describe support for index-based discovery.
     • Clarify read-only limitation.

   • Add a migration note for future write support.

Acceptance Criteria

• ocm can list and retrieve component versions from OCI repositories where the top-level object is an Image Index.
• Resources with localBlob and OCI media types can be read and exported correctly.
• Existing manifest-based component versions remain unaffected.
• All new code paths are covered by unit/integration tests.
• Documentation updated and validated.

---

Implementation References

• api/ocm/extensions/repositories/genericocireg
• Proposed PR #1646 for initial prototype logic
• OCI Image Index Specification