Charlotte-Holt commented 4 years ago

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

We need to determine if there's a better way to display kubernetes.yaml and pom.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.

Charlotte-Holt commented 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.

Charlotte-Holt commented 4 years ago

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

Charlotte-Holt commented 4 years ago

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.

Charlotte-Holt commented 4 years ago

@lauracowen My initial draft of this topic is ready for your review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#deploying-openshift.html.

lauracowen commented 4 years ago

could just say "applications" rather than "microservice applications" re conversation about terminology the other day and it doesn't have to be microservice architecture.
I wonder whether the shortdesc should also have a third sentence stating that there's an Open Liberty operator to make it easy to xxxx? Flags up early on that it's all there.
Not sure if it's "any cloud platform" so much as any cloud platform that runs OpenShift (Red Hat have got partnerships with AWS and Azure so they do run them). Maybe just don't say "any".
Maybe switch sentences around a bit in the Operator section so that it starts with "Operators are..." then "The OL Operator is/provides..." then give a little background on operators more generally, if that works.
Maybe needs a bit more info about the value of using the operator? Maybe just examples of what it can be used to do?

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.

NottyCode commented 4 years ago

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.

lauracowen commented 4 years ago

I think, based on what Alasdair said above, remove the "What is OpenShift?" heading and just have the first paragraph of that section "OpenShift is..." as part of the intro. Then remove the second para in that section (starting "OpenShift takes...").
The bit about using SSO could link to the Social Media Login feature which will have example config (or if it seems to much there, a separate topic maybe?). #1118 contains the info about that but I'm not sure where it's been put as I can't see it in the draft Social Media Login feature doc.
Aside from Alasdair's question about whether the OL Operator works on K8s, could just remove the sentence "Kubernetes Operators use the Operator framework and can be used on Kubernetes or OpenShift." and just start from "The Open Liberty Operator is available...".
If the OL Operator can't be used with Kubernetes, maybe remove the "See also" link to the K8s guide as that's then not relevant to deploying to 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?

NottyCode commented 4 years ago

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.

Charlotte-Holt commented 4 years ago

Laura's feedback:

I think, based on what Alasdair said above, remove the "What is OpenShift?" heading and just have the first paragraph of that section "OpenShift is..." as part of the intro. Then remove the second para in that section (starting "OpenShift takes..."). DONE
The bit about using SSO could link to the Social Media Login feature which will have example config (or if it seems to much there, a separate topic maybe?). #1118 contains the info about that but I'm not sure where it's been put as I can't see it in the draft Social Media Login feature doc. DONE
Aside from Alasdair's question about whether the OL Operator works on K8s, could just remove the sentence "Kubernetes Operators use the Operator framework and can be used on Kubernetes or OpenShift." and just start from "The Open Liberty Operator is available...". I didn't remove it completely, but I did change up the wording. Let me know what you think. I also confirmed with @arthurdm that the OL Operator can be used with Kubernetes. He said, "yup, it works in regular Kubernetes as well. We have finished the work to support regular Ingress".
And yep! There's an issue that I'm working on to pull in the Operator docs.

Alasdair's feedback:

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. DONE
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. DONE
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. DONE (I think sufficiently)

@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?

lauracowen commented 4 years ago

Yep, looks good. Signing off.

NottyCode commented 4 years ago

looks good to me. Signing off.

dmuelle commented 4 years ago

Peer review

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.

Charlotte-Holt commented 4 years ago

@chirp1 Topic at https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/deployment-openshift.html.

chirp1 commented 4 years ago

Hi Charlotte, Nice job! Here are my comments:

I'm finding issues that could be resolved by following the peer review cheat sheet. Review the peer review cheat sheet and make corrections as appropriate:
https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W93fb765ee31c_4aa7_98f6_a02c0f1a2ebf/page/Peer%20review%20cheat%20sheet For example, fix any possessives.
Do not put a link in the opening paragraph. The paragraph is meant to stand on its own.
Rewrite the opening paragraph and make it two sentences as described in the short description guidelines.
Spell out ops.
For the "One of the benefits of running...." paragraph, the sentences seem to be switching between application/applications when I believe one or the other should be used in this paragraph. Change application/applications as appropriate.
Spell out IaaS on first occurrence. The sentence structure/grammar seems to be a little off. When I spell out IaaS, the sentence sounds a bit odd. Make corrections as necessary.
For "For a step-by-step tutorial on deploying to OpenShift ...", specify what is being deployed.
For "Level 5 Operator", "Level" doesn't seem to be the word used in other literature on the subject. Review the peer review cheet sheet as necessary. Find and use the correct word.
For "... of enterprise capabilities.", give some examples of the enterprise capabilities.
If "Then, the Operator updates the application on a rolling basis." an example of how the operator manages application deployments or the only way? Reword to explain which it is.
Update "See also" with the new wording.

