-
Notifications
You must be signed in to change notification settings - Fork 244
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Cluster Setup documentation #4973
Add Cluster Setup documentation #4973
Conversation
✔️ Deploy Preview for odo-docusaurus-preview ready! 🔨 Explore the source changes: 80cc7e6 🔍 Inspect the deploy log: https://app.netlify.com/sites/odo-docusaurus-preview/deploys/611f8a1bdf00a30007d2de03 😎 Browse the preview: https://deploy-preview-4973--odo-docusaurus-preview.netlify.app |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some changes based on a quick look.
|
||
## Install the OLM | ||
The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This doesn't help make things clear for someone who is new to Kubernetes or doesn't want to get deep into Kubernetes. We got to try to make things simpler for users who have barely used Kubernetes.
The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) | |
As the name suggests, Operator Lifecycle Manager (or OLM) manages the lifecycle of Operators. So what are Operators? In simplest terms, Operators are a collection of definitions used to spin up services like databases, message queues, etc. odo uses these definitions to spin up services but cannot help install them. It's something that requires administrator privileges and throughout this guide we assume that you have those privileges since you have setup a minikube environment. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't we put this in the Operator doc?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes we should. But at the moment, we are adding this doc. So we should put it here. If operator doc was ready, we could have linked to it. Once we have it ready, we could replace this paragraph with a link to it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rather than coming up with our own definition of what Operator is we should link to existing Kubernetes documentation
https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can and should surely link to k8s docs whenever it makes sense. But we should also make things simpler to understand for users who don't want/need to know things from k8s perspective.
Having said that, in this case, the Motivatoin
section of the doc is pretty good and can be used to explain Operators instead of using what I suggested.
But overall, I hope that odo docs attempt to make k8s things simpler to understand for users. If that means coming up with our own definitions, so be it. Code should not be the only place where odo follows the philosophy of making k8s abstractions simple for users.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Code should not be the only place where odo follows the philosophy of making k8s abstractions simple for users.
agreed
If that means coming up with our own definitions,
That is dangerous. We should not come up with our own definitions for stuff that we did no created. We should no try to redefine things.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not use already existing definition from https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ or https://www.redhat.com/en/topics/containers/what-is-a-kubernetes-operator ? Do you think that those are too technical?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That is dangerous.
The other way of looking at it is trying to do ELI5. Instead of really trying to do ELI5, we should try to explain things as if our readers have no knowledge of k8s.
Why not use already existing definition from https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ or https://www.redhat.com/en/topics/containers/what-is-a-kubernetes-operator ? Do you think that those are too technical?
I already said in my previous comment (#4973 (comment)) that in this case, reusing what's in the "Motivation" section makes sense because it's written in really simple language.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will add the excerpt of Motivation from the official k8s doc, it's short and simple as compared to the RH article.
@valaparthvi Update Changelog.md |
@dharmit Can we get this one in first? Build for #4934 is broken atm because we removed some of the pages it is referring to, mainly cluster-setup pages. If this one gets in, 4934 will no longer break. I am not happy with the current position of operator definition for OpenShift, but I couldn't think of any other place to put it, so suggestions are welcome. |
Kudos, SonarCloud Quality Gate passed! 0 Bugs No Coverage information |
/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 |
What type of PR is this?
/kind documentation
What does this PR do / why we need it:
This PR adds the documentation for cluster setup.
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: