refine install and dependency docs #21

dmesser · 2019-12-02T13:30:40Z

Signed-off-by: dmesser dmesser@redhat.com

Signed-off-by: dmesser <dmesser@redhat.com>

Bowenislandsong

Great PR, Thank you for cleaning some of the stuff up. Just some nits.

Bowenislandsong · 2019-12-02T15:46:31Z

docs/how-do-i-install-my-operator-with-olm.md

+You can inspect your `Subscription` with `kubectl describe subs <name-of-your-subscription> -n <namespace>`.

+```yaml
+k describe subs subs-to-my-operator -n olm 


Maybe we want to say $ kubectl instead of k?

Bowenislandsong · 2019-12-02T20:40:15Z

docs/operator-dependencies-and-requirements.md

+In case multiple Operators serve a required API, rather than using the first match, OLM searches `CatalogSources` in a specific order. First is the same catalog that contains the Operator stating the dependency, followed by other catalogs in the same namespace as the required `Subscription` and then finally all remaining `CatalogSources` objects in other namespaces of the cluster.

-If the required API cannot be resolved, OLM will not install operators that rely on that API.
+If are required API cannot be resolved or found, OLM will not install operators that rely on that API.


nit: I don't understand why we changed the to are...

awgreene

Nice work @dmesser, a few comments but the suggested changes look great.

awgreene · 2019-12-03T12:37:27Z

docs/how-do-i-install-my-operator-with-olm.md

-# How do I install my operator with OLM? 
+# How do I install my operator with OLM?
+
+[Once you've made your packaged operator available in a catalog](packaging-an-operator.md) it will appear in the `packagemanifest` list from which the Operators to install are selected. See [How do I list available Operators](list-available-operators.md#information-relevant-for-installation) how to retrieve the required information from the `PackageServer` in order start an installation of an Operator.


The following sentence does not read well:

See [How do I list available Operators] how to retrieve...

awgreene · 2019-12-03T12:39:32Z

docs/how-do-i-install-my-operator-with-olm.md

+$ kubectl describe packagemanifest my-operator
+```
+
+ With this information a `Subscription` object can be created. This represents the intent to install an Operator from a particular catalog and keep it updated throughout the life cycle of the Operator via newly released version that got subsequently added to the referenced catalog.


I would recommend changing

This represents the intent to install an Operator from a particular catalog and keep it updated throughout the life cycle of the Operator via newly released version that got subsequently added to the referenced catalog.

to

A subscription represents the desire to install an Operator from a particular catalog and keep it updated as new versions are subsequently added to the referenced catalog.

or somethings along those lines.

Maybe even

With this information, a Subscription to an operator can be created.

instead of

With this information a Subscription object can be created.

And in @awgreene 's suggestion:

A subscription represents the desire to install an Operator from a particular catalog and keep it updated as new versions are subsequently added to the referenced catalog.

if we tweak it to

A subscription represents the desire to install an Operator from a particular catalog, and subscribe to updated version of the operators as they are subsequently added to the catalog.

then if could read like more of a user facing doc than dev facing doc.

awgreene · 2019-12-03T12:40:52Z

docs/how-do-i-install-my-operator-with-olm.md

-For example, if you want to install an operator named `my-operator`, from a catalog named `my-catalog` that is in the namespace `olm`, and you want to subscribe to the channel `stable`, your subscription yaml would look like this: 
+ ```
+
+The `spec.channel` property can also be omitted in which case the default channel will be picked. Optionally you can also define `spec.startingCSV` to denote that you want to install a specific version of your Operator and not the latest.


Should we highlight behavior when specifying spec.startingCSV with automatic approval? My concern is that users will set a startingCSV expecting that the specified version will persist on cluster and be surprised when it is updated.

awgreene · 2019-12-03T12:44:51Z

docs/how-do-i-install-my-operator-with-olm.md

+
+NAME                    READY   UP-TO-DATE   AVAILABLE   AGE
+my-operator             1/1     1            1           9m48s
+```


Should we highlight that a new installPlan for the next available version will be created when available? This will give users an idea how to perform a manual update.

awgreene · 2019-12-03T12:46:01Z

docs/list-available-operators.md

 # How do I list Operators available to install?

-There is an extension API in OLM named `PackageManifest` that contains information about existing `CatalogSources`, which is essentially a repository of CSVs, CRDs, and packages that define an operator in the cluster. By querying that API, you can see the list of available operators.
+There is an extension API in OLM named `PackageManifest` that contains information about the content served by `CatalogSources`, which is essentially a repository of CSVs, CRDs, and packages that define a operator in the cluster. By querying that API, you can see the list of available operators.


a operator

This should be:

an operator

awgreene · 2019-12-03T12:50:27Z

docs/list-available-operators.md

+If there are no `CatalogSource` objects present in the current namespace of the command above the list will contain all Operators found in global catalogs. To include Operators available to install from namespace catalogs simply supply it with the `kubectl` command:
+
+```bash
+$ kubectl get packagemanifests
+
+NAME                               CATALOG               AGE
+...
+my-operator                        My Catalog            31m
+...
+```


As someone that has worked with OLM before this is clear, but it may not be clear to users unfamiliar with OLM.

