Creating an update graph with OLM - Add info about when use the skipRange and skips and its caveats

[camilamacedo86]

Description

It is not clear for the users when they should or not use skip/skipRange as it caveats
So, wdyt about we address it in the docs?

Suggestion

Following a draft for the content with some suggestions which probably need some shape.

So, when you can use olm..skipRange

a) If you do not care for the user and are unable to install the versions skipped ( they will be like pruned from the catalog )
b) f your Operator has no controller logic which requires your users to follow a specific upgrade path, such as migrating from version A to B to C exactly. Thus, ensuring that all required operations are performed until the latest version is installed.

When skips and skipRange gets more complicated?

When skips and skipRange gets more complicated?
See the following example:

v4 replaces v3.  
v3 skips v2.
v2 replaces v1

You cannot get to v4 now. In fact your users will be stuck at v1. Because when considering upgrade targets, OLM will never upgrade you to a version that is skipped by something else. Since v2 is skipped by v3, OLM will not upgrade you to v2, thus you can’t get to v3 and beyond.
The way skips is “intended” to be used is that you’d do the following:

v4 replaces v3.  
v3 skips v2 and v3 replaces v1
v2 replaces v1

The original intent of skips was “oops, we shipped v2 and then realized it’s a bad version, so we shipped a v3 that fixes the issue with v2. Thus, we want to “skip” v2 where possible (go from v1 to v3), but if you already have v2 installed, we’ll upgrade you to v3

[pavolloffay]

I have personally run into this issue and It took me some time to understand the bigger picture. I have also realized that replaces is optional when submitting the bundle to the community/prod operators.

This issue summarizes documentation for replaces,skipRange open-telemetry/opentelemetry-operator#926

[camilamacedo86]

Hi @pavolloffay,

In RedHat Community and OperatorHub you can opt-in for the semver-mode but it is valid only for these pipelines/indexes. This option is specific for them. Not all pipelines/indexes that you might choose to publish your bundle might support this option that instead of you inform replace/skip/skipRange you just keep empty and the upgrade graph will be built using replaces based using semver according to the bundles versions.