Feature Overview

Enable release managers/Operator authors to manage Operator releases in the file-based catalog (FBC) based on the existing catalog (in sqlite) and distribute them to multiple OCP versions at ease.

Goals

• Operator releases can be managed declaratively in a canonical source of truth and automated via git in the context of the OpenShift release lifecycle.

• File-based catalog (FBC) can be converted back to sqlite format in order to be distribute to those OCP versions that do not support file-based catalog yet.

• Existing catalog image in sqlite format can be converted to the basic template of file-based catalog (FBC) for easy adoption.

• Existing catalog image in sqlite format can be converted to the semver template of file-based catalog (FBC) when possible and/or highlights the uncompleted sections so users can easier identify the gaps. 

Requirements

Use Cases

• Operator authors/release managers can manage releases (i.e., edit the update paths) in a canonical source of truth (in FBC) and automate it via git to simplify the bundle release process.

• Operator authors/release managers can mange and publish Operator releases from a canonical source of truth (in FBC) to multiple OCP versions.

• Operator authors/release managers can mange and publish Operator releases from a canonical source of truth (in FBC) to older OCP versions without FBC supported yet.

• Operator authors/release managers can convert their existing catalog images in sqlite format to the basic template of file-based catalog (FBC) to jumpstart the catalog migration process.

• Operator authors/release managers can convert their existing catalog images in sqlite format to the semver template of file-based catalog (FBC), when possible to drive adoption, and/or highlights the uncompleted sections so users can easier identify the gaps. 

Definition of Done / Acceptance criteria

• All use cases above are implemented and meet the requirements.

Background, and strategic fit

A catalog maintainer frequently needs to make changes to an OLM catalog whenever a new software version is released, promoting an existing version and releasing it to a different channel, or deprecating an existing version.  All these often require non-trivial changes to the update graph of an Operator package.  The maintainers need a git- and human-friendly maintenance approach that allows reproducing the catalog at all times and is decoupled from the release of their individual software versions.  

The original imperative catalog maintenance approach, which relies on `replaces`, `skips`, `skipRange` attributes at the bundle level to define the relationships between versions and the update channels, is perceived as complicated from the Red Hat internal developer community.  Hence, the new file-based catalog (FBC) is introduced with a declarative fashion and GitOps-friendly. 

Furthermore, the concept so-called “template”, as an abstraction layer of the FBC, is introduced to simplify interacting with FBCs.  While the “basic template” serves as a simplified abstraction of an FBC with all the `replaces`, `skips`, `skipRange` attributes supported and configurable at the package level, the “semver template” provides the capability to auto-generate an entire upgrade graph adhering to Semantic Versioning (semver) guidelines and consistent with best practices on channel naming.  

Based on the feedback in KubeCon NA 2022, folks were all generally excited to the features introduced with FBC and the UX provided by the templates.  What is still missing is the tooling to enable the adoption.  

Therefore, it is important to allow users to:

• convert the existing catalog image in sqlite format to the basic template of file-based catalog (FBC) for easy adoption

• convert the existing catalog image in sqlite format to the semver template of file-based catalog (FBC) when possible and/or highlights the uncompleted sections so users can easier identify the gaps

• automate the catalog update process using FBC with newly-published bundle references

• publish Operator releases in file-based catalog (FBC) to multiple OCP releases

• convert file-based catalog (FBC) back to sqlite database format so it can be publish to OCP versions without FBC supports 

to help users adopt this novel file-based catalog approach and deliver value to customers with a faster release cadence and higher confidence. 

Documentation Considerations

• The way ”to automate the catalog update process in FBC with newly-published bundle references” needs to be documented (in the context of “Developing Operators”).

• The way ”to to publish Operator releases in file-based catalog (FBC) to multiple OCP releases” needs to be documented (in the context of “Developing Operators” and “Administrator Tasks”).

• The way ”to convert file-based catalog (FBC) to sqlite database format so it can be publish to OCP versions without FBC supports” needs to be documented (in the context of “Developing Operators” and “Administrator Tasks”).

• The way ”to convert existing catalog from sqlite database to file-based catalog (FBC) basic template” needs to be documented (in the context of “Developing Operators”).

• The way ”to convert existing catalog from sqlite database to file-based catalog (FBC) semver template when possible and/or highlights the uncompleted sections so users can easier identify the gaps” needs to be documented (in the context of “Developing Operators”).