Charlotte-Holt commented 4 years ago

[x] I'm finding issues that could be resolved by following the peer review cheat sheet. Review the peer review cheat sheet and make corrections as appropriate: https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W93fb765ee31c_4aa7_98f6_a02c0f1a2ebf/page/Peer%20review%20cheat%20sheet For example, fix any possessives.
[x] Do not put a link in the opening paragraph. The paragraph is meant to stand on its own.
[x] Rewrite the opening paragraph and make it two sentences as described in the short description guidelines.
[x] Spell out ops.
[x] For the "One of the benefits of running...." paragraph, the sentences seem to be switching between application/applications when I believe one or the other should be used in this paragraph. Change application/applications as appropriate.
[x] Spell out IaaS on first occurrence. The sentence structure/grammar seems to be a little off. When I spell out IaaS, the sentence sounds a bit odd. Make corrections as necessary.
[x] For "For a step-by-step tutorial on deploying to OpenShift ...", specify what is being deployed.
[x] For "Level 5 Operator", "Level" doesn't seem to be the word used in other literature on the subject. Review the peer review cheet sheet as necessary. Find and use the correct word.
[x] For "... of enterprise capabilities.", give some examples of the enterprise capabilities.
[x] If "Then, the Operator updates the application on a rolling basis." an example of how the operator manages application deployments or the only way? Reword to explain which it is.
[x] Update "See also" with the new wording.

@chirp1 Thanks for the review! I've made the requested updates. Let me know if further updates are necessary.

chirp1 commented 4 years ago

Hi Charlotte, Almost there! I have a few more comments.

Work Open Liberty Operator into the opening paragraph since it is a main discussion point in your topic.
For ",,,,including auto-scaling, service binding, and exposing metrics to Prometheus.", I don't think these are all level 5 capabilities, but the sentence seems to imply that they are. Rework to make them all level 5 capabilities. For the non-level 5 capabilities, remove them or discuss them elsewhere.
For "For more information about different OpenShift....", this sentence/link doesn't seem to belong in the topic as it is too broad, and discusses little in relation to IBM Cloud/Open Liberty Operator.
"For more information about Operators, see the Kubernetes documentation." seems a little misplaced. To me, something like "Operators are extensions to Kubernetes" seems like better text for the link.

Charlotte-Holt commented 4 years ago

@chirp1 I made the following updates:

[x] Work Open Liberty Operator into the opening paragraph since it is a main discussion point in your topic.
[x] For ",,,,including auto-scaling, service binding, and exposing metrics to Prometheus.", I don't think these are all level 5 capabilities, but the sentence seems to imply that they are. Rework to make them all level 5 capabilities. For the non-level 5 capabilities, remove them or discuss them elsewhere.
[x] For "For more information about different OpenShift....", this sentence/link doesn't seem to belong in the topic as it is too broad, and discusses little in relation to IBM Cloud/Open Liberty Operator.
[x] "For more information about Operators, see the Kubernetes documentation." seems a little misplaced. To me, something like "Operators are extensions to Kubernetes" seems like better text for the link.

I'm going to ping you so we can talk through the "For more information about different OpenShift...." sentence. Thx!!

chirp1 commented 4 years ago

Hi! I have a few more comments:

The first sentence uses "application" and the second "applications". Let's make them consistent and use "applications in the first sentence.
How about if for " single-sign on (SSO) to external providers." you link to https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/single-sign-on.html instead of https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/reference/feature/socialLogin-1.0.html ?
I think that for the following sentences different wording could be linked as the current links don't catch my eye as to their purpose: "You can install the Open Liberty Operator from OperatorHub for use on Kubernetes or OpenShift. The Operator is also available as a Red Hat-certified Operator from OpenShift Container Platform (OCP)." Whenever you write, use the style guide. So, for linking, see https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch10.html#ch10lev1sec3

Charlotte-Holt commented 4 years ago

@chirp1 Thx! Changes are in https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/deployment-openshift.html.

[x] The first sentence uses "application" and the second "applications". Let's make them consistent and use "applications in the first sentence.
[x] How about if for " single-sign on (SSO) to external providers." you link to https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/single-sign-on.html instead of https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/reference/feature/socialLogin-1.0.html ?
[x] I think that for the following sentences different wording could be linked as the current links don't catch my eye as to their purpose: "You can install the Open Liberty Operator from OperatorHub for use on Kubernetes or OpenShift. The Operator is also available as a Red Hat-certified Operator from OpenShift Container Platform (OCP)." Whenever you write, use the style guide. So, for linking, see https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch10.html#ch10lev1sec3

chirp1 commented 4 years ago

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.

Charlotte-Holt commented 4 years ago

@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.

Charlotte-Holt commented 4 years ago

2481

chirp1 commented 4 years ago

The updates look good! Closing.

OpenLiberty / docs

Deploying microservices to OpenShift #766

Peer review

2481