Goal

• Help customers who are building mirrors of OpenShift image to store subsets of multi-arch images without changing their digests for effective use with disconnected OpenShift clusters

Why is this important?

• OpenShift customers running disconnected looking to use OpenShift features are required to mirror extensive sets of images to get layered product functionality in the form of operators into the system
• This data set is large because many operators are available for multiple compute platforms, like x86_64, ppc64le or s390x (and soon very likely arm64) and distributed in manifest list images
• Currently there is no effective way of reducing the size of this set because only mirroring a subset of the desired manifests in the above manifest lists because creating new manifest lists with the desired subsets will have result in new digests which breaks OpenShift in disconnected environments (image refs are digest based)
• What's a required is to be able mirror the original manifest list without changing its digest but only mirror a subset of the desired manifests in the list

Scenarios

1. Quay has the ability to accept sparse manifests which are defined as manifest lists with multiple manifests referenced, with only a subset of these manifests actually stored in the same Quay instances as the manifest list
2. The support for sparse manifest list should be global configuration option, when enabled Quay accepts manifest lists being pushed where not all referenced images are available in Quay
3. The Quay UI has visual indication that a manifest list is sparse and when displaying manifest list entries visually differentiates those which are stored in Quay vs. those which are not
4. An API endpoints exists by which clients can query if the registry supports sparse manifest lists
5. Users can choose which architecture to mirror when creating a repo mirror job

Acceptance Criteria

• Clients can push manifest lists where not all referenced manifests are present in the target registry while retaining the original manifest lists digest
• Admins can enable sparse manifest list support system-wide but is disabled by default
• Users can discover sparse manifest list images in the UI
• Repo mirror jobs use sparse manifest lists when configured with architecture filters
• Clients can programmatically detect if the registry is configured to accept sparse images
• CI - MUST be running successfully with tests automated
• Release Technical Enablement - Provide necessary release enablement details and documents.
• ...

Prior work

• https://github.com/quay/enhancements/pull/29/files Design

Dependencies (internal and external)

1. https://github.com/opencontainers/distribution-spec/pull/310
2. oc image mirror and oc adm catalog mirror and oc mirror are aware this capability and mirror sparse manifest list instead of truncated manifest lists can auto-sense support in the registry

Open questions:

1. Do we anticipate the need to make support for sparse manifests configurable at the organization or even repository level?

Done Checklist

• CI - CI is running, tests are automated and merged.
• Release Enablement <link to Feature Enablement Presentation>
• DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
• DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
• DEV - Downstream build attached to advisory: <link to errata>
• QE - Test plans in Polarion: <link or reference to Polarion>
• QE - Automated tests merged: <link or reference to automated tests>
• DOC - Downstream documentation merged: <link to meaningful PR>