search

operator-framework / olm-docs

Hugo doc site for https://github.com/operator-framework/operator-lifecycle-manager
10 stars 82 forks source link

Clarify use of version numbers in channel names #139

Closed gsaslis closed 3 years ago

gsaslis commented 3 years ago

Version numbers, on their own, are ambiguous and could be referring to either product or operator version itself.

If I am creating a Subscription to channel 1.x of 3scale-operator (note: /not/ of 3scale - the product), is it really clear that this version is referring to the version of 3scale (the product) and not to the version of 3scale-operator (the component)?

As far as I understand when reading these Naming conventions, the intent is for the former (i.e. that the version refers to the product), but does it hurt us to be explicit - by including the product name - and avoid any confusion at all around this?

The problem is that: a. "3scale operator" is a component that has different versioning than "3scale" (the product). For 3scale 2.10, 3scale operator has version 1.13.0 b. As such, even if the channel is always used within the context of a Subscription, I can never be sure if the version is the version of the operator, or the product (because the subscription is to the operator, not the product).

The screenshot from step 2, but also the Subscription YAML both, hopefully, help illustrate the problem I am referring to.

If "threescale-" was not included in the channel name and only "2.9" was, how could I know that "2.9" is referring to 3scale (the product) when I am subscribing to the operator ?

Operator Installation - OpenShift Console

Step 1: Pick operator

operatorInstallation1

Step 2: Select channel

operatorInstallation2

Step 3: View Subscription

operatorInstallation3

Alternate installation step : Subscription installation through YAML

This is what the customer who chooses to install the 3scale operator by applying YAML to their openshift cluster will see.

operatorInstallation4

https://github.com/gsaslis/3scale-deployment/blob/main/operators/3scale/3scale-operator-subscription.yaml#L7-L9

openshift-ci-robot commented 3 years ago

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gsaslis To complete the pull request process, please assign njhale after the PR has been reviewed. You can assign the PR to them by writing /assign @njhale in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files: - **[OWNERS](https://github.com/operator-framework/olm-docs/blob/master/OWNERS)** Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment
jmccormick2001 commented 3 years ago

https://olm.operatorframework.io/docs/best-practices/channel-naming/#docs I think the closest we got to a naming convention that covers the operand version is Example 3 from our channel naming conventions. But it sounds like you need a combination of Example 2 and Example 3 if I'm understanding the question. So lets assume that you have a database operator at version 2.4 and it creates operands at version 13.0, then you might desire to have a channel name of something like stable-2.4-pg-13.0 or similar. Would that work or be good enough to cover this situation?

gsaslis commented 3 years ago

@jmccormick2001 actually, looking at the examples you pointed to, Example 2 has the same problem I'm describing above (please make sure to check the screenshots, especially step 2).

In step 2, if I see "preview-2.4", is "2.4" referring to the product version, or the operator version? How can one be sure?

In fact, I think Example 2 is problematic and should probably be adapted based on the outcome of this discussion.

Example 3 is fine, as far as I'm concerned. The use of a version number ("12" and "13" in that case) is qualified by "pg". It is clear that version is referring to the version of the product (i.e. pg) and not of the operator.

jmccormick2001 commented 3 years ago

you are right I think, we left it pretty vague in that you could refer to a product or the operator version with those examples. Perhaps something like: stable-op-2.4-pg-13 would be clearer, that 'op' would indicate operator version, to the right of that we could assume operand versions. If you had just stable-1.2-op-2.4-pg-13 that would mean, the product is version 1.2, its operator is 2.4, and its operand is pg 13.0. What do you think about such a convention as that?

gsaslis commented 3 years ago

@jmccormick2001 I am not very familiar with cases where the product and the operand would be different. I always somehow imagined in my head that they were the same thing and there was only "product version" and "operator version", but it looks like I was wrong. šŸ˜Š

Perhaps something like: stable-op-2.4-pg-13 would be clearer, that 'op' would indicate operator version, to the right of that we could assume operand versions. If you had just stable-1.2-op-2.4-pg-13 that would mean, the product is version 1.2, its operator is 2.4, and its operand is pg 13.0. What do you think about such a convention as that?

I am a little concerned we might be trying to bake in too much logic into the channel name with such an example. šŸ¤” It is even starting to sound like perhaps that information should live in separate fields rather than having all of that baked into the channel name.

That is probably opening a broader discussion though and it sounds like it might be stretching what the scope of this PR was. šŸ˜…

The only thing I wanted to fix with this PR was to avoid having entirely unqualified version numbers (because it would not always be clear what they were referring to). Do you think the text change in this PR is enough to improve that? Could we get that part merged and move the other discussion in a more suitable place?

jmccormick2001 commented 3 years ago

@gsaslis thanks, I think this PR is fine to merge. What I've learned recently is that OLM when it moves to a declarative config design will support metadata on channels which would allow for much more precision in discovering a channel. This is going to be vastly better than trying to include that metadata into the channel name.

gsaslis commented 3 years ago

@jmccormick2001 that is definitely GREAT news! šŸŽ‰ thanks for sharing. This is exactly what I meant with:

It is even starting to sound like perhaps that information should live in separate fields rather than having all of that baked into the channel name.

and I'm glad to see things are already headed in this direction.

timflannagan commented 3 years ago

/lgtm

openshift-ci[bot] commented 3 years ago

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: anik120, gsaslis

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files: - ~~[OWNERS](https://github.com/operator-framework/olm-docs/blob/master/OWNERS)~~ [anik120] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment