Feature Overview (aka. Goal Summary)  

oc-mirror v2's multi-arch filtering optimizes downloads, saves network bandwidth, and minimizes storage needs.

Goals (aka. expected user outcomes)

oc-mirror v2 allows users to specify the desired compute architectures for the images they intend to mirror and run in their disconnected environment. 

• To achieve this, oc-mirror v2 leverages Sparse Manifests, as described in PROJQUAY-3114, which are based on recent updates to the OCI and Docker image specifications.

• oc-mirror v2 will push manifest lists to the target registry without modification, preserving their original digest.  However, it will omit pushing child manifests that correspond to unsupported compute architectures, as defined in the oc-mirror configuration file.

This enables users to reduce the time and the amount of data transferred and stored in the disconnected registry, leading to faster mirror preparation and updates.

Background

Many customers in disconnected environments face challenges such as limited internet bandwidth or high storage costs.  While oc-mirror is a valuable tool for creating disconnected environments, its current approach of mirroring all multi-arch images, including all child manifests and images, can lead to increased storage consumption, especially for customers who only require a specific compute architecture.

By optimizing the mirroring process to include only the necessary images and manifests, oc-mirror can help customers reduce storage requirements as well as the time and the amount of data transferred, making it more efficient and cost-effective to maintain disconnected OpenShift core payload and optional operator images.

Requirements (aka. Acceptance Criteria):

• Sparse Manifest support: oc-mirror v2 can process Sparse Manifests, which are manifest lists that include information about all supported architectures, regardless of whether all architectures are present in the registry.

• Filtering by architecture: oc-mirror v2 supports filtering images by architecture, as defined in the image set configuration file for mirroring.

• Manifest list pull/push: oc-mirror v2 pulls manifest lists from the source registry and pushes them to the target registry unchanged, ensuring the original digest is maintained.

• Image pull: oc-mirror v2 pulls only the specified architectures from the source registry, as defined by the multi-arch filtering rules.

• Image push: oc-mirror v2 skips pushing child manifests that correspond to architectures excluded by the multi-arch filtering rules in the configuration file.

Documentation Considerations

• Sparse Manifests:
  • What a sparse manifest is and how it represents multiple architectures in a single manifest list.
  • How oc-mirror v2 processes and understands Sparse Manifests.

• Multi-Arch Filtering:
  • Step-by-step guide on configuring multi-arch filtering rules.
  • Examples of filtering by specific architectures or platforms.
  • How to verify the mirrored images and their architectures.

• Troubleshooting:
  • Introduce potential common issues, error messages, troubleshooting tips, and best practices.

Dependencies

• CRI-O: should work already (need QE to verify)
• `containers/image` library: ~Jan/Feb 2025
• Quay: ~Jun 2025