With OCP 4.15 operator framework has introduced a new deprecation marker for File-Based Catalogs (FBC). This marker is similar in name to those used by legacy (SQLite) catalog formats, but with a different intent.
In legacy catalogs, OLM supported two CSV properties which influenced upgrade reconciliation:
olm.deprecated, meaning "omit from reconciliation"olm.substitutesFor, meaning "replaces a bundle with another"
Both of these properties were attempting to overcome limitations of the legacy catalog approach, whether it was that the catalog required no dangling bundle references but needed an 'out of bounds' marker on some versions (olm.deprecated), or that the principle of bundle immutability prevented the easy 'republication' of a bundle version in order to surpass a mistake, vulnerability, etc. (olm.substitutesFor).
With FBC catalogs, operator authors have much greater flexibility to express bundle upgrade graphs, but until this feature, the analog to the old olm.deprecated property was to omit the bundle version from the upgrade graph entirely. Authors asked for more nuance than a metaphoric cliff that bundle versions fall off of, and the new schema is an attempt to capture that nuance.
This is fine for all future bundle deployments and graph updates, but what about all the existing catalog content?
This repo is a request to operator author operators to start providing deprecation metadata about their operators and their upgrade graphs now, without requiring a bundle-republish or graph update, to be used in the OCP4.15 (and later) releases.
Clone the repo, and add deprecation metadata suitable for your operator(s) to the directory structure.
There is an example (but commented-out) set of deprecation available to follow in deprecations.yaml at
redhat-operator-index
└── 4.15
└── example-mypackage
└── deprecations.yaml
You may run validate crafted deprecation metadata against the appropriate catalog by executing scripts/validate_contribution.sh.
Before running the script, it's necessary to successfully docker login registry.redhat.io to ensure registry access.
The script will download and install the latest version of upstream opm and use it to render the latest version of the OCP4.15 redhat-operator-index catalog to ./redhat-operator-index/4.15/redhat-operator-index-v4.15.yaml.
A zero exit status indicates success.
On PR push to github, a similar workflow will trigger to validate the catalog configuration.
The general format of an olm.deprecations schema is
schema: olm.deprecations
package: <MANDATORY>package-name # this must be unique across the catalog
entries: # at least one of below reference types
- reference:
schema: olm.bundle # bundle version scope
name: <MANDATORY>bundle-version-name
message: <MANDATORY>descriptive message to catalog users about the specified bundle (e.g. suggested replacements)
- reference:
schema: olm.package
<MANDATORY>no name, since it is already specified and unique per-package
message: <MANDATORY>descriptive message to catalog users about the specified package (e.g. suggested replacements)
- reference:
schema: olm.channel
name: <MANDATORY>channel-name
message: <MANDATORY>descriptive message to catalog users about the specified channel (e.g. suggested replacements)The top-level package name is required. This should be the same as the package name used in the catalog. There should be at most one olm.deprecations schema for a package.
There are discrete entries types for package, channel, or bundle scopes. Each has their own requirements which are enforced by opm validate. Each entry is composed of a mandatory reference field to indicate the deprecation scope and a mandatory message field which is represented as an opaque text blob.
olm.package: represents the entire package. There must not be an associatedname.olm.channel: represents one channel.name(channel name) is mandatory.olm.bundle: represents one bundle version.name(bundle version name) is mandatory.
The below example demonstrates an instance of the olm.deprecations schema against the kiali package which enumerates a deprecation against each possible scope:
schema: olm.deprecations
package: kiali
entries:
- reference:
name: kiali-operator.v1.68.0
schema: olm.bundle
message: |
kiali-operator.v1.68.0 is deprecated. Uninstall and install kiali-operator.v1.72.0 for support.
- reference:
schema: olm.package
message: |
package kiali is end of life. Please use 'kiali-new' package for support.
- reference:
name: alpha
schema: olm.channel
message: |
channel alpha is no longer supported. Please switch to channel 'stable'.