Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/openliberty/guide-cloud-openshift-operator

A guide on how to deploy microservices to Red Hat OpenShift by using Kubernetes Operators.
https://github.com/openliberty/guide-cloud-openshift-operator

Last synced: 3 months ago
JSON representation

A guide on how to deploy microservices to Red Hat OpenShift by using Kubernetes Operators.

Awesome Lists containing this project

README 

        
// Copyright (c) 2020, 2024 IBM Corporation and others.

// Licensed under Creative Commons Attribution-NoDerivatives

// 4.0 International (CC BY-ND 4.0)

//   https://creativecommons.org/licenses/by-nd/4.0/

//

// Contributors:

//     IBM Corporation

//

:projectid: cloud-openshift-operator

:page-layout: guide-multipane

:page-duration: 30 minutes

:page-releasedate: 2020-10-30

:page-majorupdateddate: 2024-04-04

:page-description: Explore how to deploy microservices to Red Hat OpenShift 4 using Kubernetes Operators like the Open Liberty Operator.

:page-tags: ['kubernetes', 'docker', 'cloud'] 

:page-permalink: /guides/{projectid}

:page-related-guides: ['cloud-openshift', 'okd']

:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod

:imagesdir: /img/guide/{projectid}

:source-highlighter: prettify

:page-seo-title: Deploying microservices to Red Hat OpenShift 4 using Kubernetes Operators

:page-seo-description: A getting started tutorial with examples on how to deploy cloud-native Java applications and microservices to Red Hat OpenShift cluster by using Kubernetes Operators like the Open Liberty Operator.

:guide-author: Open Liberty

= Deploying microservices to OpenShift 4 using Kubernetes Operators



[.hidden]

NOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website^].



Explore how to deploy microservices to Red Hat OpenShift 4 using Kubernetes Operators.



== What you'll learn 



You will learn how to deploy a cloud-native application with 2 microservices to Red Hat OpenShift 4 using Kubernetes Operators like the Open Liberty Operator. 

You will install two operators into an OpenShift cluster and use them to deploy and scale sample microservices. 



https://www.openshift.com/[OpenShift^] is a Kubernetes-based platform with added functions. It streamlines the DevOps

process by providing an intuitive development pipeline. It also provides integration with multiple tools to make the

deployment and management of cloud applications easier.

You can learn more about Kubernetes by checking out the https://openliberty.io/guides/kubernetes-intro.html[Deploying microservices to Kubernetes^] guide.



https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#operators-in-kubernetes[Kubernetes operators]

provide an easy way to automate the management and updating of applications by abstracting away some of the details of cloud application management.

To learn more about operators, check out this https://www.openshift.com/learn/topics/operators[Operators tech topic article^]. 



The application in this guide consists of two microservices, `system` and `inventory`. Every 15 seconds, the `system`

microservice calculates and publishes events that contain its current average system load. The `inventory` microservice

subscribes to that information so that it can keep an updated list of all the system microservices and their current system loads.



The following figure shows the application that you deploy, which consists of two microservices, `system` and `inventory`, connected by a message broker:



image::reactive-messaging-system-inventory-rest.png[Reactive system inventory,align="center"]



You will deploy the two Open Liberty microservices by using the Open Liberty Operator, and deploy Kafka using the Strimzi Operator. 

The https://github.com/OpenLiberty/open-liberty-operator[Open Liberty Operator^] provides a method of packaging,

deploying, and managing Open Liberty applications on Kubernetes-based clusters. 

The Open Liberty Operator watches Open Liberty resources and creates various Kubernetes resources,

including `Deployments`, `Services`, and `Routes`, depending on the configurations. 

The Operator then continuously compares the current state of the resources, the desired state

of application deployment, and reconciles them when necessary.

To learn more about the Strimzi Operator, visit their https://strimzi.io/[official website^].

You can learn more about how the reactive Java services used in this guide work by checking out the

https://openliberty.io/guides/microprofile-reactive-messaging.html[Creating reactive Java microservices^] guide.



== Additional prerequisites



Before you can deploy your microservices, you must gain access to a cluster on OpenShift and have an OpenShift client installed. 

For client installation instructions, refer to https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[the official OpenShift Online documentation^].



There are various OpenShift offerings. You can gain access to an OpenShift cluster that is hosted on

https://www.openshift.com/products/openshift-ibm-cloud[IBM Cloud^], or check out other offerings

https://www.openshift.com/products[from OpenShift^]. 



After you get access to a cluster, make sure you are logged in to the cluster

as a cluster administrator by running the following command:



[role='command']

```

oc version

```



Look for output similar to the following example:



[role='no_copy']

```

Client Version: 4.14.0

Server Version: 4.14.0

Kubernetes Version: v1.27.11

```



Before you install any resources, you need to create a project on your OpenShift cluster.

Create a project named `guide` by running the following command:



[role='command']

```

oc new-project guide

```



Ensure that you are working within the project `guide` by running the following command:



[role='command']

```

oc projects

```



Look for an asterisk (*) with the `guide` project in the list of projects to confirm that you are in the `guide` project, as shown in the following example:



[role='no_copy']

```

You have access to the following projects and can switch between them with 'oc project ':



    default

  * guide

```



If the https://cert-manager.io[cert-manager^]  is not installed on your cluster yet, install it by running the following command:

[role='command']

```

oc apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml

```

For more information, see the https://cert-manager.io/docs/installation[cert-manager installation] documentation.



// Getting Started block



== Getting started



The fastest way to work through this guide is to clone the https://github.com/openliberty/guide-{projectid}.git[Git repository^]

into your cluster and use the projects that are provided inside:



[source, role="command", subs="attributes"]

----

git clone https://github.com/openliberty/guide-{projectid}.git

cd guide-{projectid}

cd start

----



The `start` directory contains the starting project that you will build upon.



The `finish` directory contains the finished project that you will build.



// no "try what you'll build" section in this guide because it would be too long due to all setup the user will have to do.



== Installing the Operators



When you obtained your OpenShift cluster, you received login information for the

https://docs.openshift.com/container-platform/latest/web_console/web-console.html[OpenShift web console^].

The web console provides an interface to interact with your OpenShift cluster through your web browser.



To install the two Operators, navigate to the web console and select *Operators > OperatorHub* from the sidebar menu.

Search for and install the *Open Liberty Operator* and the *Strimzi Operator*. For the Strimzi Operator, install the latest version, not the stable version.

Make sure you install the Operators into the `guide` namespace. 



Run the following command to view all the supported API resources that are available through the Open Liberty Operator:



[role='command']

```

oc api-resources --api-group=apps.openliberty.io

```



Look for the following output, which shows the https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[custom resource definitions^] (CRDs) that can be used by the Open Liberty Operator:



[role='no_copy']

```

NAME                      SHORTNAMES         APIGROUP              NAMESPACED   KIND

openlibertyapplications   olapp,olapps       apps.openliberty.io   true         OpenLibertyApplication

openlibertydumps          oldump,oldumps     apps.openliberty.io   true         OpenLibertyDump

openlibertytraces         oltrace,oltraces   apps.openliberty.io   true         OpenLibertyTrace

```



Each CRD defines a kind of object that can be used, which is specified in the previous example by the `KIND` value.

The `SHORTNAME` value specifies alternative names that you can substitute in the configuration to refer to an object kind. 

For example, you can refer to the `OpenLibertyApplication` object kind by one of its specified shortnames, such as `olapps`. 



The `openlibertyapplications` CRD defines a set of configurations for

deploying an Open Liberty-based application, including the application image, number of instances, and storage settings.

The Open Liberty Operator watches for changes to instances of the `OpenLibertyApplication` object kind and creates Kubernetes resources that are based on the configuration that is defined in the CRD.



Run the following command to all CRDs that the Strimzi Operator uses:



