Update OpenShift guide to use the Operator

[gcharters]

Our strategic direction is to use the Liberty Operator for deploying to OpenShift, but our current OpenShift guide doesn't use this approach (because the operator didn't exist when it was written). We should update the OpenShift guide to use the operator-based approach.

This may resolve #303 or could be separate.

[yeekangc]

@gkwan-ibm @MaiHameed

[lauracowen]

Should we also update the Kubernetes guide (or guides)?

[yeekangc]

Make sense to consider for the Kubernetes guides too.

[jamiecoleman92]

This version also uses an older version of OpenShift so we may need to update that to take advantage of operators.

[nastacio]

I was asked to look at the guide for different reasons, and whereas I understand the desire to use this same sample across different tutorials, it just doesn't make for a good Docker-based example, more so when paired with the OpenShift platform.

My comments:

1. Best-practices for creation of Docker images call for repeatable content in the final image, so that asking users to install/run things like mvn to pre-generate the results locally for inclusion in the container image with docker build ... is a well-documented, long-established, bad-practice for the creation of Docker images (e.g. there is no guarantee about the final binaries packaged inside the image since each local installation may have different versions of java and mvn). If this guide's end-goal is to show people how to package Open Liberty, it is demonstrably and ostensibly telling the users to follow bad-practices that cannot be reused in an actual development shop or OpenShift CI/CD pipeline.

2. I suggest modifying the Dockerfiles to match something like this (https://github.com/ibm-cloud-architecture/learning-distributed-tracing-101/blob/master/lab-jaeger-istio-ol/service-a/Dockerfile), using a multi-stage build to build the WAR file in the first stage and then package the WAR file (alone) in the second stage, thus generating an image without any dependency on local Java/Maven installations.

3. OpenShift customers rely on oc new-build ... and oc new-app... to go from Git repo to deployed code, no real customer will be going about repeating all the internals of those steps by hand (oc registry ..., docker build..., docker push..., etc). The latest CRC installations don't even have those registry commands anymore. If you refactor the Dockerfile as suggested, you should be able to deploy the two apps simply with:

oc new-app https://github.com/OpenLiberty/guide-cloud-openshift.git --strategy=docker --context-dir=/finish/system --name system-service
oc new-app https://github.com/OpenLiberty/guide-cloud-openshift.git --strategy=docker --context-dir=/finish/inventory --name inventory-service

4. Re: Liberty Operator, I don't understand how it relates to the established process of using oc new-app or oc new-build. It would be quite the hard-sell to tell an OpenShift admin/dev to rebuild CI/CD processes and retrain their personnel exclusively for the build and deployment of Open Liberty apps.

[lauracowen]

@arthurdm ^^

[arthurdm]

hi @nastacio - regarding point 4: The Operator is meant to replace things like the DeploymentConfig, not BuildConfig. So you can definitely still use things like new-build or any other way to build the image or image stream, and then use the OL Operator to actually deploy it - with a much larger set of QoS available than what a vanilla Deployment or DeploymentConfig would allow.

[nastacio]

hi @nastacio - regarding point 4: The Operator is meant to replace things like the DeploymentConfig, not BuildConfig. So you can definitely still use things like new-build or any other way to build the image or image stream, and then use the OL Operator to actually deploy it - with a much larger set of QoS available than what a vanilla Deployment or DeploymentConfig would allow.

@arthurdm,

How about oc new-app? (also in point 4)

[arthurdm]

The new-app command is a superset of new-build - so it does a BuildConfig + DeploymentConfig (+ Service). It's a great tool for simple dev, but anything more substantial (for example using auto-scaling, certs, TLS, customized routes, etc) you would then either drop to using raw k8s (oc apply -f <yamls>) or something more powerful / easier to configure like the OL Operator (oc apply -f app-deploy.yaml).

[yeekangc]

I can understand Denilson's point 1 and 2 particularly in the context of CI/CD. Then, another key consideration is what is the optimal workflow for developers during development. A war and then image build can be reasonable. @gkwan-ibm @meswan, these are what we need to feed into OpenLiberty/open-liberty#9890 and validate with stakeholders/users.

The focus of this issue will be to use Open Liberty Operator for deployment for the OpenShift guide. Can have new issues to cover similar updates to the other guides if appropriate. (Use of Operator isn't specific to Open Liberty but a general trend/direction.)

[yeekangc]

Keep the current version around until OpenShift in the other clouds are updated to 4.x. Create a separate version that shows Operator for now.

[nastacio]

@arthurdm

The new-app command is a superset of new-build - so it does a BuildConfig + DeploymentConfig (+ Service). It's a great tool for simple dev, but anything more substantial (for example using auto-scaling, certs, TLS, customized routes, etc) you would then either drop to using raw k8s (oc apply -f <yamls>) or something more powerful / easier to configure like the OL Operator (oc apply -f app-deploy.yaml).

When you look at the oc new-app CLI help, you can see parameters like template and param. I have never used those directly, but a full understanding of those capabilities can better inform our position on whether addressing deployment complexity entails abandoning new-app altogether:

Options:
      --allow-missing-images=false: If true, indicates that referenced Docker images that cannot be found locally or in
a registry should still be used.
      --allow-missing-imagestream-tags=false: If true, indicates that image stream tags that don't exist should still be
used.
      --allow-missing-template-keys=false: If true, ignore any errors in templates when a field or map key is missing in
the template. Only applies to golang and jsonpath output formats.
      --as-test=false: If true create this application as a test deployment, which validates that the deployment
succeeds and then scales down.
      --binary=false: Instead of expecting a source URL, set the build to expect binary contents. Will disable triggers.
      --build-env=[]: Specify a key-value pair for an environment variable to set into each build image.
      --build-env-file=[]: File containing key-value pairs of environment variables to set into each build image.
      --code=[]: Source code to use to build this application.
      --context-dir='': Context directory to be used for the build.
      --docker-image=[]: Name of a Docker image to include in the app.
      --dry-run=false: If true, show the result of the operation without performing it.
  -e, --env=[]: Specify a key-value pair for an environment variable to set into each container.
      --env-file=[]: File containing key-value pairs of environment variables to set into each container.
  -f, --file=[]: Path to a template file to use for the app.
      --grant-install-rights=false: If true, a component that requires access to your account may use your token to
install software into your project. Only grant images you trust the right to run with your token.
      --group=[]: Indicate components that should be grouped together as <comp1>+<comp2>.
      --ignore-unknown-parameters=false: If true, will not stop processing if a provided parameter does not exist in the
template.
  -i, --image-stream=[]: Name of an image stream to use in the app.
      --insecure-registry=false: If true, indicates that the referenced Docker images are on insecure registries and
should bypass certificate checking
  -l, --labels='': Label to set in all resources for this application.
  -L, --list=false: List all local templates and image streams that can be used to create.
      --name='': Set name to use for generated application artifacts
      --no-install=false: Do not attempt to run images that describe themselves as being installable
  -o, --output='': Output format. One of:
json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
      --output-version='': The preferred API versions of the output objects
  -p, --param=[]: Specify a key-value pair (e.g., -p FOO=BAR) to set/override a parameter value in the template.
      --param-file=[]: File containing parameter values to set/override in the template.
  -S, --search=false: Search all templates, image streams, and Docker images that match the arguments provided.
  -a, --show-all=true: When printing, show all resources (false means hide terminated pods.)
      --show-labels=false: When printing, show all labels as the last column (default hide labels column)
      --sort-by='': If non-empty, sort list types using this field specification.  The field specification is expressed
as a JSONPath expression (e.g. '{.metadata.name}'). The field in the API resource specified by this JSONPath expression
must be an integer or a string.
      --source-secret='': The name of an existing secret that should be used for cloning a private git repository.
      --strategy=: Specify the build strategy to use if you don't want to detect (docker|pipeline|source).
      --template=[]: Name of a stored template to use in the app.

[nastacio]

Re: comment above, the integration with --image-stream is also an important aspect of new-app.

[arthurdm]

@nastacio +1. We added image stream support to our Operators recently. It reacts (i.e. rolling deployment) to changes in it.

[MaiHameed]

Hello all. I'm tasked with re-writing the guide to incorporate operators as well as any additional features discussed in this thread or pointed out to me. I wanted to take a moment to showcase what I updated in the draft to incorporate said changes:

• The Open Liberty application in use will still be the system and inventory services as consistently used across multiple guides. For those who are unaware, the system service, when accessed, will respond with the system properties of the host. The system service can run independently, and will not need to communicate with the inventory service. The inventory service will need to access the system service to gather the system properties, and store them in-memory.
• The guide will cover using OpenShift 4.x through OCP. This is an update from using OpenShift 3.x, hosted using OpenShift Online.
• I updated the Dockerfiles for both services to utilize the multi-stage build as discussed above. This eliminates the need for the end users to have Maven or Java at all, as the source code + Dockerfile will be in the guide repo. The guide will be asking the user to create the service imagestreams via the following command:

oc new-build https://github.com/OpenLiberty/guide-cloud-openshift.git#update-operators --strategy=docker --context-dir=/finish/[system|inventory] --name [system|inventory]

• The guide will ask the user to install the OL operator either through OperatorHub or through the CLI using the instructions provided here: https://github.com/OpenLiberty/open-liberty-operator/tree/master/deploy/releases/0.4.0.
• The OL apps will be deployed using a YAML file, and will showcase:
  • ease of exposing the services
  • service binding between the inventory (consumer) and the system (producer) services
  • how to deploy using imagestreams

The above changes have been implemented in a new branch, here: OpenLiberty/archived-guide-cloud-openshift#53. It includes the deployment.yaml file as well as the new multi-stage Dockerfiles.

Additional features that I will be or will be thinking of implementing are:

• Setting ENV variables
• Day-2 operations including collecting traces and dumps
• Persistence storage

I wanted some quick reviews before proceeding with the guide update to ensure that it looks good to you all, and if there are any comments/questions/concerns with the process thus far. @nastacio @arthurdm @yeekangc @gkwan-ibm @gcharters @jamiecoleman92. Also CCing @leochr and @navidsh as they provided some ideas on the guide content.

[yeekangc]

As indicated in a prior comment, the version with Operator should be in a new guide. The existing one should be kept around for users that need it.

[gkwan-ibm]

• it will be a new guide
• suggest to use new sys/inv app as the reactive guide
• show Service Binding operator if possible
• add a link to the old openshift guide

[gkwan-ibm]

• trying to deploy the reactive app by operator to openshift

[gkwan-ibm]

• successfully deploy the reactive app by operator to openshift
• start to draft the readme

[gkwan-ibm]

• simplified the deployment process

[gkwan-ibm]

• SME review in progress

[gkwan-ibm]

• addressing SME review feedback

[gkwan-ibm]

• addressed SME review
• next user review

[meswan]

• User review completed with feedback
• feedback addressed and verified
• next id review

[gkwan-ibm]

• final content and ID review in progress

[yeekangc]

Signing off assuming the latest PRs will be merged. Please proceed to publish.

[yeekangc]

Published at https://openliberty.io/guides/cloud-openshift-operator.html.