Documentation for Odo integration with Operator Hub #3029

dharmit · 2020-04-28T09:14:05Z

What type of PR is this?
/kind documentation
[skip ci]

What does does this PR do / why we need it:
Adds documentation explaining how to use Odo and Operator Hub

Which issue(s) this PR fixes:

How to test changes / Special notes to the reviewer:

yhontyk · 2020-04-28T09:17:22Z

docs/user/operator-hub.adoc

+# Odo integration with Operator Hub
+---
+
+When working in experimental mode, Odo provides the abilitiy to work with


abilitiy -> ability

yhontyk · 2020-04-28T09:18:50Z

docs/user/operator-hub.adoc

+In this document we will cover the following:
+
+. <<list-operators,List the operators installed in the current project>>
+. <<dry-run,Print the YAML specification that wil be used to start the service from a CRD>>


wil -> will

yhontyk · 2020-04-28T09:19:50Z

docs/user/operator-hub.adoc

+and the
+link:https://docs.openshift.com/container-platform/4.3/operators/crds/crd-extending-api-with-crds.html#crd-custom-resource-definitions_crd-extending-api-with-crds[CRD
+(Custom Resource Definitions)] provided by these operators. For example, we
+have installed Etcd and MongoDB opertors and the output we get is like below:


opertors -> operators

We generally capitalize Operators.

yhontyk · 2020-04-28T09:20:18Z

docs/user/operator-hub.adoc

@@ -0,0 +1,253 @@
+:source-highlighter: pygments
+
+# Odo integration with Operator Hub


Should Odo/odo be capitalized?

No, odo should not be capitalized. Good catch Yana.

yhontyk

Found a few typos.

Do you want me to make stylistic suggestions to the language (the many very rigid lang rules we use for downstream...) or do you prefer to have these upstream docs to be written in a less strict/more relaxed language?

kadel · 2020-04-28T09:43:07Z

/approve

openshift-ci-robot · 2020-04-28T09:43:24Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kadel

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:

~~docs/OWNERS~~ [kadel]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

codecov · 2020-04-28T11:52:28Z

Codecov Report

Merging #3029 into master will decrease coverage by 0.00%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3029      +/-   ##
==========================================
- Coverage   45.43%   45.42%   -0.01%     
==========================================
  Files         109      109              
  Lines       10400    10408       +8     
==========================================
+ Hits         4725     4728       +3     
- Misses       5220     5223       +3     
- Partials      455      457       +2