[role='command']

```

oc api-resources --api-group=kafka.strimzi.io

```



Look for the following output, which lists the CRDs that the Strimzi Operator uses, along with object kinds and shortnames.



[role='no_copy']

```

NAME                 SHORTNAMES   APIGROUP           NAMESPACED   KIND

kafkabridges         kb           kafka.strimzi.io   true         KafkaBridge

kafkaconnectors      kctr         kafka.strimzi.io   true         KafkaConnector

kafkaconnects        kc           kafka.strimzi.io   true         KafkaConnect

kafkaconnects2is     kcs2i        kafka.strimzi.io   true         KafkaConnectS2I

kafkamirrormaker2s   kmm2         kafka.strimzi.io   true         KafkaMirrorMaker2

kafkamirrormakers    kmm          kafka.strimzi.io   true         KafkaMirrorMaker

kafkarebalances      kr           kafka.strimzi.io   true         KafkaRebalance

kafkas               k            kafka.strimzi.io   true         Kafka

kafkatopics          kt           kafka.strimzi.io   true         KafkaTopic

kafkausers           ku           kafka.strimzi.io   true         KafkaUser

```



You can also confirm the installation of the operators from the web console.

Navigate to the OperatorHub.

From the categories on the left, you can filter to see only installed operators. 



== Adding a private Docker credential



Docker limits container image pull requests for free DockerHub subscriptions. 

For more information, see link:https://www.docker.com/increase-rate-limits[Understanding Docker Hub Rate Limiting].

If you have a Docker account with a Pro or Team subscription, you can add a private credential to avoid any errors as a result of the limits.



To add a private credential, navigate to the OpenShift web console and select *Workloads > Secrets* from the sidebar menu. 

Ensure that the selected project is `openshift-config`. 

Search for `pull-secret` and click the *three vertical dots* menu; then *Edit Secret*. 

Scroll down and click *Add credentials*.  

Enter `docker.io` to the *Registry Server Address* field, 

your Docker user ID to the *Username* field, 

and your Docker password to the *Password* field.

Click the *Save* button to save the credential. 



== Deploying the Kafka cluster to OpenShift



//File 0

kafka.yaml

[source, yaml, linenums, role='code_column']

----

include::finish/kafka.yaml[]

----



Apache Kafka is the messaging broker that is used in this application. The Strimzi Operator simplifies the deployment

and management of Kafka clusters. 



You can configure the specifics of the Strimzi Operator-controlled Kafka deployment with a YAML configuration file.



Ensure that you are in the `start` directory.



[role="code_command hotspot file=0", subs="quotes"]

----

#Create the `kafka.yaml` configuration file in the `start` directory.#

`kafka.yaml`

----



The provided Kafka cluster configuration is based on the

https://github.com/strimzi/strimzi-kafka-operator/blob/main/examples/kafka/kafka-ephemeral-single.yaml[Strimzi Kafka ephemeral single example^].

For more information about the Kafka configuration file, check out the

https://strimzi.io/docs/operators/master/using.html#assembly-deployment-configuration-kafka-str[official Strimzi documentation^]



Run the following command to deploy Kafka by using the newly created configuration file:



[role='command']

```

oc apply -f kafka.yaml

```



Run the following command to view the details of the deployment:



[role='command']

```

oc get kafka/kafka-cluster -o yaml

```



In the `status` section under `conditions` you can see a report similar to the following example when the cluster is ready:



[role='no_copy']

```

- lastTransitionTime: 2024-03-28T19:27:00+0000

  status: "True"

  type: Ready

```



== Deploying the system and inventory microservices to OpenShift



//File 0

build.yaml

[source, yaml, linenums, role='code_column']

----

include::finish/build.yaml[]

----



To deploy the `system` and `inventory` microservices, you must first package the microservices, then create and

run an OpenShift build to produce runnable container images of the packaged microservices.



=== Packaging the microservices



Ensure that you are in the `start` directory and run the following commands to package the `system` and `inventory`

microservices:



[role='command']

```

mvn -pl models clean install

mvn clean package

```



=== Building and pushing the images



Create a build template to configure how to build your container images.



[role="code_command hotspot file=0", subs="quotes"]

----

#Create the `build.yaml` template file in the `start` directory.#

`build.yaml`

----



The [hotspot file=0]`build.yaml` template includes two objects. 

The [hotspot=imageStream file=0]`ImageStream` object provides an abstraction from the image in the image registry. 

This allows you to reference and tag the image. 

The image registry used is the integrated internal OpenShift Container Registry.



The [hotspot=buildConfig file=0]`BuildConfig` object defines a single

build definition and any triggers that kickstart the build. The [hotspot=source file=0]`source` spec defines the build input. In this case,

the build inputs are your [hotspot=binary file=0]`binary` (local) files, which are streamed to OpenShift for the build.

The uploaded files need to include the packaged `WAR` application binaries, which is why you needed to run the Maven commands. The template specifies

a [hotspot=docker file=0]`Docker` strategy build, which invokes the `docker build` command, and creates a runnable container image of the microservice

from the build input. The template is parameterized with the [hotspot=appname file=0]`APP_NAME` parameter so that you can use the same

template to create the objects for the `system` and `inventory` microservices separately.



Run the following commands to create the objects for the `system` and `inventory` microservices:



[role='command']

```

oc process -f build.yaml -p APP_NAME=system | oc create -f -

oc process -f build.yaml -p APP_NAME=inventory | oc create -f -

```



Next, run the following commands to view the newly created `ImageStream` objects and the build configurations for each microservice:



[role='command']

```

oc get all -l name=system

oc get all -l name=inventory

```



Look for the following resources:



[role='no_copy']

```

NAME                                                TYPE     FROM     LATEST

buildconfig.build.openshift.io/system-buildconfig   Docker   Binary   0



NAME                                                IMAGE REPOSITORY                                                            TAGS           UPDATED

imagestream.image.openshift.io/system-imagestream   image-registry.openshift-image-registry.svc:5000/guide/system-imagestream   1.0-SNAPSHOT   2 days ago



...



NAME                                                   TYPE     FROM     LATEST

buildconfig.build.openshift.io/inventory-buildconfig   Docker   Binary   2



NAME                                                   IMAGE REPOSITORY                                                               TAGS           UPDATED

imagestream.image.openshift.io/inventory-imagestream   image-registry.openshift-image-registry.svc:5000/guide/inventory-imagestream   1.0-SNAPSHOT   2 days ago

```



Ensure that you are in the `start` directory and trigger the builds by running the following commands:



[role='command']

```

oc start-build system-buildconfig --from-dir=system/.

oc start-build inventory-buildconfig --from-dir=inventory/.

```



The local `system` and `inventory` directories are uploaded to OpenShift to be built into the Docker images. Run the

following command to list the builds and track their status:



[role='command']

```

oc get builds

```



Look for the output that is similar to the following example:



[role='no_copy']

```

NAME                      TYPE     FROM             STATUS     STARTED

system-buildconfig-1      Docker   Binary@f24cb58   Running    45 seconds ago

inventory-buildconfig-1   Docker   Binary@f24cb58   Running    13 seconds ago

```



You may need to wait some time until the build is complete. To check whether the build is complete, run the following

commands to view the build logs until the `Push successful` message appears:



[role='command']

```

oc logs build/system-buildconfig-1

oc logs build/inventory-buildconfig-1

```



=== Checking the images



During the build process, the images associated with the `ImageStream` objects that you created earlier

were pushed to the image registry and tagged. Run the following command to view the newly updated `ImageStream` objects:



[role='command']

```

oc get imagestreams

```



Run the following commands to get more details on the newly pushed images within the streams:



[role='command']

```

oc describe imagestream/system-imagestream

oc describe imagestream/inventory-imagestream

```



The following example shows part of the `system-imagestream` output:



