ORAS migrating to OCI Reference types

Status: Work-in-progress

Version: draft

Overview

The two PRs of working group proposal for reference types were merged recently and will be released in Image-spec v1.1 and distribution-spec v1.1.0. See below two PRs for reference types:

NOTES:
distribution-spec v1.1.0-rc.1 was released, see v1.1.0-rc1
image-spec v1.1.0-rc.2 was released, see v1.1.0-rc.2

This document describes the changes, manifest, and fallback use cases for ORAS-go library and ORAS CLI when migrating to OCI reference types.

NOTES:
EDIT (SteveLasker): Per the Distribution Spec: Enabling the Referrers API
3. After the referrers API is enabled, Registries MUST include all newly pushed image and artifact manifests with a valid refers field in the referrers API response.
This means a registry that supports the _referrers api MUST support the OCI Artifact manifest
Registries that support the referrer API also support OCI artifact manifest. Registries that support OCI artifact manifest may not support referrer API.

Solution and Plan

ORAS will support only OCI artifact in the near future and fall back to use OCI Image manifest with a subject property if a registry doesn't support OCI artifact. There is no plan to support both ORAS artifact and OCI artifact in the same ORAS release. The last version of ORAS-go supporting ORAS artifact is v2.0.0-rc.3, and the last version of ORAS CLI supporting ORAS artifact is 0.15.x.

Check below table for the timeline of releases supporting OCI artifact:

Release ETA Date Related issue
ORAS-go v2.0.0-rc.4 End of Oct, 2022 ORAS-go #271
ORAS CLI 0.16.0 Nov 7, 2022 ORAS #406

ORAS-go supports reference types

Changes are required for the following use cases:

  • Pushing Manifests with Subject
  • Discovering Referrers
  • Deleting Manifests

Pushing Manifests with Subject

Follow the spec Pushing Manifests with Subject

Discovering Referrers

Follow the spec Listing Referrers

Deleting Manifests

Follow the spec Deleting Manifests

ORAS CLI supports reference types

ORAS push command

A new flag is introduced with the name --compatibility={none,min,max}, so that users can change the default pushing behavior.

  • With value set to min (default value), pushing OCI artifact manifests to a registry, if the response is 400 Bad Request, fallback to pushing OCI image manifest.
  • With value set to none, no fallback procedure is triggered for pushing OCI artifact manifests. Push fails if the response is 400 Bad Request.
  • With value set to max, OCI image manifests are pushed instead of OCI artifact manifests.

NOTES: The flag names are tentative. Any suggestions are welcome.

Should follow below steps:

  • PUT artifact manifest
  • If 200, we are good.
  • Else
    • If can fallback (we don't know that the referrers API is enabled, and the error is 400 and MANIFEST_INVALID), PUT OCI image manifest.
    • Else abort.

ORAS pull command

No changes

ORAS attach command

A new flag is introduced with the named --compatibility={none,min,max}, so that users can change the default pushing behavior.

  • With value set to min (default value), OCI artifact manifest with subject field is attached, if the response is 400 Bad Request, fallback to attaching OCI image manifest with subject field.
  • With value set to none, no fallback procedure is triggered for attaching OCI artifact manifests. Attaching fails if the response is 400 Bad Request.
  • With value set to max, OCI image manifests are attached instead of OCI artifact manifests.

If the referrers API returns a 404, use the same logic as ORAS-go Pushing Manifests with Subject.

NOTES: The flag names are tentative. Any suggestions are welcome.

Should follow below steps:

  • oras: Resolve the subject manifest –> 200
  • oras: PUT artifact manifest
    • If it succeeds,
      • oras-go: Check the referrers API is enabled or not.
        • If it is enabled, done / return
    • If it fails,
      • oras: set referrers capability to false.
      • oras: PUT image manifest
  • oras-go: Update the index

ORAS manifest fetch

No changes

ORAS manifest Push

Pushing manifests with subject

If the referrers API returns a 404, use the same logic as ORAS-go Pushing Manifests with Subject.

When pushing an OCI artifact manifests with subject field，if the response is 400 Bad Request, by default, fallback to pushing an OCI image manifest with subject field. Fallback procedure can be disabled using a new flag named --strict.

When user pushes an OCI Image manifest with subject field，by default, image index is updated, user can disable updating image index using the new flag --strict.

NOTES: The flag names are tentative. Any suggestions are welcome

Pushing manifests without subject

No changes when pushing an OCI image manifest without subject field.

When pushing an OCI artifact manifests without a subject field，if the response is 400 Bad Request, by default, fallback to pushing an OCI image manifest without a subject field. Fallback procedure can be disabled using a new flag named --strict (flag name is tentative).

NOTES: The flag names are tentative. Any suggestions are welcome

ORAS manifest Delete

By default, only supplied manifest is deleted.

Use a new flag named -r, --recursive to delete referrer manifests recursively. See below example, by using the flag -r, --recursive, when deleting subject manifest, manifest A, B, C are deleted, and image index are updated.

Use a new flag --strict to disable updating image index.

graph LR

A -- refers --> Subject
B -- refers --> Subject
C -- refers --> Subject
Index --> A
Index --> B
Index --> C

Tag --> Index

Tag -.- Subject

NOTES: The flag names are tentative. Any suggestions are welcome

ORAS blob

No changes

ORAS tag

No changes

ORAS repository

referrers tag schema may mess the results of oras repository list, so a new flag could be introduced to filter out referrers tag schema from the results.

ORAS discover

The same logic as ORAS-go discover referrers.

ORAS copy from target A to target B (include extended copy)

Notes: Registry is one type of target, there are others types of target, for example, OCI-layout.

ORAS doesn't perform manifest conversion, so copy succeeds only if both target A and target B support the type of manifest being copied.

Target B: Support OCI Artifact B: Support OCI Image
A: Copy OCI Artifact Success Failure
A: Copy OCI Image Success Success
Select a repo