Feature Overview (aka. Goal Summary)  

Design an API to expose the catalog introspection tools.

Design a feature to allow the user to pin a catalog. The introspection tool will allow to pin the selected catalog.

The phase 2 should have a design ready and approved as enhancement proposal via OpenShift enhancement process.

Goals (aka. expected user outcomes)

A design document to expose the API for the catalog introspection.

A design document that will explain how to use the API to pin the selected catalog.

A working prototype - tech preview level, to enable GA in the next release.

— more details from RFE-4930 triggering this request —
1. Proposed title of this feature request

oc operator catalog introspection tool

2. What is the nature and description of the request?

A new oc-based plugin utility is available that can introspect and filter the content of existing OLM operator catalog according to user-specified filtering criteria to create a list of container images and artifacts required to run this content subset and the ability to create a new catalog with only that content.

In essence, this new tool will be able to filter OLM operator catalog content in the same way that oc-mirror supports today:

• by catalog name
• by operator package name in a catalog
• by operator channel name in a package of a catalog
• by version range inside a channel of a package in a catalog

This filter criteria should be something to be supplied in a config file akin to the ImageSetConfig API today. This allows customers to flexibly decide which operators they want to be part of their new catalog.

Out of this filtered subset of content, the new tool will be able to create an artifact mapping file containing the container images related to the filtered content subset. The mapping file maps the source image reference to a target image reference. The format must allow easy modification of the target image reference and generally be machine-readable for easy post-processing.

In addition, this new tool will be able to create a new catalog image out of this content subset referencing the image mapping mentioned above.

oc-mirror will be able to directly use this new tool's input to create an appropriate mirror in the same way it does today.
So, in a sense, this feature request asks for a subset of the existing oc-mirror functionality to be spun out into a separate tool to allow for more custom use cases and to avoid polluting the interface of oc-mirror.

3. Why does the customer need this? (List the business requirements here)

An extensive set of use cases around oc-mirror in today's form focuses on creating new catalogs, which represent subsets of existing catalogs based on user-supplied filter criteria. Users generally only want to see a specific subset of public content for various reasons that are not solely related to mirroring, such as internal testing, licensing restrictions, etc.
Another widespread use case is to extract the image references of a filtered subset of public catalog content to carry out the mirroring of these images in a more custom way, e.g., when a particular form of organizing the images in the target registry is desired.

4. List any affected packages or components.

oc-mirror

— Consider RFE-5585  for additional suggestions —
1. Proposed title of this feature request

Introspection and monitoring commands

2. What is the nature and description of the request?

Create some simple introspection commands to quickly gather information. Offer some quick output commands like:

• "ocm -a authfile <catalog image> –list-operators"
  • list all packages
• "ocm -a authfile <catalog image> –list-operators –versions"
  • list all packages, and versions and put the current version in brackers [curentversion] so it stands out
    • Auto-detect default channel
• "ocm -a authfile <catalog image> –list-operators –versions –channel"
  • Do the same as the above, but allow channel specification
• A meta data flag to show more information, such as "Supported Install modes", or a list the install modes with –list-operators.
• Offer an -o yaml or -o json output as well for use with scripting/programming outside of the tool. 

3. Why does the customer need this? (List the business requirements here)

Customer needs to publish a document containing the operator version for each operator in the catalog (Customer always takes the latest version from the default channel), but customer has to sift through JSON to get this data today.

4. List any affected packages or components

oc-mirror/registry