[role='no_copy']

```

Name:                     system-imagestream

Namespace:                guide

Created:                  2 minutes ago

Labels:                   name=system

Annotations:              

Image Repository:         image-registry.openshift-image-registry.svc:5000/guide/system-imagestream

Image Lookup:             local=false

Unique Images:            1

Tags:                     1



...

```

Look for similar output for `inventory-imagestream`.



Now you're ready to deploy the images.



=== Deploying the images

//File 0

deploy.yaml

[source, yaml, linenums, role='code_column hide_tags=replicas']

----

include::finish/deploy.yaml[]

----



You can configure the specifics of the Open Liberty Operator-controlled deployment with a YAML configuration file.



[role="code_command hotspot file=0", subs="quotes"]

----

#Create the `deploy.yaml` configuration file in the `start` directory.#

`deploy.yaml`

----



The [hotspot file=0]`deploy.yaml` file is configured to deploy two [hotspot=olapp1 hotspot=olapp2 file=0]`OpenLibertyApplication`

resources, [hotspot=system file=0]`system` and [hotspot=inventory file=0]`inventory`, which are controlled by

the Open Liberty Operator.



The [hotspot=sysImage hotspot=invImage file=0]`applicationImage` parameter defines what container image is deployed as part of the `OpenLibertyApplication` CRD. 

This parameter follows the `/[:tag]` format.

The parameter can also point to an image hosted on an external registry, such as Docker Hub. 

The [hotspot=system file=0]`system` microservice is configured to use the [hotspot=sysImage file=0]`image` created from the earlier build. 



One of the benefits of using `ImageStream` objects is that the operator redeploys the application when it detects a new image is pushed.

The [hotspot=systemEnv file=0]`env` parameter is used to specify environment variables that are passed to the container at runtime.

You need to specify the bootstrap address required to communicate with the deployed Kafka cluster as an environment variable.



Update the [hotspot=bootstrap hotspot=bootstrapInv file=0]`[kafka-bootstrap-address]` variable to the

bootstrap address found by running the following command:



[role='command']

```

oc describe kafka kafka-cluster | grep -B1 "Name:\s*plain" | grep "Bootstrap Servers:" | awk '{print $3}'

```



You will see output similar to the following example:



[role='no_copy']

```

kafka-cluster-kafka-bootstrap.guide.svc:9092

```



The [hotspot=inventory file=0]`inventory` microservice is configured

similarly to the [hotspot=system file=0]`system` microservice.

Additionally, the `inventory` microservice includes the [hotspot=service file=0]`service`

and [hotspot=expose file=0]`expose` parameters.

The [hotspot=servicePort file=0]`service.port` parameter specifies which port is exposed by the container,

allowing the microservice to be accessed from outside the container.

To access the microservice from outside of the cluster,

it must be exposed by setting the [hotspot=expose file=0]`expose` parameter to `true`.

After you expose the microservice, the Operator automatically creates and configures routes for external access to your microservice.



Run the following command to deploy the `system` and `inventory` microservices with the previously explained configurations:



[role='command']

```

oc apply -f deploy.yaml

```



Next, run the following command to view your newly created `OpenLibertyApplications` resources:



[role='command']

```

oc get OpenLibertyApplications

```



You can also replace `OpenLibertyApplications` with the shortname `olapps`.



Look for output that is similar to the following example:



[role='no_copy']

```

NAME        IMAGE                                      EXPOSED   RECONCILED   AGE

inventory   guide/inventory-imagestream:1.0-SNAPSHOT   true      True         10s

system      guide/system-imagestream:1.0-SNAPSHOT                True         10s

```



A `RECONCILED` state value of `True` indicates that the operator was able to successfully process the `OpenLibertyApplications` instances. 

Run the following commands to view details of your microservices:



[role='command']

```

oc describe olapps/system

oc describe olapps/inventory

```



This example shows part of the `olapps/system` output:



[role='no_copy']