Impacted Files	Coverage Δ
pkg/sync/sync.go	`48.51% <0.00%> (-1.00%)`	⬇️
pkg/devfile/adapters/docker/component/utils.go	`71.36% <0.00%> (-0.91%)`	⬇️
pkg/devfile/adapters/helper.go	`10.34% <0.00%> (-0.37%)`	⬇️
pkg/debug/info.go	`67.56% <0.00%> (ø)`
pkg/occlient/utils.go	`11.11% <0.00%> (ø)`
pkg/odo/cli/service/ui/ui.go	`35.48% <0.00%> (ø)`
pkg/odo/cli/service/create.go	`11.11% <0.00%> (ø)`
pkg/devfile/adapters/common/command.go	`97.87% <0.00%> (ø)`
pkg/service/service.go	`68.30% <0.00%> (+0.54%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e1232ad...22d9114. Read the comment docs.

dharmit · 2020-04-28T11:59:54Z

Found a few typos.

Fixed them all. Thanks for the catch!

Do you want me to make stylistic suggestions to the language (the many very rigid lang rules we use for downstream...) or do you prefer to have these upstream docs to be written in a less strict/more relaxed language?

I'd prefer to keep it somewhat relaxed. But how do other teams (for eg: CRC) do this? Also, making changes here would mean that you can use more things as-is, right?

docs/user/operator-hub.adoc

cdrage

Hey @dharmit thank you so much for detailing how to use odo with Operator Hub.

My question is, is there any way you can format it similar to how we do some of the OpenShift tutorials? For example:

Showing how to create a project first
Using the numeric formatting (1. 2. 3. etc) of the steps

Similar to this example: https://odo.dev/docs/creating-a-multicomponent-application-with-odo/

The source being here: https://github.com/openshift/openshift-docs/blob/master/cli_reference/openshift_developer_cli/creating-a-multicomponent-application-with-odo.adoc

If not, no worries. at the moment, the site and the synchronization to the current docs is a bit messed up.

I know this is a lot to ask. But I can re-organize it if you'd like. I wouldn't be removing any of your notes, but simply putting it in a similar format as our current documentation.

cdrage · 2020-04-29T13:15:46Z

docs/user/operator-hub.adoc

+# odo integration with Operator Hub
+---
+
+When working in experimental mode, Odo provides the ability to work with


odo should not be capitalized

girishramnani · 2020-04-30T10:24:07Z

docs/user/operator-hub.adoc

+start from it.
+====
+
+To start an `EtcdCluster` service from `etcdoperator.v0.9.4` operator, you need


maybe mention that the name of the CRD is case sensitive?

girishramnani · 2020-04-30T10:25:16Z

docs/user/operator-hub.adoc

+
+=== [[dry-run]]Print the YAML used to start a service
+
+Odo provides the feature to print the YAML definition of the service (Custom


nit: s/Odo/odo

girishramnani · 2020-04-30T10:29:24Z

The docs are very nice and thorough, the one thing that worries me is that it exposes alot of words like pods, CRDs etc which we want to hide from the user as thats one of the principals of odo I suppose.
I understand that, the docs isn't the only place where this needs to be taken care of. or maybe we cannot solve this problem for the operator hub feature due to the limitations of the metadata accessible to odo. something to think about I guess.

kadel · 2020-04-30T11:36:41Z

The docs are very nice and thorough, the one thing that worries me is that it exposes alot of words like pods, CRDs etc which we want to hide from the user as thats one of the principals of odo I suppose.
I understand that, the docs isn't the only place where this needs to be taken care of. or maybe we cannot solve this problem for the operator hub feature due to the limitations of the metadata accessible to odo. something to think about I guess.

I wouldn't be afraid of using terms like Pods or CRDs in the documentation. This is a great place to explain what odo is doing under the hood, for those that are interested, and reveal some of the "odo magic".

dharmit · 2020-05-05T04:54:53Z

Hey @dharmit thank you so much for detailing how to use odo with Operator Hub.

My question is, is there any way you can format it similar to how we do some of the OpenShift tutorials? For example:
* Showing how to create a project first

* Using the numeric formatting (1. 2. 3. etc) of the steps
Similar to this example: https://odo.dev/docs/creating-a-multicomponent-application-with-odo/

The source being here: https://github.com/openshift/openshift-docs/blob/master/cli_reference/openshift_developer_cli/creating-a-multicomponent-application-with-odo.adoc

If not, no worries. at the moment, the site and the synchronization to the current docs is a bit messed up.

I know this is a lot to ask. But I can re-organize it if you'd like. I wouldn't be removing any of your notes, but simply putting it in a similar format as our current documentation.

Sure, I can make the changes that should help this piece use directly on odo website. That would be cool!

dharmit · 2020-05-05T05:13:49Z

The docs are very nice and thorough, the one thing that worries me is that it exposes alot of words like pods, CRDs etc which we want to hide from the user as thats one of the principals of odo I suppose.

I agree with your thought process but I think we've used the corresponding words used in odo terminology all over the place. For example, if we're talking about CSV, we make sure that the word Operator shows up right besides it or at least in the same sentence. Same for CR/CRD and service.

As for pods, it's showing up near the end of the doc where we explain the user that default configuration will bring up three pods of EtcdCluster. I don't see a way to use something else in its place. Three instances of EtcdCluster doesn't seem like entirely right to me. 😞

I understand that, the docs isn't the only place where this needs to be taken care of. or maybe we cannot solve this problem for the operator hub feature due to the limitations of the metadata accessible to odo. something to think about I guess.

I think we should always keep in mind to use the words in odo terminology more liberally than those from k8s terminology. So, if it seems like k8s terminology is used more than odo terminology, it's wrong on our part (here, my part) and we must fix it!

That said, I believe that documentation is a place where we could use words from k8s world so that interested users can know what's happening under the hood.

dharmit · 2020-05-05T12:33:43Z

@cdrage to make changes to this PR to structure the docs like you've suggested, I think I could do below:

break the sections in the .adoc file into modules.
have a modules directory at a level above docs/user/operator-hub.adoc, so that would be docs/modules

Is there anything else I'd be required to do?

cdrage · 2020-05-05T13:42:36Z

@dharmit Nope, no need for the modules. What I was suggesting is adding perhaps a "Creating a project" and following a similar format as: https://odo.dev/docs/creating-a-single-component-application-with-odo/

For example, we start with listing pre-requisites and follow a simple step-by-step structure. Have a look at a few of the other examples such as:

https://odo.dev/docs/creating-a-multicomponent-application-with-odo/

and https://odo.dev/docs/creating-an-application-with-a-database/ and notice how similar they are.

#3029 (comment)

dharmit · 2020-05-06T06:15:03Z

@cdrage I've made the changes. Hope they align with your recommendations. Let me know if you'd like me to make any changes. I've kept a separate "Prerequisites" section but let me know if it doesn't make sense to keep it.

Other than that, the docs on https://odo.dev need to change from Log in to an OpenShift cluster: to Login to the Kubernetes/OpenShift cluster:, IMO.

adisky · 2020-05-08T10:24:16Z

/lgtm

openshift-bot · 2020-05-08T10:36:39Z

/retest

Please review the full test history for this PR and help us cut down flakes.

dharmit · 2020-05-08T11:40:45Z

@cdrage need your input on this comment #3029 (comment). If it looks good, could you please LGTM?

/hold

cdrage · 2020-05-08T14:24:59Z

docs/user/operator-hub.adoc

+:source-highlighter: pygments
+
+# odo integration with Operator Hub
+---


Have to get rid of the above stuff :) not sure why this is here.

cdrage · 2020-05-08T14:26:00Z

docs/user/operator-hub.adoc

+the cluster. It allows listing of Operators, creation of services from CRD
+(Custom Resource Definitions) provided by the Operators, printing the YAML
+definition and providing custom YAML definition to start the service from a
+CRD.


Can you refactor the above sentence? We could instead create it as bullet points? Sorry! Just a very long sentence.

cdrage · 2020-05-08T14:27:13Z

docs/user/operator-hub.adoc

+[NOTE]
+====
+Installation of Operators is not a part of odo workflow. It is something that
+your OpenShift/Kubernetes cluster administrator should be able to do for you. 


We may have to remove this since you've already got it covered under prerequisites.

cdrage · 2020-05-08T14:27:20Z

docs/user/operator-hub.adoc

+
+=== Prerequisites
+
+- `odo` is installed.


can remove this

cdrage · 2020-05-08T14:27:48Z

docs/user/operator-hub.adoc

+=== Prerequisites
+
+- `odo` is installed.
+- Required Operators are installed in the project/namespace by cluster


Reword this?

Perhaps something like: Operators are required to be installed in your OpenShift cluster.

And then provide a link?

cdrage · 2020-05-08T14:28:45Z

docs/user/operator-hub.adoc

+
+[source,shell]
+----
+$ export ODO_EXPERIMENTAL=true


See how we do it here: https://odo.dev/docs/deploying-a-devfile-using-odo/#deploying-your-first-devfile

No need to go into detail with regards to adding experimental mode, we can make it just a one-liner under pre-requisites.

cdrage · 2020-05-08T14:29:19Z

docs/user/operator-hub.adoc

+Create a project to keep your source code, tests, and libraries organized in a
+separate single unit.
+
+1. Log in to the Kubernetes/OpenShift cluster:


Add spacing between /

cdrage · 2020-05-08T14:30:36Z

docs/user/operator-hub.adoc

+
+=== [[list-operators]]Listing the Operators
+
+To list the Operators installed in current project, execute below command:


installed in the current project

No need to have stuff like: execute the command

See examples such as: https://odo.dev/docs/creating-a-single-component-application-with-odo/

You just need to say: List the Operators installed in the current project.

And then show the command.

cdrage · 2020-05-08T14:32:39Z

docs/user/operator-hub.adoc

+NAME                          CRDs
+etcdoperator.v0.9.4           EtcdCluster, EtcdBackup, EtcdRestore
+mongodb-enterprise.v1.4.5     MongoDB, MongoDBUser, MongoDBOpsManager
+----


No need to have this section. Instead, add the output of this into line 75:

https://github.com/openshift/odo/pull/3029/files#diff-15071c5bfeaad296b2a7b29032ce0d56R75

And then go into detail after with the following paragraphs / sentences.

cdrage · 2020-05-08T14:32:55Z

docs/user/operator-hub.adoc

+----
+
+In above output, `etcdoperator.v0.9.4` is the Operator while `EtcdCluster`,
+`EtcdBackup` and `EtcdRestore` are the CRDs provided by this Operator.


the Operator

cdrage · 2020-05-10T14:08:36Z

Can you change this so it's in the

/docs/public folder? Then we can refactor after / LGTM :)

openshift-ci-robot · 2020-05-11T04:43:30Z

@dharmit: The following test failed, say /retest to rerun all failed tests:

Test name	Commit	Details	Rerun command
ci/prow/unit	`22d9114`	link	`/test unit`

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.

cdrage · 2020-05-11T13:04:20Z

/lgtm

openshift-ci-robot added the kind/documentation label Apr 28, 2020

openshift-ci-robot requested review from maysunfaisal and mohammedzee1000 April 28, 2020 09:14

dharmit requested review from cdrage, yhontyk and Preeticp and removed request for mohammedzee1000 and maysunfaisal April 28, 2020 09:14

yhontyk reviewed Apr 28, 2020

View reviewed changes

openshift-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. Required by Prow. label Apr 28, 2020

adisky reviewed Apr 29, 2020

View reviewed changes

docs/user/operator-hub.adoc Outdated Show resolved Hide resolved

cdrage suggested changes Apr 29, 2020

View reviewed changes

openshift-ci-robot assigned cdrage Apr 29, 2020

girishramnani reviewed Apr 30, 2020

View reviewed changes

cdrage mentioned this pull request May 1, 2020

Publish odo.dev site, integrate both OpenShift and Kubernetes documentation #2958

Closed

4 tasks

dharmit added 4 commits May 6, 2020 11:41

Documentation for Odo integration with Operator Hub

b2d8b9e

Changes based on PR review

852bbb1

It's odo, not Odo

f485730

Changes as suggested in PR review

ab0b7c9

#3029 (comment)

dharmit mentioned this pull request May 7, 2020

Adds debug command for devfiles #3059

Merged

Accommodate PR review and change case where required

ac5c657

openshift-ci-robot assigned adisky May 8, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. Required by Prow. label May 8, 2020

openshift-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. Required by Prow. label May 8, 2020

cdrage suggested changes May 8, 2020

View reviewed changes

openshift-ci-robot removed the lgtm Indicates that a PR is ready to be merged. Required by Prow. label May 8, 2020

Move from docs/user to docs/public

22d9114

cdrage merged commit 5226dab into redhat-developer:master May 11, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. Required by Prow. label May 11, 2020

dharmit deleted the fix-2779 branch May 15, 2020 04:45

		@@ -0,0 +1,253 @@
		:source-highlighter: pygments

		# Odo integration with Operator Hub


		=== [[dry-run]]Print the YAML used to start a service

		Odo provides the feature to print the YAML definition of the service (Custom


		=== [[list-operators]]Listing the Operators

		To list the Operators installed in current project, execute below command:

Documentation for Odo integration with Operator Hub #3029

Documentation for Odo integration with Operator Hub #3029

Conversation

dharmit commented Apr 28, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yhontyk left a comment

Choose a reason for hiding this comment

kadel commented Apr 28, 2020

openshift-ci-robot commented Apr 28, 2020

codecov bot commented Apr 28, 2020 • edited Loading

Codecov Report

dharmit commented Apr 28, 2020

cdrage left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

girishramnani commented Apr 30, 2020

kadel commented Apr 30, 2020

dharmit commented May 5, 2020

dharmit commented May 5, 2020

dharmit commented May 5, 2020

cdrage commented May 5, 2020

dharmit commented May 6, 2020

adisky commented May 8, 2020

openshift-bot commented May 8, 2020

dharmit commented May 8, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdrage commented May 10, 2020

openshift-ci-robot commented May 11, 2020

cdrage commented May 11, 2020

codecov bot commented Apr 28, 2020 •

edited

Loading