awgreene · 2019-12-03T12:51:13Z

docs/list-available-operators.md

+NAME                               CATALOG               AGE
+...
+my-operator                        My Catalog            31m
+...


You used [...] above to imply that additional output existed. Please chose a single format.

awgreene · 2019-12-03T12:56:06Z

docs/operator-scoping.md

 Any operator tied to this `OperatorGroup` will now be confined to the permission(s) granted to the specified `ServiceAccount`. If the operator asks for permission(s) that are outside the scope of the `ServiceAccount` the install will fail with appropriate error(s).

-An example of scoping an operator can be found [here]("https://operator-framework.github.io/olm-book/docs/how-do-i-scope-down-an-operator).
+An example of scoping an operator can be found [here](./).


We can probably remove this.

anik120

Thanks for the PR @dmesser. Had a few comments.

anik120 · 2019-12-03T19:28:19Z

docs/how-do-i-install-my-operator-with-olm.md

+You can then either interactively set the `spec.approved` property of the `InstallPlan` to `true` or _patch_ the object like so:
+
+```bash
+kubectl patch installplan install-q4fmf -n olm --type merge  -p '{"spec":{"approved":true}}'


Should we get rid of the "What do I approve an update?" doc too if we're putting this information here?

anik120 · 2019-12-03T19:35:45Z

docs/how-do-i-install-my-operator-with-olm.md

+
+## Install with automatic updates enabled
+
+First, retrieve the package name, channel and catalog name and catalog source namespace from the `packagemanifest` of the desired Operator to install.


nit: package name, channel, CatalogSource name, and CatalogSource namespace from the packagemanifest...

anik120 · 2019-12-03T19:38:16Z

docs/discover-operator-presence.md

 would return all CSVs across all namespaces and provide a high-level view of all custom installed operators. 

-If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](https://) to debug your installation.  
+If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](troubleshooting.md) to debug your installation.  


We could link to (troubleshooting.md#clusterserviceversion-troubleshooting) to link to the more relevant section instead of the entire doc.

anik120 · 2019-12-03T19:39:37Z

docs/how-do-i-install-my-operator-with-olm.md

-NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
-<name-of-your-operator>      1/1     1            1           9m48s
+
+If the ClusterServiceVersion fails to show up or does not reach the `Succeeded` phase, please check the [troubleshooting documentation](troubleshooting.md) to debug your installation.


Same comment as above about the (troubleshooting.md#clusterserviceversion-troubleshooting).

anik120 · 2019-12-03T19:50:27Z

docs/how-do-i-install-my-operator-with-olm.md

+$ kubectl describe packagemanifest my-operator
+```
+
+ With this information a `Subscription` object can be created. This represents the intent to install an Operator from a particular catalog and keep it updated throughout the life cycle of the Operator via newly released version that got subsequently added to the referenced catalog.


Maybe even

With this information, a Subscription to an operator can be created.

instead of

With this information a Subscription object can be created.

And in @awgreene 's suggestion:

A subscription represents the desire to install an Operator from a particular catalog and keep it updated as new versions are subsequently added to the referenced catalog.

if we tweak it to

A subscription represents the desire to install an Operator from a particular catalog, and subscribe to updated version of the operators as they are subsequently added to the catalog.

then if could read like more of a user facing doc than dev facing doc.

anik120 · 2019-12-03T19:52:55Z

docs/how-do-i-install-my-operator-with-olm.md

 ```
-$ kubectl get csv -n <namespace-operator-was-installed-in>
+
+The `Subscription` has successfully deployed the Operator when the `status.state` property reaches `AtLatestKnown`.


Is this always true? If the CSV reaches a Failed state, will the Subscription not reach AtLatestKnow?

openshift-ci-robot · 2021-04-09T12:34:19Z

@dmesser: PR needs rebase.

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.

refine install and dependency docs

1149a32

Signed-off-by: dmesser <dmesser@redhat.com>

dmesser requested a review from awgreene December 2, 2019 13:30

openshift-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Dec 2, 2019

dmesser requested a review from Bowenislandsong December 2, 2019 13:30

dmesser force-pushed the doc-improvements branch from a07b73c to 49e9171 Compare December 2, 2019 13:58

fix broken links

06a8d68

Signed-off-by: dmesser <dmesser@redhat.com>

dmesser force-pushed the doc-improvements branch from 49e9171 to 06a8d68 Compare December 2, 2019 14:08

Bowenislandsong reviewed Dec 2, 2019

View reviewed changes

awgreene suggested changes Dec 3, 2019

View reviewed changes

anik120 suggested changes Dec 3, 2019

View reviewed changes

Merge branch 'master' into doc-improvements

1113a86

openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 9, 2021


		## Install with automatic updates enabled

		First, retrieve the package name, channel and catalog name and catalog source namespace from the `packagemanifest` of the desired Operator to install.

refine install and dependency docs #21

Are you sure you want to change the base?

refine install and dependency docs #21

Uh oh!

Conversation

dmesser commented Dec 2, 2019

Uh oh!

Bowenislandsong left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awgreene left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anik120 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci-robot commented Apr 9, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants