Feature Overview (aka. Goal Summary)  

FBC registry+v1 bundles have never supported use-cases associated with re-publishing an identical-version bundle, for e.g. CVEs, accidents, and have relied on machinery in pipelines to override users' expectations, with a number of caveats. 

By providing a format-native schema for determining preference among bundles with the same nominal version, we provide surprise-free abilities to perform retrograde updates to fulfill a number of use-cases.

Goals (aka. expected user outcomes)

Operator authors will be able to re-publish a bundle with a higher `release` attribute than predecessors, and it will be preferred on-cluster over similarly-versioned bundles while providing migration paths for customer with existing installs of the bundle with lesser release versions.

Requirements (aka. Acceptance Criteria):

Use Cases (Optional):

• operator bundle authors (and automated systems fulfilling this persona) must be capable of expressing a re-release relation to existing, published bundle versions in ClusterServiceVersions to enable the ability for authors to be able to create and publish re-released registry+v1 bundle manifests.
• operator bundle authors (and automated systems fulfilling this persona) must be capable of expressing and validating operator upgrade graphs containing re-release version representations, including
  • re-release naming constraints to ensure superseding relationship is transparent
  • adoption and conversion of existing content using the existing freshmaker `olm.substitutesFor` annotation-based API and version expression paradigms
• operator bundle authors (...) must have simplified approaches to avoid upgrade graph confusion by adhering to re-release upgrade graph best practices.
  • (in the form of a catalog template)
• opm tooling must be capable of providing a stable ordering of multiple bundle versions for a package where re-release version information may or may not be present, as well as exporting the ordering functions as part of a library for other tooling to utilize.
  • (level TBD, but might be at declcfg.Bundle or model.Bundle levels)
• olmv1 successor identification must utilize a stable ordering of multiple bundle versions for a package where re-release version information may or may not be present, and prefer the highest re-released bundle with identical version as that selected (as maximal extent; as pinned version; other?).  Functionality must be feature-gated.
• cluster-admins (olmv1) must be capable of selecting re-release-version-specific bundle versions.  Functionality may be feature-gated.
  • ClusterExtension API must be capable of accepting re-release-version-specific pinning.
  • ClusterExtension API must fail deployment with a clear diagnostic indicator if a re-release-version-specific pin is specified which results in no bundles found (TBD whether this needs to differentiate from existing "no matching bundles found" messaging).
• olmv0 must be capable of utilizing a stable ordering of multiple bundle versions for a package where re-release version information may or may not be present which favors re-released bundles, wherever bundle ordering outside the version graph is utilized. There are no feature-gates in v0. 

Questions to Answer (Optional):

Include a list of refinement / architectural questions that may need to be answered before coding can begin.  Initial completion during Refinement status.

<your text here>

Out of Scope

• unrelated updates to ClusterServiceVersion or the registry+v0 spec
• introduction of new FBC schema
• updates to the olmv0 GRPC API (all graph updates will be performed on the production side such that they are correct when presented via the GRPC API)
• introduction of a feature-gating mechanism to OLMv0

Background

https://docs.google.com/document/d/1tX0fXYuflTpTal6z0TbNkrQ7SAkYIKxQj4cPjlFAh4Q/

Customer Considerations

n/a

Documentation Considerations

Documentation updates will need to be made for receiving OCP versions in the area of

• "what is a release version"
• interaction with previous freshmaker feature
• tooling descriptions (template, opm render/migrate support)
• ClusterExtension API changes
• ClusterExtension release-version pinning implications and howto
• ClusterServiceVersion API documentation

Interoperability Considerations

• ClusterServiceVersion changes should be ignored in any case where the on-cluster processes lag behind the production versions where this feature is introduced.  For example, if a package introduces a new CSV with a release version which is intended for consumption in OCP 4.16..4.21, then OCP versions older than this feature will ignore the unknown field.
• ROSA/HCP configurations where the default catalogs available to the managed cluster straddle the feature delivery timing (in either direction) will ignore the unknown field.