openliberty / archived-guide-cloud-openshift Goto Github PK

Publishing Tasks

• Create a PR from dev to master branch
• Create qa branch from master branch
• Rename the guide repo
• Refresh qa staging site and verify
• If qa site has no problem, request to refresh openliberty.io site
• For master branch, add a tag by creating a new release for this repo with name "1st-release"

• "... a built-in Kubernetes cluster on OpenShift; Red Hat’s cloud platform." is not very accurate in the following paragraph:

  You will learn how to deploy two microservices in Open Liberty containers to a built-in Kubernetes cluster on OpenShift; Red Hat’s cloud platform.

  I'd suggest to highlight that OpenShift is basically Kubernetes with some additional tooling and goodies. Once you mention what is OpenShift, then you can refer to it through out the guide. You should be able to find more info about OpenShift from Red Hat's website.

• "...Kubernetes cluster on OpenShift" is also not very accurate. See previous comment.

• "Signing up for an account will automatically provision a single cluster for you to use."
  I am not sure if this is true. My understanding is that OpenShift Online Starter would just give you access to a project to experiment. That doesn't necessarily mean they will provision a dedicated cluster just for one individual. Please correct me if I am wrong.

• I'd suggest to change oc to "OpenShift CLI" here:

  oc: You need the OpenShift command-line ...

• It would be good to include what output people should see when they run oc version in the following section:

  To verify that the OpenShift CLI is installed correctly, run ....

• "Creating a Kubernetes cluster on OpenShift" section needs to be reworded (including title ...) since it is talking about creating a new project in OpenShift and not provisioning a whole new cluster nor creating a Kubernetes cluster on OpenShift.

• Section "Pushing the images to OpenShift’s internal registry": It would be good to mention that OpenShift comes with an internal registry...

• "MAC" -> "Mac OS X" through out the guide. Mac OS X is the correct name of Mac's operating system.

• Formating "The registry address will be displayed after running the oc registry login command..." -> "The registry address will be displayed after running the oc registry login command..."

• "Deploying the microservices" section: "A Kubernetes resource definition is a yaml file that contains a description of all your deployments, services, or any other resources that you want to deploy. ": See the following two links for an overview of K8s objects: Understanding Kubernetes Objects and Resources.

When doing:

$ oc apply -f kubernetes.yaml

I get a warning message:

W0503 15:21:27.438985 116460 shim_kubectl.go:55] Using non-groupfied API resources is deprecated and will be removed in a future release, update apiVersion to "route.openshift.io/v1" for your resource
W0503 15:21:27.439453 116460 shim_kubectl.go:55] Using non-groupfied API resources is deprecated and will be removed in a future release, update apiVersion to "route.openshift.io/v1" for your resource

Suggesting a fix to:

apiVersion: route.openshift.io/v1
kind: Route

(which would also work with kubectl by default)

Easy change if we're still actively updating this guide.

Update the relevant fields and metadata to indicate this guide is for OpenShift 3.x so users can easily choose which guide to use.

• there seems to be a few cut and paste instances of "Kubernetes cluster on OpenShift". To be technically correct, OpenShift is a container orchestration platform that is based on Kubernetes, the Kubernetes cluster does not run on top of OpenShift. Additionally I don't think it's really correct to call it "Red Hat's cloud platform" as it is "Red Hat's container platform", as the intention is that the container platform runs on top of cloud infrastructure. We should change everywhere it says "Kubernetes cluster on Openshift" to just "Openshift container platform".

• The second paragraph perhaps should expand on what is the difference between OpenShift and Kubernetes. We mention "A cloud-based infrastructure" but in this case we are actually deploying to managed OpenShift running on likely AWS. The value proposition of Openshift can be viewed here: https://www.openshift.com/learn/what-is-openshift

• In the Prerequisites section for "OpenShift account", what actually happens beneath the covers is you get access to a managed multi-tenant OpenShift cluster running on AWS. You do not get your own cluster nor do you get access to their public cloud platform, you are given access to create projects and deploy containers to this cluster.

• it might bear mentioning about the expected outputs of oc version, additionally i am not sure of the output before the client is logged in.

• as mentioned in another guide I reviewed, I don't think this is a very realistic scenario that you have a monolithic build that builds two microservices. Microservices should be built and deployed separately as building and deploying services together defeats the purpose of having microservices.

• A little concerning is the security setting on Windows that you advise the user to shut off, where the docker daemon is exposed locally without TLS. I'd rather have maven not build the image than to shut this off. Usually a CI process will be building the docker image separately outside of the developer environment anyway.

• for logging into registry part, can you explain more about "custom credentials store". It's not really clear what this means and whether this applies to me. For example, i'm pretty sure this applies to mac users as docker integrates with the keychain on mac.

• As we are building for openshift, one question I had was why we build the docker images locally rather than use any of the openshift s2i developer tools, DeploymentConfigs, or imagestreams. these are the value propositions of openshift for developers. For example, we could use a BuildConfig to build the docker image in openshift and not require Docker on the local user's desktop at all. This would handle building the image and pushing it to the internal registry, and create an ImageStream resource inside of Openshift for tracking.

What you’ll learn

• Intro cloud paragraph needs to be changed. Refer to this issue to see what needs to be changed: OpenLiberty/guides-common#317

Prerequisites

• Different output for oc version command than the one on the guide

  Client Version: version.Info{Major:"4", Minor:"1+", GitVersion:"v4.1.14", 
  GitCommit:"ed73a65c7", GitTreeState:"clean", BuildDate:"2019-08-27T04:36:57Z", 
  GoVersion:"go1.11.5", Compiler:"gc", Platform:"darwin/amd64"}
  Server Version: version.Info{Major:"1", Minor:"14", GitVersion:"v1.14.3", 
  GitCommit:"5e53fd6bc17c0dec8434817e69b04a25d8ae0ff0", GitTreeState:"clean", 
  BuildDate:"2019-06-06T01:36:19Z", GoVersion:"go1.12.5", Compiler:"gc", 
  Platform:"linux/amd64"}
  

Accessing an OpenShift cluster

• the first > looks weird in the sentence:

  To login to OpenShift using the CLI, navigate to the online web console > [username] > Copy Login Command > Display Token > Log in with this token.

  so change it to this maybe:

  To login to OpenShift using the CLI, open the online web console and then navigate to [username] > Copy Login Command > Display Token > Log in with this token.

Deploying microservices to OpenShift

• "If you’re unfamiliar with Dockerfiles, check out the Using Docker containers to develop microservices guide." should point to the new Containerize docker guide instead

• I don't think we should be using the dockerfile-maven plugin, since all of the cloud guides were changed to not use it anymore

  • Instead, manually build the docker images using the docker build commands
  • remove all mentions of dockerfile-maven in paragraphs

• MAC & LINUX is usually MAC | LINUX in other guides

Making requests to the microservices

• output of registry address is different than the one listed in the guide:

  default-route-openshift-image-registry.apps.us-west-1.starter.openshift-online.com
  

• url for sample hostname is different:
  • original: inventory-route-[project-name].apps.[region].online-starter.openshift.com
  • new: http://inventory-route-nim-project.apps.us-west-1.starter.openshift-online.com

Testing the microservices

• mvn verify not working for inventory endpoint test:

  InventoryEndpointTest.testSuite:72->testHostRegistration:101 The inventory should have one entry for null expected:<1> but was:<0>
  

Other

• This issue needs to be fixed before publishing: #6
  • mvn verify on finish directory fails on SystemEndpointTest instead of InventoryEndpointTest like on start directory

Issues:

• Provided instructions all worked smoothly for me. No issues.

Clarity:

• When applying kubernetes.yaml it could do to emphasize (bold or have it earlier in the paragraph) that you need to swap out [project-name] in the yaml file as at steps like this most will just copy paste and try to move on without reading to the end of the section. Especially for users not familiar with the hotspot feature in these guides.

Misc Suggestions:

• In the section on tagging and pushing images to registry it would save the user some hassle to use docker tag system:1.0-SNAPSHOT `oc registry info`/`oc project -q`/system:1.0-SNAPSHOT and likewise for the docker push command so that they can just copy paste instead of swapping out the brackets.
• The instructions for going to the route in your browser might benefit slightly from also mentioning you can get the hostnames by using oc get routes in the terminal, as it's a little bit faster and consistent across all OpenShift platforms.

• What you’ll learn
  • Look like OpenShift Dedicated is NOT Red Hat’s private cloud platform from https://docs.openshift.com
    • either make sure the description of different OC platforms are correct or ask readers to visit https://docs.openshift.com.
• Creating a Kubernetes cluster on OpenShift
  • should we say how the cluster be created more clear?
    • "To create a Kubernetes cluster, you must sign up ..." or
    • "First, you sign up... A Kubernetes cluster will be created when the account is set up."
  • make sure cluster-id is the right term
    • my url is https://api.us-west-2.online-starter.openshift.com. "us-west-2" like a region name instead of cluster id
• Pushing the images to OpenShift’s internal registry
  • the following command not work in Windows. There may need an OS specific section
    • docker login -u `oc whoami` -p `oc whoami -t` `oc registry info`
• Making requests to the microservices
  • may need to explain what is system-service for the following:
    • "Point your browser to the http://[inventory-hostname]/inventory/systems/system-service URL. "
• Tearing down the environment
  • need an instruction to remove the pushed images on the registry
• There is no need to start/stop the local servers
  • [ ] in the finish/pom.xml and start/pom.xml, add following in the <configuration/> of liberty-maven-plugin
    • <skipTestServer>true</skipTestServer>

Taken from Navid from issue #7. Might want to look into the rationale of why we call it just MAC instead of MAC OSX when we label the other two as their respective OSs LINUX and WINDOWS.

I'm attaching my feedback for this guide in a Word doc. Please feel free to reach out to me with any questions.

OpenShift Guide Comments.docx

After updates have been made, I'll add the ID reviewed label to OpenLiberty/guides-common#189.

Thanks!!

• diff -r start/ finish/ has an output
  • one big issue is the system and inventory endpoint test files in finish
  • running mvn verify while services are running in finish doesn't work

Originally posted by @NimG98 in #4 (comment)

Although using the OL Operator was considered when the OpenShift guide was written, the Operator wasn't ready for the big time. Now it is, can we update the OpenShift guide? @yeekangc

• Introduction: Tie OpenShift to Kubernetes in a better way. This is important.

• "To login to OpenShift using the CLI, navigate to the online web console > [username] > Copy Login Command > Display Token > Log in with this token." -- I don't think we use monospace style to identify UI menu items.

• "The registry that you will use is called OpenShift Container Registry (OCR), which is OpenShift’s own internal registry which allows a built-in location for you to push images to." -- Double "which" one after another? Can rephrase.

• "taking the results of the above and manually inputting them into the following docker login command:
  docker login -u [oc whoami] -p [oc whoami -t] [oc registry info]"

"taking the results of the above and manually inputting them into the following docker tag commands:"

"taking the results of the above and manually inputting them into the following docker push commands:"

Users should replace what's in square brackets with the right values, right? If we will do it this way, we should clearly note that they should do so.

• "You can also view the registry address by running the following:" -- Running the following what?

• "The kubernetes.yaml object configuration file is provided for you. If you are interested in learning more about Kubernetes, check out the Deploying microservices to Kubernetes guide." -- Learning more about Kubernetes and its YAML configuration file?

• "They can also be found in the web console under Networking > Routes > Location." -- Again, style for UI menu items

• Front matter:

  • Ensure that page-duration is accurate;
  • Should have "Red Hat" in either the seo-title or seo-description at the minimum. Should double check common terms and ensure that we capture them. Should we include "Java" too? Refer to the other guides to be consistent too.

I will mark final review as complete. Can sign off when all the feedback and critical issue(s) have been addressed.

There may be quite some ID edits. Please plan accordingly.

@MaiHameed @gkwan-ibm

Taken from #7, can only implement after obtaining access to an OpenShift account since mine expired.

Comment:

• Right after the docker push commands and before "Deploying the microservices" section, I'd suggest to add a command to check if the images are pushed properly. oc get imagestream should list the images. Also you can guide people to check the OpenShift's container registry dashboard. I'm not sure if it's available in the OpenShift starter tier.

• the word "kubernetes.yaml" under the page description "Explore ..."
• "What you’ll learn"
  • the first statement, should use "using" or "on"?
    • "... cluster using OpenShift Online..."
  • It is not necessary to spell out all OpenShift platforms. Just describe what Openshift Online.
• "Pushing the images to OpenShift’s internal registry" subsection
  • in the following paragraph, ask readers to keep/remember/determine the [cluster-id] from the output
    • "The command authenticates you against the internal registry and then be able to push and pull images. The registry address will be displayed after running the oc registry login command, it will be formatted like so:"
    • Or treat "default-route-openshift-image-registry.apps.us-west-2.online-starter.openshift.com" as the [integrated-registry] and use it in the docker tag and docker push commands as docker tag system:1.0-SNAPSHOT [integrated-registry]/[project-name]/system:1.0-SNAPSHOT
  • for the following statements, need to ask readers to replace [cluster-id] and [project-name]
    • "Ensure that you are logged into OpenShift as well as the registry, now run the following commands to tag your applications:"
    • "Finally, push your images to the registry:"
  • Or move the following statement after "Ensure that..." statement, let readers aware before run the commands
    • "When you tag and push your images, remember to substitute [cluster-id] and [project-name] with the appropriate values."
  • Need following command?
    • "docker login -u oc whoami -p oc whoami -t default-route-openshift-image-registry.apps.us-east-2.online-starter.openshift.com"
  • no need && \ in both docker tag and docker push commands
  • "Update the kubernetes.yaml file." command not show the kubernetes.yaml file
• in "Making requests to the microservices" subsection
  • no need to have && \ at the oc expose commands
  • for the following paragraph, make sure reader in the project
    " ...in the web console under Networking > Routes > Location"
  • following statement shows incorrectly
    • " It will be automatically formatted like so project-name.apps.[cluster-id].online-starter.openshift.com"
  • need http:// for the following
    • [system-hostname]/system/properties/
    • [inventory-hostname]/inventory/systems

The guide uses OpenShift 3, version 4 has been around for a while. Please update.

The guide should provide a link to where users can create an OpenShift account. If credit card is necessary and there will be charges, these should be noted.

FYI, @gkwan-ibm.

The include file path ../guides-common//gitclone.adoc in the second section of the guide should be an absolute file path as it is in the guide-rest-intro repo. Also, the second slash before gitclone.doc should be a single slash.

YK has raised a general issue to check/fix this but could this one be fixed (and any other include references in this guide) so that we can continue testing it getting the same source built by the RH build system? Thx

Steps:

• Package and create a local image of both microservices inventory and system
• Tag images and push to public repository on third party registry, Docker Hub.
• Apply the kubernetes configuration file to deploy both microservices and start both services.
• Expose both services using OpenShift routes.
• Access the inventory application through the hostname URL
• Access the system application through the hostname URL

This issue is to address the EPIC issue OpenLiberty/guides-common#520.

By the recommendation, need to update kubernetes.yaml by using environment variables described in the JSON logging section of https://openliberty.io/docs/latest/log-trace-configuration.html

There isn't currently a standard for how we format UI menu navigations, example in the OpenShift guide here:

YK's comments on the issue as taken from #10:

• "To login to OpenShift using the CLI, navigate to the online web console > [username] > Copy Login Command > Display Token > Log in with this token." -- I don't think we use monospace style to identify UI menu items.

• "They can also be found in the web console under Networking > Routes > Location." -- Again, style for UI menu items

Now this format was also used in the IBM Cloud guide here:

So we'll need to figure out a more concrete way of including these.

