Deprecate `substitute-for` field in the CSV

[anik120]

The substitute-For field was introduced to avoid the need to rebuild all bundles when a bundle image needed to be replaced with a new image/a bundle needed to be added in the middle of the upgrade graph. With plaintext filed backed Catalogs, to replace a bundle image, all one has to do is edit the plaintext files directly. Editing of the upgrade graph also will not require rebuilding of any bundle. Therefore the substitute-For field needs to be marked as deprecated with a warning that it only works for sqlite db backed Catalogs.

[joelanford]

The substitutesFor field is an annotation in the CSV and is only enabled via an alpha flag in opm, so I think it will be safe to remove it without notice as soon as we have a viable replacement solution in mind.

If it is documented somewhere without mention of it being alpha, we should update docs/comments to clarify its alpha status.

I'd like to investigate adding a release field to the bundle metadata as an alternative, much like rpm's release field, which is just a monotonically increasing integer that signals that an rpm has been rebuilt, but the underlying software has not changed.

This is very similar to the existing use case of substitutesFor, which is used to rebuild bundles to resolve CVEs in the underlying operator base images.

[joelanford]

Hmm - https://github.com/operator-framework/enhancements/blob/master/enhancements/substitutes-for.md#graduation-criteria

But also: https://github.com/operator-framework/operator-registry/blob/195bc038d915b8f65f1c4a1ebbcd82865aac4d23/pkg/sqlite/load.go#L119-L121

[joelanford]

Here are the rules I came up with for implementing substitutesFor with file-based catalogs.

Scenario:

• Bundle example-operator.v0.1.0 exists and needs to be substituted.
• Bundle example-operator.v0.1.0+1 substitutes for example-operator.v0.1.0

To add example-operator.v0.1.0+1 to a file-based catalog, use the following algorithm:

• add an entry for example-operator.v0.1.0+1 in every channel that contains example-operator.v0.1.0
• all example-operator.v0.1.0+1 entries must skip example-operator.v0.1.0
• in each channel, move example-operator.v0.1.0 replaces/skips/skipRange fields to the example-operator.v0.1.0+1 entry in that channel; after this step example-operator.v0.1.0 should not upgrade from any other entry.
• any entry that replaces example-operator.v0.1.0 should be changed to skip example-operator.v0.1.0 and replace example-operator.v0.1.0+1
• any entry that skips example-operator.v0.1.0 should also skip example-operator.v0.1.0+1

This algorithm assumes that the new bundle will directly substitute for the bundle it names. Concretely, if another bundle,example-operator.v0.1.0+2, needs to substitute for example-operator.v0.1.0+1, it should list example-operator.v0.1.0+1 as the substitution, not example-operator.v0.1.0.

[joelanford]

This algorithm assumes that the new bundle will directly substitute for the bundle it names. Concretely, if another bundle, example-operator.v0.1.0+2, needs to substitute for example-operator.v0.1.0+1, it should list example-operator.v0.1.0+1 as the substitution, not example-operator.v0.1.0.

This is probably an unnecessary restriction if we specify the sort order of the subsFor bundle version buildIDs (which we already do). Assuming there's a blob of subsFor metadata per package that lists all substitutions, it would be trivial to sort the subsFor bundles that substitute for the same original bundle to get the linear subsFor chain, and then iteratively execute the described algorithm.

[squakez]

Hi folks, we were planning to use this feature for automatically rebuilding the operator bundles. We bumped into this request for deprecation but it looks an old request and I am not sure if you're planning to work to this in the future. Would you mind to clarify if this is in the roadmap or no longer really in your radar?

[joelanford]

There is currently no support for substitutesFor in file-based catalogs (FBC), and the entirety of sqlite and related subcommands is deprecated. So substitutesFor is essentially already deprecated.

Having said that, this is a useful feature in general. And we should keep track of it with respect to FBC contexts.