Add Getting Started > Basics documentation #4914
Conversation
openshift-ci
bot
requested review from
mik-dass and
prietyc123
and removed request for
feloy
| @@ -8,15 +8,34 @@ odo abstracts Kubernetes concepts into developer focussed terminology. In this d | |||
|
|
|||
| ### Concepts | |||
|
|
|||
| #### Component | |||
| * Component | |||
| A component is a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend | |||
There was a problem hiding this comment.
This doesn't render well. Maybe you need to add one more newline. Also, make the keywords bold, maybe? So something like:
Component
A component is a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend
This applies to all other places in the doc as well.
There was a problem hiding this comment.
Yeah, my bad, I was too focused on the quoted part. I'll fix that.
| @@ -8,15 +8,34 @@ odo abstracts Kubernetes concepts into developer focussed terminology. In this d | |||
|
|
|||
| ### Concepts | |||
|
|
|||
| #### Component | |||
| * Component | |||
| A component is a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend | |||
There was a problem hiding this comment.
In addition to above:
| A component is a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend | |
| A component is like a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend |
| * Service | ||
| A service is another microservice, or a Kubernetes Custom Resource that your component connects to or depends on. Example of services: MariaDB, MySQL |
There was a problem hiding this comment.
For odo, at the moment, a service is only an Operator backed service. Using the term "microservice" doesn't make sense to me here.
There was a problem hiding this comment.
How would you define an operator-backed service? If I use the term, I will still need to explain what a service is. How do I define a service?
By "microservice" I meant component. Ah, I confused service with link 🤦
There was a problem hiding this comment.
How would you define an operator-backed service? If I use the term, I will still need to explain what a service is. How do I define a service?
A loose definition of service is a long-running daemon (think a server process), and listening for incoming requests based on which it would do certain actions. But we don't need to explain this in our docs. It's a definition that almost everyone relates to when they read the word "service".
When you write "Operator backed service", add a link to the term Operator. Use https://github.com/operator-framework.
| #### Component | ||
| * Component | ||
| A component is a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend | ||
| > A component in odo is an equivalent of a deployment or deploymentconfig in Kubernetes. Creating a new component in odo will create a deployment in Kubernetes or for git and binary based component creation, it will create deploymentconfig. |
There was a problem hiding this comment.
- Why is this quoted with a
>? Same question for everywhere else in the doc. - IMO, odo component is not an equivalent of Deployment or DeploymentConfig. By default, odo creates a bunch of Kubernetes resources for a component:
- Deployment (which creates a ReplicaSet and Pods)
- Service (a Kubernetes Service; not odo service)
- Storage (emptyDir or PVC depending on user's preference setting)
- probably more that I might have missed.
- We don't need to go into this level of detail for git/binary components. Also, it doesn't create just DC but other things that I mentioned above.
There was a problem hiding this comment.
I understand that the quoted part explain how the concepts are implemented in Kubernetes.
But it is probably not a good place to talk about these implementations. This concept page should help the reader make a mental representation of the objects handled by odo, without other distraction.
There was a problem hiding this comment.
Why is this quoted with a >? Same question for everywhere else in the doc.
- I figured we would put the Kubernetes part in a quoted text like Philippe has done in his blog.
I can add a note about it in the beginning.
IMO, odo component is not an equivalent of Deployment or DeploymentConfig. By default, odo creates a bunch of Kubernetes resources for a component:
Deployment (which creates a ReplicaSet and Pods)
Service (a Kubernetes Service; not odo service)
Storage (emptyDir or PVC depending on user's preference setting)
probably more that I might have missed.
- Okay, I can change that.
We don't need to go into this level of detail for git/binary components. Also, it doesn't create just DC but other things that I mentioned above.
- Noted.
There was a problem hiding this comment.
But it is probably not a good place to talk about these implementations. This concept page should help the reader make a mental representation of the objects handled by odo, without other distraction.
Okay okay. I will remove the quoted texts. @feloy, let me know if you have something specific in mind about formatting this.
There was a problem hiding this comment.
I understand that the quoted part explain how the concepts are implemented in Kubernetes.
But it is probably not a good place to talk about these implementations. This concept page should help the reader make a mental representation of the objects handled by odo, without other distraction.
Okay okay. I will remove the quoted texts. @feloy, let me know if you have something specific in mind about formatting this.
On a second thought, we mention early on in this page that we will be talking about these concepts and their Kubernetes equivalent, so it does make sense to me to put them here.
There was a problem hiding this comment.
I figured we would put the Kubernetes part in a quoted text like Philippe has done in his blog.
I can add a note about it in the beginning.
We don't want to introduce k8s lingo here.
On a second thought, we mention early on in this page that we will be talking about these concepts and their Kubernetes equivalent, so it does make sense to me to put them here.
My bad. We should not talk about k8s equivalents in this doc. Can you remove that statement as well?
There was a problem hiding this comment.
Okay. Where else do we mention it then? This seemed like the right place to me to explain about the K8s equivalent of these concepts.
There was a problem hiding this comment.
We could limit talking about Kubernetes in the Command Reference and Architecture pages
There was a problem hiding this comment.
But I do think that talking about the K8s equivalent here will help get a better understanding of odo in general. We do not need to talk about the deep implementation level details, just the high-level ones to make a relation between odo terminology and K8s terminology.
I understand that it might defeat the purpose of abstracting K8s out of the docs, but if I was reading this doc as odo user, having this relation would help me better understand the docs. Or I guess we can make a better effort at making these concepts better understandable.
There was a problem hiding this comment.
I understand that it might defeat the purpose of abstracting K8s out of the docs,
This is why we don't want to introduce k8s lingo so early.
but if I was reading this doc as odo user, having this relation would help me better understand the docs
We do not want application developers (our target audience) to deal with k8s lingo. It's for application architects and whoever already has knowledge of k8s. Majority of odo users are not expected to have knowledge of k8s.
Or I guess we can make a better effort at making these concepts better understandable.
And that we'll be doing in Command Reference and Architecture sections. Maybe at some places in tutorials where it really makes sense. But Getting Started is definitely not the place to introduce k8s lingo.
| * Application | ||
| An application consists of multiple components which may span over multiple projects, and work individually to build the entire application. Examples of applications: e-Shop, Hotel Reservation System, Online Booking |
There was a problem hiding this comment.
An application consists of multiple components which may span over multiple projects
This is not true for odo. odo doesn't cover things across multiple namespaces.
There was a problem hiding this comment.
I meant that an application can be accessed over multiple namespaces. But I see how it might have come off to mean that a user can access the same component over multiple namespaces, is that what you meant?
Anyway, I'll try to fix that.
There was a problem hiding this comment.
What I understood is that the components can be distributed over different namespaces. Which is not true for odo. At least not yet.
| * URL | ||
| A URL exposes your component to be accessed outside the cluster. | ||
| > A URL is an equivalent of a service in Kubernetes. |
There was a problem hiding this comment.
NO! It's not an equivalent of a Service in k8s! It's equivalent to Ingresses in k8s and Routes in OCP.
There was a problem hiding this comment.
😬 Okay. Changing that.
There was a problem hiding this comment.
The OCP part was just for my fyi, right? Do we want to mention it in the docs?
There was a problem hiding this comment.
Yeah. Even the Ingress thing was for reference. We need to explain URL without talking about Ingresses or Routes.
| * Storage | ||
| A storage volume is [PVC](https://kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) which is a way for you to "claim" persistent storage without knowing the details of the environment. Storage volume can persist data across restarts and rebuilds of a component. |
There was a problem hiding this comment.
Using k8s terminology to explain odo concept is not a good idea. It just means we fail to explain (or even understand ourselves!) the abstractions we created to make k8s terminology not required for the user.
There was a problem hiding this comment.
Again, picked it up from existing docs, and it seemed to make sense to me, but I get your point.
|
|
||
| ### Component vs. Application | ||
| A component is a microservice, while an application is a group of microservices. To make a microservice belong to an application, all the resources belonging to the microservice are assigned a label. |
There was a problem hiding this comment.
| A component is a microservice, while an application is a group of microservices. To make a microservice belong to an application, all the resources belonging to the microservice are assigned a label. | |
| A component is akin to a microservice, while an application is a group of components. |
To make a microservice belong to an application, all the resources belonging to the microservice are assigned a label.
Removed this as it is more about how it's done under the hood, and we don't need to expose the implementation detail to the user/reader.
There was a problem hiding this comment.
@dharmit Do we need this section? I think that we covered the differences in the concepts section and I cannot think of anything new to put in the component vs application section.
| ### odo services vs. Kubernetes services | ||
| odo service helps in connecting one microservice to another, while a Kubernetes service helps in making a microservice accessible outside the cluster. |
There was a problem hiding this comment.
NO! It's the link that helps in connecting stuff.
odo service is a service created from an Operator. k8s service definition looks good.
There was a problem hiding this comment.
A kubernetes service is mainly an abstraction that serves to expose a set of Pods in a stable way (the service will keep the same IP during its life, when Pods can be scaled and restarted, each instance having a new and separate IP).
Services can expose the microservice at different levels depending on its type:
- clusterIP type on the cluster for inter-microservices communication,
- node type to access from outside the Kubernetes cluster through the nodes
- loadBalancerType to access from outside the provider cluster, through some load balancer
There was a problem hiding this comment.
😬
How would you define an operator-backed service? If I use the term, I will still need to explain what a service is. How do I define a service?
Quoting the same comment as here #4914 (comment)
There was a problem hiding this comment.
A service in the odo sense is some external application that the user's application can interact with to gain some functionalities.
This wikipedia page can help find more inspiration: https://en.wikipedia.org/wiki/Service-oriented_architecture
There was a problem hiding this comment.
We can get rid of the "odo service vs. k8s service" from this page as long as we explain odo services well. The comparison can be kept for Command Reference section.
| ### odo services vs. Kubernetes services | ||
| odo service helps in connecting one microservice to another, while a Kubernetes service helps in making a microservice accessible outside the cluster. | ||
| Creating an odo service will create a set of resources to establish a successful connection between the two microservices. |
There was a problem hiding this comment.
This is totally wrong. It's a link that helps setup connectivity between microservices. We don't need to have this under odo service vs k8s service.
There was a problem hiding this comment.
This is totally wrong. It's a link that helps setup connectivity between microservices
Right, my bad. I mixed up service with a link while writing this.
| @@ -4,19 +4,51 @@ sidebar_position: 3 | |||
| --- | |||
| # odo concepts | |||
|
|
|||
| odo abstracts Kubernetes concepts into developer focussed terminology. In this document, we will take a look at each of these concepts and also their Kubernetes equivalent. | |||
| odo abstracts Kubernetes concepts into a developer focused terminology. In this document, we will take a look at each of these concepts. | |||
There was a problem hiding this comment.
In the first sentence we refer to "Kubernetes concepts". So, in the second statement when we say "we will take a look at these concepts", wouldn't it seem like we're talking about Kubernetes concepts?
| odo abstracts Kubernetes concepts into a developer focused terminology. In this document, we will take a look at each of these concepts. | |
| odo abstracts Kubernetes concepts into a developer friendly terminology. In this document, we will take a look at the terminolgy used by odo. |
| * Storage | ||
| * Service | ||
| * Devfile | ||
| * **Component** |
There was a problem hiding this comment.
OK this is going to sound frustrating. Instead of using bullet points, can we use H4 (####)? Now that I look at the doc without the quoted text, I think it makes more sense than using bullets.
| * **Component** | |
| #### Component |
| * Devfile | ||
| * **Component** | ||
|
|
||
| A component is like a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend |
There was a problem hiding this comment.
I'm suggesting to remove "deploy" since it'll be more relevant when we have odo deploy.
| A component is like a microservice. Each component can be run and deployed separately. Examples of components: Warehouse API Backend, Inventory API, Web Frontend, Payment Backend | |
| A component is like a microservice. Each component can be run separately. Component is at the core of numerous features provided by odo. Examples of components: backend, frontend, message queue, etc. |
| ### Component vs. Application | ||
| * **Application** | ||
|
|
||
| An application is a group of one or more components that work individually to build the entire application. Examples of applications: Online Video Streaming, Hotel Reservation System, Online Booking |
There was a problem hiding this comment.
I'm not sure about using examples like "Online Video Streaming", "Hotel Reservation", etc. on the odo website. Maybe it's just me, but it feels like reading a boring textbook from school/college.
| An application is a group of one or more components that work individually to build the entire application. Examples of applications: Online Video Streaming, Hotel Reservation System, Online Booking | |
| An application is a group of components that work individually to build the entire application. In the microservices architecture, it is each individual microservice. Examples of applications: Online Video Streaming, Hotel Reservation System, Online Booking |
| * **Project** | ||
|
|
||
| A project is a separate single unit that provides a scope for names and helps in dividing cluster resources between users. A resource name must be unique within the project but not across multiple projects. |
There was a problem hiding this comment.
Wow! That sounds like a textbook definition. Where did you get that from?
| A project is a separate single unit that provides a scope for names and helps in dividing cluster resources between users. A resource name must be unique within the project but not across multiple projects. | |
| A project helps achieve multi-tenancy. Resource names must be unique within the project but not across multiple projects. |
| * **Storage** | ||
|
|
||
| A storage is a way to claim persistent storage in the cluster. A storage can persist data across restarts and rebuilds of a component. |
There was a problem hiding this comment.
| A storage is a way to claim persistent storage in the cluster. A storage can persist data across restarts and rebuilds of a component. | |
| A storage is persistent storage in the cluster. It helps persist data across restarts and rebuilds of a component. |
| * **Service** | ||
|
|
||
| A service is an external application that a component can connect to or depend on to gain some functionality. Example of services: MySQL, Redis |
There was a problem hiding this comment.
| A service is an external application that a component can connect to or depend on to gain some functionality. Example of services: MySQL, Redis | |
| A service is an external application that a component can connect to or depend on to gain some functionality. Example of services: MySQL, Redis. |
|
|
||
| ### odo services vs. Kubernetes services | ||
| Service in terms of odo is an external application that provides an additional functionality, odo service can only be created with [Operators](https://operatorframework.io/what/). |
There was a problem hiding this comment.
| Service in terms of odo is an external application that provides an additional functionality, odo service can only be created with [Operators](https://operatorframework.io/what/). | |
| Service, in terms of odo, is an external application that provides some extra functionality. odo services can only be created with [Operators](https://operatorframework.io/what/). |
| Service in terms of odo is an external application that provides an additional functionality, odo service can only be created with [Operators](https://operatorframework.io/what/). | ||
|
|
||
| Service in terms of Kubernetes is an abstract way of exposing a microservice as a set of pods. Learn more about [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/). |
There was a problem hiding this comment.
| Service in terms of Kubernetes is an abstract way of exposing a microservice as a set of pods. Learn more about [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/). | |
| Service, in terms of Kubernetes, is an abstract way of exposing a microservice. Learn more about [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/). |
| Service in terms of Kubernetes is an abstract way of exposing a microservice as a set of pods. Learn more about [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/). | ||
|
|
||
| Deploying a service created with odo will create a set of resources in the Kubernetes cluster to establish a successful connection between the odo component and the external application. |
There was a problem hiding this comment.
I strongly feel like we should have this differentiation in the Command Reference section where we talk about odo service commands.
Without creating a link, the below statement is incorrect:
establish a successful connection between the odo component and the external application.
| Deploying a service created with odo will create a set of resources in the Kubernetes cluster to establish a successful connection between the odo component and the external application. | |
| Deploying a service created with odo will create a set of resources in the Kubernetes cluster which can then be used from within an odo component after performing link operation. |
|
@dharmit I have removed the I agree with your point about the examples being boring(they reminded me of textbooks too 😬), but I am having a little difficult time coming up with cool examples, let me know if you have some on your mind. |
openshift-ci
bot
added
the
lgtm
|
@feloy leaving |
| * Storage | ||
| * Service | ||
| * Devfile | ||
| In the cloud-native architecture, an application is a collection of small, independent, and loosely coupled components; and an odo component is one of these components. |
There was a problem hiding this comment.
| In the cloud-native architecture, an application is a collection of small, independent, and loosely coupled components; and an odo component is one of these components. | |
| In the cloud-native architecture, an application is a collection of small, independent, and loosely coupled components; an odo component is one of these components. |
| #### Project | ||
| A project helps achieve multi-tenancy: several applications can be run in the same cluster by different teams. |
There was a problem hiding this comment.
| A project helps achieve multi-tenancy: several applications can be run in the same cluster by different teams. | |
| A project helps achieve multi-tenancy: several applications can be run in the same cluster by different teams in different projects. |
|
|
||
| #### URL | ||
| A URL exposes a component to be accessed outside the cluster. |
There was a problem hiding this comment.
| A URL exposes a component to be accessed outside the cluster. | |
| A URL exposes a component to be accessed from outside the cluster. |
|
|
||
| #### Storage | ||
| A storage is persistent storage in the cluster: it persists the data across restarts and rebuilds of a component. |
There was a problem hiding this comment.
| A storage is persistent storage in the cluster: it persists the data across restarts and rebuilds of a component. | |
| A storage is a persistent storage in the cluster: it persists the data across restarts and rebuilds of a component. |
openshift-ci
bot
removed
the
lgtm
|
SonarCloud Quality Gate failed.
|
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: feloy 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
bot
added
the
approved
|
/lgtm |
openshift-ci
bot
added
the
lgtm
* Add Getting Started > Basics documentation * Better structure the doc * Changes * Fix content * Remove K8s content * Simplify the doc * Cosmetic changes * Fix grammar
What type of PR is this?
/kind documentation
What does this PR do / why we need it:
This PR adds content to Getting Started > Basics.
Note: Some of the content might not be true and will need a lot of refining.
Which issue(s) this PR fixes:
Fixes part of #4894
PR acceptance criteria:
Unit test
Integration test
Documentation
Update changelog
I have read the test guidelines
How to test changes / Special notes to the reviewer: