Closed Charlotte-Holt closed 4 years ago
We will no longer be building the guide into RHR docs. Instead, we'll create a new concept topic that covers the key concepts from the OpenShift guide.
Check for any overlap with #648.
Doc for OL operator: Create a doc that describes the Open Liberty Operator for Kubernetes clusters.
Possibly use the following info:
https://github.com/OpenLiberty/open-liberty-operator https://operatorhub.io/operator/open-liberty
Notes from LC: • Original operator was just the Helm chart wrapped as an operator to get check mark but wasn’t really an operator. Helm can’t get beyond the deployment phase, esp Day 2 ops. • Getting dumps or setting trace - devops might send the dump to the developer and developer then debug it, which the dev cares about when debugging what’s going on in production. • There’s an Appsody operator (the OL operator can be a drop-in replacement for the Appsody operator). Very simple migration on purpose. Nothing changes for Jane - she just deals with an OL app instead of an Appsody app. • Appsody Operator is upstream project of the OL Operator. Though might rename the Appsody one to avoid confusion (because the OL Operator can be used with OL apps that are not Appsody apps). The project relationship is entirely internal detail - no one needs to care about this. • OL is part of RHR. So having this OL operator is part of RHR. • RHR is part of ICP4Apps but also lives on its own. • As-is: currently have Appsody very integrated with all aspects of app lifecycle. Those get processed by Appsody CLI during deploy command. This is what the Tekton pipeline applies into OpenShift. QoS is as for our runtimes but doesn’t have Liberty-specific stuff (eg configuring Liberty’s ODIC client or Liberty’s Day 2 stuff - Day 2 ops [JVM dump and setting trace] are specific to OL). • JBoss has their own operator. If you were deploying an EAP app, they’d want you to use the JBoss operator. So similarly, if you’re deploying an OL app, you use the OL Operator. • Both Appsody and OL operators are in the OperatorHub. If you’re deploying OL app, use the OL operator. For anything else, you use Appsody operator (OL operator has everything appsody operator has). Jane doesn’t see any difference - she just continues to use the CLI. • Only difference is that the OL operator has the Day 2 operations that weren’t available in the Appsody operator (for using with OL). • There’s no one operator for everyone in the world - operators will be chosen by preference, the things they do, what’s popular in the community. Application stacks will have their own operator, JBoss does - so we’ll hit this soon. Operator doc thoughts: • What are operators and what the Open Liberty operator does (deployment but also ‘day 2’ stuff like JVM dump and setting trace). • Aimed at devops - so Scenario 2 - deployment and production lifecycle. • In the video, Arthur is showing the design doc which talks about as-is and to-be. I think the to-be is basically what it is that needs to be doc’d. • We don’t need to talk about it being a drop-in for Appsody Operator. Ditto how to decide which to use - that’s an Appsody/ICP4Apps question. Don’t know who will talk about that (maybe whatever docs there are about Appsody Operator). • Certified as Red Hat Operator so you can find it in the OperatorHub - eg if you’re coming to it from the RHR perspective. • https://www.openshift.com/learn/topics/operators and the ebook linked from that page, for background/education.
@lauracowen My initial draft of this topic is ready for your review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#deploying-openshift.html.
Not sure what else to suggest, if anything. See what @NottyCode or @gcharters thinks, in case there is anything else they'd like to get across in this.
Can we just say OpenShift?
Instead of this:
After you write your applications, you can containerize and deploy them to OpenShift to orchestrate and automate your containers.
What about this:
After you write your application you can use OpenShift to build, containerize and deploy your application to be highly available and scalable.
This implies to me you have to write an operator, but you don't it is provided by us:
You can also implement the Open Liberty Operator to simplify the process of deploying and managing your applications in the cloud.
Perhaps just say "you can use the Open Liberty Operator". Can we link to any docs about it?
This isn't quite right:
OpenShift is an open source application platform that is based on Kubernetes.
OpenShift is a Red Hat product which is based on open source technologies such as Origin Kubernetes Distribution (OKD). This might be a minor thing, but I think we should be careful here since we don't own the product. What about this:
OpenShift is a kubernetes based application platform
I'm not sure about the must in the following sentence. I'm not sure what the intent is, but it sounds like you are giving me an order.
After you develop and containerize your applications, your containers must be able to communicate with each other and scale as each service is needed.
I think it is less direct than this. I think that they take OKD into OpenShift and I'm not sure the OKD -> Kube relationship. I'm not sure we should be defining what OpenShift is, we should be able to link to Red Hat's definition, or just copy it from them:
OpenShift is a distribution of Kubernetes that takes the upstream Kubernetes project and adds fixes and helpful tooling.
I think the use of cloud platform isn't right here. I think Red Hat would define OpenShift as a cloud platform, I think what is meant here is effectively a cloud hosted IaaS.
...you can deploy them to a cloud platform, or to your current on-premises structure.
What is the difference between a CLI and a command line tool? To me it is the same thing:
You can use the OpenShift CLI or OpenShift command line tools to develop your application.
I'd say use rather than implement, and we should check with @arthurdm that the operator works in Kube, it was a TODO item and I don't know if it is done:
Kubernetes Operators implement the Operator framework and can be used on Kubernetes or OpenShift.
Otherwise looks good. I don't know what else you'd include here. I think it will work in the RHR docs.
I think you have a separate issue about pulling in Arthur's Operator docs from the other repo?
I agree with Laura that the "What is OpenShift" section seems redundant. It looks like it duplicates much of what is in the first paragraph. The first 7 words in the into paragraph to the article are identical to the first 7 words in the "What is OpenShift" section.
It is probably fine, but it didn't feel right to say the containers need to talk to each other. If you create a container image for an application and then deploy it 12 times those 12 instances don't necessarily (and often wouldn't) communicate with each other, they would need to communicate with other containers running databases, security systems or other microservices, but that isn't how I read it.
I don't think we need to say this:
Kubernetes Operators use the Operator framework...
I would like to see the description of the Open Liberty operator talk about using it to manage high availability and application updates which I think are part of the operator responsibility.
Laura's feedback:
Alasdair's feedback:
@lauracowen @NottyCode Could you have another look over this topic now that I've addressed your feedback: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#deploying-openshift.html?
Yep, looks good. Signing off.
looks good to me. Signing off.
This looks good. Just a few minor questions and suggestions.
should IaaS be spelled out on first mention? I'm not sure.
should The Open Liberty Operator be linked on the first mention? Or are we waiting until there's a OL doc for it?
the ability to delegate single-sign on (SSO) to external providers.
is there a reason this links to Social Media login instead of the SSO topic? Does the Operator use this feature?
With the Open Liberty Operator, applications can be made highly available by configuring...
maybe
With the Open Liberty Operator, you can make applications highly available by configuring...
Then, the Operator performs a rolling update of the application.
could be
Then, the Operator updates the application on a rolling basis.
The Open Liberty Operator can be used on Kubernetes or OpenShift and is available for installation from OperatorHub.
Maybe
You can install the Open Liberty Operator from OperatorHub for use on Kubernetes or OpenShift.
Double check the link to Operator hub. It looks good but it's not resolving for me right now.
Hi Charlotte, Nice job! Here are my comments:
@chirp1 Thanks for the review! I've made the requested updates. Let me know if further updates are necessary.
Hi Charlotte, Almost there! I have a few more comments.
@chirp1 I made the following updates:
I'm going to ping you so we can talk through the "For more information about different OpenShift...." sentence. Thx!!
Hi! I have a few more comments:
@chirp1 Thx! Changes are in https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/deployment-openshift.html.
Hi! The updates for the first and third bullets look good. As we just now discussed about linking to Richard's SSO topic, that one will be live after your topic goes live. So, you'll use the SSO feature link for now and then open a defect to link to Richard's SSO topic when it goes live.
@chirp1 Got it! Updated the link for the second bullet point in https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/reference/feature/socialLogin-1.0.html.
The updates look good! Closing.
(No longer republishing/adapting the guide. See comments.)
Red Hat built the 'Deploying microservices to OpenShift' guide on 10/16/2019. The PDF and HTML versions are attached here:
OpenShift_RHRBuild_10:16:2019.zip
OpenShift_RHRBuild_10:16:2019.pdf
We need to determine if there's a better way to display
kubernetes.yaml
andpom.xml
. Right now, they're included in the middle of the text, and some of them are included multiple times. We could try including them at the end of the guide in some sort of appendix. Then, each reference to one of these files/classes could link down to the appropriate file in the appendix section of the guide. This is assuming that the instances of each file are all the same. Restructuring the guides into this appendix/linking format could be a good starting point for usability testing to determine whether the linking would involve too much movement up and down the page.We also need to fix the pieces of the guide that differentiate which command the user should be used based on their OS (found in the Pushing the images to OpenShift’s internal registry section). In the PDF and HTML versions, these commands are all thrown together on the page in a way that doesn't allow a user to understand which command they should use.
The legal notice needs to be updated too, but that may have already been addressed indirectly when we updated the legal notice for the docs.