Child of issue #5, to be addressed later as they are large scale changes that affect multiple guides:

• as mentioned in another guide I reviewed, I don't think this is a very realistic scenario that you have a monolithic build that builds two microservices. Microservices should be built and deployed separately as building and deploying services together defeats the purpose of having microservices.

• A little concerning is the security setting on Windows that you advise the user to shut off, where the docker daemon is exposed locally without TLS. I'd rather have maven not build the image than to shut this off. Usually a CI process will be building the docker image separately outside of the developer environment anyway.

• As we are building for openshift, one question I had was why we build the docker images locally rather than use any of the openshift s2i developer tools, DeploymentConfigs, or imagestreams. these are the value propositions of openshift for developers. For example, we could use a BuildConfig to build the docker image in openshift and not require Docker on the local user's desktop at all. This would handle building the image and pushing it to the internal registry, and create an ImageStream resource inside of Openshift for tracking.

At the Additional Prereq section, the "OpenShift Online documentation" link is broken.

Peer Review: review to be done by a peer member.

• Check that the guide has working instruction and sample code
• Check the quality of code according to the best coding practices
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Define test coverage and review with team (including guide contributor, if available)
• Define detail test cases
• Consider corner cases targeting the specific guide
• Consider different platform tests, ie, Mac, Windows, Linux
• Consider corner cases UI tests
• Consider testing URL on all browsers, ie, FF, Chrome, Safari
• Consider testing the curl command for URL visits
• Consider Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, VS.code, Eclipse, IntelliJ, Microclimate
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
• Table of contents
• Headings
• Paragraphs
• code snippets
• outputs
• links
• hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

• Starter tier doesn't seem to exist now
• Users have to sign up for a 30-day trial and register with a working payment method

Needs adding to this repo. Maybe other guide repos too?

add a section to describe OKD

COPY --chown=1001:0 target/system.war /config/apps

The above line does not work, when i moved it to below line it worked for me.

COPY target/system.war /config/dropins/

1. The /config/apps was wrong location to put the war file.
2. The command chown gave me error

Step 3/7 : ARG REVISION=SNAPSHOT
 ---> Using cache
 ---> a8068d720130
Step 4/7 : LABEL org.opencontainers.image.authors "Mai Hameed" org.opencontainers.image.vendor "Open Liberty" org.opencontainers.image.url "local" org.opencontainers.image.source "https://github.com/OpenLiberty/guide-cloud-openshift" org.opencontainers.image.version "$VERSION" org.opencontainers.image.revision "$REVISION" vendor "Open Liberty" name "system" version "$VERSION-$REVISION" summary "The system microservice from the Deploying microservices to OpenShift guide" description "This image contains the system microservice running with the Open Liberty runtime."
 ---> Using cache
 ---> aa6e0f1d93ee
Step 5/7 : COPY --chown=1001:0 src/main/liberty/config /config/
Unknown flag: chown

Use $(cmd) vs backticks

The OpenShift Online documentation link at the "Additional prerequisites" section is not available.

Either it is temporary or moved.

Correct the link if necessary.

I could not reach to /system/properties

Post-Publishing Tests (Danny)

• Check appearance (contents, headings, paragraphs, code snippets, outputs, links) of the guide on openliberty.io
• Clone repo and test finish directory with no error

Other post-publishing tasks (Gilbert)

• Add description for the repo with link to guide's published website
• Double check the SEO title and description are added for the guide
• Create the Home and Branches wiki pages
• Ensure automated test for PR and Continuous Tests are enabled for both master and qa branches and are run on Travis, see instruction
• Ensure the automated tests are running successfully for the daily builds
• Ensure the automated tests are running successfully for the daily docker image, if the guide uses a docker image
• Enable pull creation notification on the repo for was-lib-guides-alerts, see instruction
• Enable master and qa branches lock down, see instruction
  • make sure the Branch protection rules were created
• Add the new guide's repo to the OpenLiberty/guides-common ZenHub board
• Delete dev branch
• (Optional) Send announcement to slack channel(s)
• Arrange a demo at the EOI meeting