Documents steps for component creation #4982

dharmit · 2021-08-10T13:56:05Z

What type of PR is this?
/kind documentation

What does this PR do / why we need it:
what: $subject
why: because it helps users new to odo

Which issue(s) this PR fixes:

Fixes part of #4895

PR acceptance criteria:

How to test changes / Special notes to the reviewer:

netlify · 2021-08-10T13:57:30Z

✔️ Deploy Preview for odo-docusaurus-preview ready!

🔨 Explore the source changes: e15c6c3

🔍 Inspect the deploy log: https://app.netlify.com/sites/odo-docusaurus-preview/deploys/61128577150507000729e565

😎 Browse the preview: https://deploy-preview-4982--odo-docusaurus-preview.netlify.app

netlify · 2021-08-10T13:59:19Z

✔️ Deploy Preview for odo-docusaurus-preview ready!

🔨 Explore the source changes: 6a4e77e

🔍 Inspect the deploy log: https://app.netlify.com/sites/odo-docusaurus-preview/deploys/611373c2ae6c6e0007618166

😎 Browse the preview: https://deploy-preview-4982--odo-docusaurus-preview.netlify.app

This is to ensure relevant folks are pinged for reviews.

kadel · 2021-08-10T14:02:55Z

Changelog.md

@@ -11,10 +11,11 @@

 ### Tests

- runs nightly test of main branch of odo against [SBO master branch](https://github.com/redhat-developer/service-binding-operator) ([4942](https://github.com/openshift/odo/issues/4942))
+- runs nightly test of main branch of odo against [SBO master branch](https://github.com/redhat-developer/service-binding-operator) ([#4942](https://github.com/openshift/odo/issues/4942))


It would help if you elaborate beyond a "?".

What is this change? It is completely unrelated to this PR

1f0ac44

I hope that helps.

#4983

I hope that helps as well.

website/docs/using-odo/create-component.md

kadel · 2021-08-10T14:08:04Z

website/docs/using-odo/create-component.md

+Among the various ways described above, irrespective of how you created the component, the next step to create the resources for our component on the cluster would be to run `odo push`
+
+Note that first run of `odo push` could take a long time for the Spring Boot petclinic project. This is because of the dependencies being pulled by Spring Boot framework. Subsequent `odo push` runs shouldn't take longer when working on the same Kubernetes cluster.


Spring Boot framework is not pulling any dependencies. Spring boot is one of the dependency.
petclinic uses maven to manage java dependencies

I have reworded it. PTAL.

website/docs/command-reference/catalog.md

Co-authored-by: Tomas Kral <[email protected]>

valaparthvi

Overall the doc looks good to me. Good work :)

website/docs/using-odo/create-component.md

valaparthvi · 2021-08-11T05:20:51Z

website/docs/using-odo/create-component.md

+   ```
+   Now you will have a `devfile.yaml` in your current working directory. But odo is just not done asking you questions yet.
+4. Lastly, odo asks you if you would like to download a starter project. Since we already cloned the petclinic project, we answer in No by typing `n` and hitting the return key:


Lastly, odo asks you if you would like to download a starter project.

Asking from a reader's perspective: What is a starter project?

I had this question a lot of times when I was getting started with odo; it might help to give starter project an alias, say example project in the brackets. Or better yet, add the hyperlink to the starter project section in the doc.

hitting the return key

Return key? Shouldn't it be the enter key?

Asking from a reader's perspective: What is a starter project?

I had this question a lot of times when I was getting started with odo; it might help to give starter project an alias, say example project in the brackets. Or better yet, add the hyperlink to the starter project section in the doc.

Thanks for the catch! I had put a reference in the beginning of the doc. So I didn't put it here. But then I removed that statement and didn't remember to put it here. Updated. PTAL.

Return key? Shouldn't it be the enter key?

They are the same. I have observed "Return" used more widely in docs.

website/docs/using-odo/create-component.md

valaparthvi · 2021-08-11T05:32:11Z

website/docs/using-odo/create-component.md

Would && work on windows/mac? If not, should we separate the 2 commands?
Also, it would help with copying the command if you separate odo create in a different code block.

Would && work on windows/mac? If not, should we separate the 2 commands?

I'm inclined to think it will work. @kadel can you help check if this works on Windows?

Also, it would help with copying the command if you separate odo create in a different code block.

I intentionally put it in the same block because the entire thing works just fine. But I'm on Fedora. Worth checking if it works on Windows. Mac, I would be surprised if it doesn't work.

valaparthvi · 2021-08-11T05:34:31Z

website/docs/using-odo/create-component.md

+## Push the component to Kubernetes
+
+odo follows a "create & push" workflow for almost all the commands. Meaning, most odo commands won't create resources on Kubernetes cluster unless you run `odo push` command.


most odo commands won't create resources on Kubernetes cluster

I am still confused whether we should mention just the K8s cluster or OCP as well.

IMO k8s. OCP is for docs.openshift.com, not for upstream.

website/docs/using-odo/create-component.md

valaparthvi · 2021-08-11T05:36:25Z

website/docs/using-odo/create-component.md

+Among the various ways described above, irrespective of how you created the component, the next step to create the resources for our component on the cluster would be to run `odo push`
+
+Note that first run of `odo push` could take a long time for the Spring Boot petclinic project. This is because of the dependencies being pulled by maven for Spring Boot framework. Subsequent `odo push` runs shouldn't take longer when working on the same Kubernetes cluster. 


Subsequent odo push runs shouldn't take longer when working on the same Kubernetes cluster.

Again, should it just be K8s or OCP as well?

#4982 (comment)

website/docs/using-odo/create-component.md

valaparthvi · 2021-08-11T05:43:04Z

website/docs/using-odo/create-component.md

+[Component](../getting-started/basics#component) is the most basic unit of operation for odo. And the way to create one is using `odo create` (short for `odo component create`) command.
+
+In simplest terms, when you "create" an odo component, you populate your current working directory with the file `devfile.yaml`. It is a manifest file that contains information about various resources (URL, Storage, Services, etc.) that correspond to your component, and will be created on the Kubernetes cluster when you execute `odo push` command. Most odo commands will first modify (add or remove configuration from) this file, and then subsequent `odo push` will create or delete the resources from the Kubernetes cluster. However, odo users are not expected to know how the `devfile.yaml` is organized; it is the odo commands that would create, update, or delete it.


It is a manifest file that

I would rather prefer we say Devfile is a manifest file than calling it It.

However, odo users are not expected to know how the devfile.yaml is organized; it is the odo commands that would create, update, or delete it.

What do you think about highlighting this line in a separate para perhaps or just highlighting it here? It would sort of take away the pressure of learning a new thing i.e. Devfile.

Makes sense. Done both.

valaparthvi · 2021-08-11T06:28:58Z

One more thing; I think you forgot to mention that a single directory can contain only one component.

dharmit · 2021-08-11T06:53:55Z

One more thing; I think you forgot to mention that a single directory can contain only one component.

I forgot. But I'm not sure if adding that info in this doc makes sense. I'm more inclined to put it in odo component command reference doc.

Anyhow, I have added it in 6a4e77e. PTAL.

@kadel PTAL. Let me know if you folks would like to word it differently.

valaparthvi · 2021-08-11T07:14:02Z

The doc lgtm to me for now, I don't see any immediate change we need to make to it.

dharmit · 2021-08-11T07:20:34Z

Nesting odo components is not expected to work well.

When you say this, it gives an impression that managing nested components is possible with odo, which is not the possible, is it?

Why does it seem that way? I have mentioned that it is "not" expected to work well. I can change it to "not supported" instead of
"not expected to work well" if that helps. But I'm confused why it sounds exactly opposite of what I have written there.

kadel · 2021-08-11T07:33:16Z

This lookgs good, but I think that there is one important piece missing. "How to access the application".
There is a lot of details about how to create a component, but not how to access it after running odo push.

dharmit · 2021-08-11T08:45:30Z

This lookgs good, but I think that there is one important piece missing. "How to access the application".
There is a lot of details about how to create a component, but not how to access it after running odo push.

That will be put up in doc for URL. At the moment, we have kept doc for env vars after the component creation doc. But I think it makes more sense to write doc for creating and accessing URL.

sonarqubecloud · 2021-08-11T08:51:08Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

kadel · 2021-08-11T11:13:43Z

/approve
/lgtm

openshift-ci · 2021-08-11T11:14:08Z

[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:

~~OWNERS~~ [kadel]

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

Documents steps for component creation

e15c6c3

openshift-ci bot added the kind/documentation label Aug 10, 2021

openshift-ci bot requested review from prietyc123 and rnapoles-rh August 10, 2021 13:56

Update Changelog

991227d

Adds OWNERS files

fedae92

This is to ensure relevant folks are pinged for reviews.

kadel reviewed Aug 10, 2021

View reviewed changes

website/docs/using-odo/create-component.md Outdated Show resolved Hide resolved

kadel reviewed Aug 10, 2021

View reviewed changes

website/docs/command-reference/catalog.md Outdated Show resolved Hide resolved

dharmit and others added 2 commits August 11, 2021 10:28

Update website/docs/using-odo/create-component.md

fb4d3a3

Co-authored-by: Tomas Kral <[email protected]>

Changes based on PR feedback

6e4e994

valaparthvi suggested changes Aug 11, 2021

View reviewed changes

openshift-ci bot assigned valaparthvi Aug 11, 2021

valaparthvi reviewed Aug 11, 2021

View reviewed changes

dharmit added 2 commits August 11, 2021 12:12

Changes based on Parthvi's feedback

dfa314d

Single directory, single component

6a4e77e

valaparthvi approved these changes Aug 11, 2021

View reviewed changes

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. Required by Prow. label Aug 11, 2021

Removes an absolutely unrelated change from the PR

1f0ac44

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. Required by Prow. label Aug 11, 2021

openshift-ci bot assigned kadel Aug 11, 2021

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. Required by Prow. label Aug 11, 2021

openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. Required by Prow. label Aug 11, 2021

openshift-ci bot merged commit 7d206a9 into redhat-developer:main Aug 11, 2021

dharmit mentioned this pull request Aug 12, 2021

Add tutorials under "Using odo" section to docusaurus based site #4895

Closed

18 tasks

dharmit deleted the 4895-create-component branch April 18, 2022 08:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documents steps for component creation #4982

Documents steps for component creation #4982

dharmit commented Aug 10, 2021

netlify bot commented Aug 10, 2021

netlify bot commented Aug 10, 2021 •

edited

Loading

kadel Aug 10, 2021

dharmit Aug 11, 2021

kadel Aug 11, 2021

dharmit Aug 11, 2021

kadel Aug 10, 2021

dharmit Aug 11, 2021

valaparthvi left a comment

valaparthvi Aug 11, 2021

dharmit Aug 11, 2021

valaparthvi Aug 11, 2021

dharmit Aug 11, 2021

valaparthvi Aug 11, 2021

dharmit Aug 11, 2021

valaparthvi Aug 11, 2021

dharmit Aug 11, 2021

valaparthvi Aug 11, 2021

valaparthvi Aug 11, 2021

dharmit Aug 11, 2021

valaparthvi commented Aug 11, 2021

dharmit commented Aug 11, 2021

valaparthvi commented Aug 11, 2021

dharmit commented Aug 11, 2021

kadel commented Aug 11, 2021

dharmit commented Aug 11, 2021

sonarqubecloud bot commented Aug 11, 2021

kadel commented Aug 11, 2021

openshift-ci bot commented Aug 11, 2021

		Among the various ways described above, irrespective of how you created the component, the next step to create the resources for our component on the cluster would be to run `odo push`

		Note that first run of `odo push` could take a long time for the Spring Boot petclinic project. This is because of the dependencies being pulled by Spring Boot framework. Subsequent `odo push` runs shouldn't take longer when working on the same Kubernetes cluster.

		## Push the component to Kubernetes

		odo follows a "create & push" workflow for almost all the commands. Meaning, most odo commands won't create resources on Kubernetes cluster unless you run `odo push` command.

		[Component](../getting-started/basics#component) is the most basic unit of operation for odo. And the way to create one is using `odo create` (short for `odo component create`) command.

		In simplest terms, when you "create" an odo component, you populate your current working directory with the file `devfile.yaml`. It is a manifest file that contains information about various resources (URL, Storage, Services, etc.) that correspond to your component, and will be created on the Kubernetes cluster when you execute `odo push` command. Most odo commands will first modify (add or remove configuration from) this file, and then subsequent `odo push` will create or delete the resources from the Kubernetes cluster. However, odo users are not expected to know how the `devfile.yaml` is organized; it is the odo commands that would create, update, or delete it.

Documents steps for component creation #4982

Documents steps for component creation #4982

Conversation

dharmit commented Aug 10, 2021

netlify bot commented Aug 10, 2021

netlify bot commented Aug 10, 2021 • edited Loading

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

valaparthvi 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

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

valaparthvi commented Aug 11, 2021

dharmit commented Aug 11, 2021

valaparthvi commented Aug 11, 2021

dharmit commented Aug 11, 2021

kadel commented Aug 11, 2021

dharmit commented Aug 11, 2021

sonarqubecloud bot commented Aug 11, 2021

kadel commented Aug 11, 2021

openshift-ci bot commented Aug 11, 2021

netlify bot commented Aug 10, 2021 •

edited

Loading