```

Name:         system

Namespace:    guide

Labels:       app.kubernetes.io/part-of=system

              name=system

Annotations:  kubectl.kubernetes.io/last-applied-configuration:

                {"apiVersion":"apps.openliberty.io/v1","kind":"OpenLibertyApplication","metadata":{"annotations":{},"labels":{"name":"system"},"name":"sys...

API Version:  apps.openliberty.io/v1

Kind:         OpenLibertyApplication



...

```



Look for a similar output for `olapps/inventory`.



== Accessing the inventory microservice



To access the exposed `inventory` microservice, run the following command and make note of the `HOST`:



[role='command']

```

oc get routes

```



Look for an output that is similar to the following example:



[role='no_copy']

```

NAME        HOST/PORT                                    PATH   SERVICES    PORT       TERMINATION   WILDCARD

inventory   inventory-guide.apps.lights.os.fyre.ibm.com         inventory   9448-tcp                 None

```



Visit the `inventory` microservice by going to the following URL: 

`https://[HOST]/inventory/systems`



Make sure to substitute the appropriate `HOST` value.

For example, using the output from the command above, `inventory-guide.apps.lights.os.fyre.ibm.com` is the `HOST`.

The following example shows this value substituted for `HOST` in the URL:

`\https://inventory-guide.apps.lights.os.fyre.ibm.com/inventory/systems`.



Look for a JSON response that is similar to the following example: 



[role='no_copy']

```

[

    {

        "hostname": "system-7cbc47455c-664wh",

        "systemLoad": 1.15

    }

]

```

This sample output was formatted for readability. Your output might not be formatted.



== Scaling up the system microservices



//File 0

deploy.yaml

[source, yaml, linenums, role='code_column']

----

include::finish/deploy.yaml[]

----



The `inventory` microservice displays the `hostname` and `systemLoad` of all `system` microservices that are publishing

messages to the Kafka broker. Because only one `system` pod is running, only one element displays in the `inventory` microservice.

Scaling up microservices is easy with Operators. Simply update the `deploy.yaml` file with the `replica: n` parameter,

where `n` is the number of instances that you want.



[role="code_command hotspot file=0", subs="quotes"]

----

#Update the `deploy.yaml` configuration file in the `start` directory.#

`deploy.yaml`

----

[role="edit_command_text"]

Add the [hotspot=replicas file=0]`replicas` parameter to the `system` configuration.



Run the following command to update the `system` resource:



[role='command']

```

oc apply -f deploy.yaml

```



Look for the following output:



[role='no_copy']

```

openlibertyapplications.apps.openliberty.io/system configured

openlibertyapplications.apps.openliberty.io/inventory unchanged

```



Notice that only the `system` resource was updated because there was a change in its specification. The `inventory`

resource was left unchanged.



Run the following command to see the newly scaled up `system` pods:



[role='command']

```

oc get pods

```



When you see a status of `Running` on all of the `system` pods, your application is ready. 

Revisit the `inventory` microservice and you can now see three instances of the `system` microservice listed in the `inventory` endpoint:



[role='no_copy']

```

[

    {

        "hostname": "system-5bb7b86fd5-b5plz",

        "systemLoad": 2.73

    },

    {

        "hostname": "system-5bb7b86fd5-fkd5j",

        "systemLoad": 2.95

    },

    {

        "hostname": "system-5bb7b86fd5-pgcbf",

        "systemLoad": 2.73

    }

]

```



== Tearing down the environment



When you no longer need your project, switch to another project and delete the project `guide` by running the following command:



[role='command']

```

oc delete project guide

```



This command deletes all the applications and resources.



== Great work! You're done!



You just deployed two microservices running in Open Liberty to OpenShift by using the Open Liberty Operator.



== Related Links



// Multipane

include::{common-includes}/attribution.adoc[subs="attributes"]



// DO NO CREATE ANYMORE SECTIONS AT THIS POINT

// Related guides will be added in automatically here if you included them in ":page-related-guides"