(doc) How to update operators documentation #988
Conversation
openshift-ci-robot
added
the
size/M
|
/retest |
1 similar comment
|
/retest |
|
|
||
|  | ||
|
|
||
| A user indicates a particular package (etcd) and channel (alpha) in a particular `CatalogSource` in a `Subscription`. If a `Subscription` is made to a package that hasn’t yet been installed in the namespace, the newest operator in the package/channel/catalog is installed. |
There was a problem hiding this comment.
I suggest describing it as the "head" of the channel rather than "newest", since OLM seems to deliberately avoid version comparisons in the way that some other familiar packaging formats do. It's all about the graph.
Speaking of which, it would be helpful to talk directly about that graph, maybe in a dedicated section, to get people on the same page about how an upgrade target is chosen.
|
|
||
| ## Replaces / Channels | ||
|
|
||
| Each Operator’s definition also known as `ClusterServiceVersion` (CSV) has a `replaces` field that indicates which operator it replaces. This builds a DAG ([directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph)) of CSVs that can be queried by OLM, and updates can be shared between channels. Channels can be thought of as entrypoints into the DAG of updates. A more accurate diagram would be: |
There was a problem hiding this comment.
Language nit-pick: the operator community at large thinks that etc-operator, prometheus-operator, mongodb-operator etc are all "operators". Those operators each have "releases" aka "versions". If possible to do while being consistent with existing OLM docs, it would help to clarify here that a CSV represents a specific release of an operator.
There was a problem hiding this comment.
Adding commas: "Each Operator’s definition, also known as ClusterServiceVersion (CSV), has a"
There was a problem hiding this comment.
Nit: Does OLM do anything to prevent the graph from being cyclic?
|
|
||
| OLM’s happy path for updates is: | ||
|
|
||
| * A `CatalogSource` is updated with one or more updates to an operator |
There was a problem hiding this comment.
Should both of these lines say "Channel" instead of "CatalogSource"?
| OLM’s happy path for updates is: | ||
|
|
||
| * A `CatalogSource` is updated with one or more updates to an operator | ||
| * We traverse every version of the operator until we’re at the newest version the `CatalogSource` contains. |
There was a problem hiding this comment.
By "traverse", are you implying that each version will be installed along the way? The next sentence seems to imply that, but it would be helpful to be explicit here.
And again I suggest using the word "head" instead of "newest version".
There was a problem hiding this comment.
I added a section named Upgrade Path with a given upgrade scenario that requires "traverse" through multiple versions to demonstrate this upgrade concept a bit better.
|
|
||
| Creating the “New Catalog” described above requires publishing CSVs that `replace` one operator, but can `skip` several. | ||
|
|
||
| ## Z-stream support |
There was a problem hiding this comment.
There is a desire by many operators to have y-release channels that each contain only z-releases. For example, a 1.1 channel and 1.2 channel. That gives the end user the ability to deliberately upgrade to a new y-release only when they are ready, but automatically consume z-releases.
That use case requires a particular use of skipRange and particular assumptions about testing and potential upgrade paths. It would be very helpful to describe that here. If you like, I'm happy to add that section after this PR merges.
There was a problem hiding this comment.
You are welcome to submit PRs to improve the doc further after the initial PR is merged. Any practical use cases that will provide further contexts to the doc are certainly appreciated.
|
Can we move this forward soon and get it merged? I would like to contribute additional docs about z-stream management before I forget what we settled on; that'll be a lot easier with this in-place. Thanks! |
|
I will get this PR updated to address some of the feedbacks and will get it moving forward and merged soon. Thanks. |
|
Quick note - docs now live in |
dinhxuanvu
force-pushed
the
update-csv
branch
3 times, most recently
from
94c8abc to
9a09a28
Compare
openshift-ci-robot
added
size/L
|
/retest |
2 similar comments
|
/retest |
|
/retest |
njhale
added
the
kind/documentation
dinhxuanvu
force-pushed
the
update-csv
branch
2 times, most recently
from
f737764 to
542b3e9
Compare
Signed-off-by: Vu Dinh <vdinh@redhat.com>
dinhxuanvu
force-pushed
the
update-csv
branch
from
542b3e9 to
98c24d9
Compare
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: dinhxuanvu, njhale 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:
Approvers can indicate their approval by writing |
openshift-ci-robot
added
the
approved
|
/retest |
1 similar comment
|
/retest |
|
@dinhxuanvu: The following tests failed, say
Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
|
doc-only, merging |
Signed-off-by: Vu Dinh vdinh@redhat.com