Feature Overview

The Operator Framework project introduces a new, generic API for filtering content within catalogs. This extensible and shareable API supports various use cases and tools, including:

• Offline mirroring with oc-mirror v2.
• In-cluster filtering for OLM v1 and the OpenShift console.
• Off-cluster filtering with the opm CLI utility.

Goals

This feature allows users to:

• List available operator versions: Search for operator versions within a catalog by package name, channel, or specific version range.
• Retrieve specific catalog properties: Efficiently retrieve a specified subset of properties for a given operator version within a full catalog.
• Identify required container images: Automatically extract the container images needed to run the listed operator versions.

This functionality centralizes the logic for filtering, querying, and extracting from catalogs.  This eliminates the need for redundant implementation, reducing the risk of inconsistencies.

Requirements:

The library and CLI provide functionality to:

• List operators with config-based filtering:
  • View all packages within a catalog.
  • List channels within a specific package.
  • Enumerate versions within a channel.
  • Retain valid upgrade paths for versions within a channel (based on OLM definitions).

• Extract container images:
  • Retrieve container image lists associated with operators, filtered by package, channel, and version range.

• Offline operation:
  • Perform all operations without internet connectivity or image downloads.

The CLI offers additional features:

• Output formats: Support human-readable text, YAML, and JSON output.
• opm integration: Implemented as a subcommand of the opm CLI utility.

Use Cases:

• Streamlined oc-mirror v2: This library simplifies image selection for oc-mirror v2, eliminating the need for redundant code within oc-mirror v2 itself.

• Custom Catalog Filtering: Developers can leverage the opm CLI utility to filter catalogs without image mirroring, for their custom filtering workflows.

• Custom Mirroring Solutions: The opm CLI utility empowers developers to build custom mirroring solutions, enabling the creation of filtered catalogs and extracting image references for custom mirroring implementations.

• Incremental Mirroring with oc-mirror v2: oc-mirror v2 leverages the library's filtering capabilities to optimize mirroring.  By comparing previously mirrored content (packages, channels, versions, and images) with the library's filter output, oc-mirror v2 efficiently identifies what needs updating (via incremental mirroring). 

Out of Scope

• the CLI tool will not list any additional metadata in its output that requires additional bundle images to be downloaded because they contain that metadata
• the CLI tool will not support merging or mutating existing catalog definitions, but instead create new ones - existing opm functionality can be used to create composite catalogs (link)

Background

Challenges with Separate Logic:

• oc-mirror v1 Complexity: Splitting catalog filtering and image extraction logic in oc-mirror v1 led to a cumbersome user experience and a complex codebase.

• OLM v1 Integration Gap: OLM v1 lacks an equivalent to packageserver (used for partial catalog content filtering in the OCP console).

• Limited Mirroring Options: Developers building custom mirroring solutions are restricted to using the complex oc-mirror v1.

Benefits of a Centralized Approach:

• Improved User Experience and Maintainability: A central shared library and CLI tool streamline development, simplify the codebase, and enhance the user experience for all tools utilizing this functionality.

Documentation Considerations

• the CLI tool needs documentation

Interoperability Considerations

• Integration and interoperability with oc-mirror v2, OCP console, and the opm CLI utility.

Relevant upstream CNCF OF PR

• render: add alpha support for filtering #1231