kogito-openshift-getting-started-guide: A repository from DuncanDoyle

Table of Contents

Kogito on OpenShift: Getting Started Guide
Problem Statement
OpenShift Environment
Install the Kogito Operator
- Installing the Operator with the Kogito CLI
Open the Kogito project
Installing Infinispan persistence
Installing Kafka messaging.
Installing the Data Index Service
Cloning the Kogito Travel Agency application.
Creating the Kogito Services
Building the projects
- Kogito Travel Agency Application
- Kogito Visas Application
Running the Demo
Conclusion

Kogito on OpenShift: Getting Started Guide

In this advanced Kogito lab, we will deploy an advanced, multi-service, Kogito application, including Kogito support services and infrastructure. We will add persistence with Infinispan, messaging with Kafka and data-indexing and search with GraphQL

Goals

Deploy an advanced Kogito application, including supporting services and infrastructure.

Prerequisite

Visual Studio Code: https://code.visualstudio.com/
Kogito Tooling Visual Studio Code: https://github.com/kiegroup/kogito-tooling/releases
OpenShift 4.x environment.
OpenShift oc client.
Kogito CLI: https://github.com/kiegroup/kogito-cloud-operator/releases
Git client
JDK 11
Maven 3.5.x+: https://maven.apache.org
GraalVM (optional): https://www.graalvm.org/

Problem Statement

The goal is to create a full Kogito enterprise environment in OpenShift.

Deploy Kogito infrastructure (Infinispan, Kafka) using the Kogito Operator and CLI.
Deploy Kogito application and service definitions using the Kogito CLI.
Use OpenShift Binary Builds to push Kogito services to OpenShift.

OpenShift Environment

To complete this guide, you will need to have access to an OpenShift environment in which either:

you have cluster admin rights, or
the Kogito Operator is already installed in a namespace accessible to you.

The reason is that in order to install Operators on OpenShift, you need to have cluster admin rights.

You can use different types of OpenShift 4.x environments, like a full OpenShift cluster, or a small [CodeReady Containers](https://github.com/code-ready/crc) environment. The OpenShift environment needs to have access to the outside world in order to be able to pull in the required container images and build artefacts.

First, we need to login to the OpenShift environment, both via the web console and via the oc command line client.

Navigate to your OpenShift Master console and login with your credentials.
In the upper-right corner of the console, click on your username. In the dropdown, click on Copy Login Command.
Provide your username and password again, and in the next screen, click on Display Token.
Copy the oc login command, and run it in a terminal: oc login --token={openshift_token} --server=https://OpenShift Master

Depending on whether you’ve cluster admin rights or not, you either:

Create a new project and install the Kogito Operator.
Connect to the project that has the Kogito Operator installed.

If you don’t have cluster admin rights, and have access to a project with the Kogito Operator installed, continue with the Open the Kogito project section.

Install the Kogito Operator

The Kogito Operator can be installed via either the Operator Hub in the OpenShift Console, or via the Kogito CLI. In this guid we will be using the Kogito CLI.

Installing the Operator with the Kogito CLI

To install the Kogito Operator, we first need to create a project/namespace in OpenShift in which we will install our Operator and application. You can do this either from the OpenShift console or with the oc client. In this guide we will use the oc client.

In a terminal, with the oc client connected to your OpenShift environment, issue the following command to create a new project: oc new-project kogito-travel-agency --display-name="Kogito Travel Agency" --description="Kogito Travel Agency application."
Make sure your kogito tooling is using our new project. Issue the following command: kogito use-project. This should return: Project set to 'kogito-travel-agency'. If this is not the case, issue the command: kogito use-project kogito-travel-agency
The kogito use-project command will also automatically install the:
1. Kogito Operator:
2. Infinispan Operator: provides persistence infrastructure to Kogito applications and support services.
3. Strimzi Operator: provides messaging infrastructure to Kogito applications.
4. Keycload Operator: provides security and single-sign-on infrastructure to Kogito applications.
The Kogito Operator can also be installed with the command: kogito install operator

Navigate to your OpenShift console. Open the project you’ve created. In the left-hand side of the screen, click on Operators → Install Operators. The Operators will be listed:

Open the Kogito project

If you don’t have cluster admin rights on your OpenShift instance, a project with the Kogito Operator (and the Operators it depends on) should be provided to you. Say that this project is called kogito-travel-agency

In a terminal, with the oc client connected to your OpenShift instance, open your project with the command: oc project kogito-travel-agency.
Make sure your kogito tooling is using our new project. Issue the following command: kogito use-project. This should return: Project set to 'kogito-travel-agency'. If this is not the case, issue the command: kogito use-project kogito-travel-agency

Installing Infinispan persistence

Kogito persistence is built on-top of the NoSQL key/value store paradigm. By defaul, Kogito services and support services use [Infinispan](https://infinispan.org/) as their persistence provider. The Kogito Operator depends on, and user, the Infinispan Operator to deploy and manage the Infinispan infrastructure in the Kogito project.

The Infinispan infrastructure can be installed both from the Kogito Operator UI in the OpenShift Console and the kogito client. In this guide, we will be using the kogito client.

From a terminal, install the Infinispan infrastructure using the command: kogito install infinispan
Navigate to the Kogito Operator in the OpenShift console. A new kogito-infra CR (Custom Resource) will be created:
If we navigate to the Infinispan Operator in the OpenShift Console, we can see the kogito-infispan Infinispan CR, which defines the Infispan cluster:
Under Workloads → Stateful Sets, the kogito-infinispan Stateful Set is deployed.

With the persistence infrastructure deployed, we can continue with the messaging infrastructure

Installing Kafka messaging.

Kogito services and support services are built on [Quarkus](https://quarkus.io/) (note Kogito services can also be built on top of SpringBoot), and as such use MicroProfile Reactive Messaging specification for messaging. By default Kogito uses [Apache Kafka](https://kafka.apache.org/) as the messaging provider. The Kogito Operator depends on, and uses, the [Strimzi](https://strimzi.io/) Operator to deploy and manage the Kafka infrastructure in the Kogito project.

The Kafka infrastructure can be installed both from the Kogito Operator UI in the OpenShift Console and the kogito client. In this guide, we will use the kogito client.

From a terminal, install the Kafka infrastructure with the command: kogito install kafka
Navigate to the Kogito Operator in the OpenShift console. Navigate to the Kogito Infra tab. Click on the kogito-infra CR, and observe that the Install Kafka switch is enabled. I.e. the Kogito Kafka management resides in the same KogitoInfra Custom Resource as the Kogito Infispan infra.
Navigate to the Strimzi Operator in the OpenShift Console. Observe the kogito-kafka CR instance:
Under Workloads → Stateful Sets we can see the Kafka and Kafka Zookeeper stateful sets deployed:

With the infrastructure deployed, we can now deploy the Kogito Support Services, in particular the Data Index Service.

Installing the Data Index Service

The Kogito Data Index Service is responsible for storing all Kogito events related to processes, tasks and domain data. It operates by consuming messages from various Kafka topics, indexing them and storing them into the Infinispan persistence store. The Data Index Service provides the back bone for all of the Kogito search, insight and management capabilities.

The Data Index Service can be installed both from the Kogito Operator UI in the OpenShift Console and the kogito client. In this guide we will use the kogito client.

From a terminal, install the Kogito Data Index Service with the command: kogito install data-index

The response in the terminal states that, because no Infinispan and Kafka information was provided in the command, the required Infinispan and Kafka infrastructure will be automatically deployed if it does not yet exist. However, since we’ve already deployed this infrastructure, the Kogito Operator will make sure that the Data Index Service is provisioned with the configuration settings required to connect to our existing infrastructure.

Note	It would have been possible to deploy the entire Kogito Infrastructure by simply deploying the Kogito Data Index Service. However, in this guide we want to be explicit and show you all of the individual components, and their management commands, that build up a Kogito application.

Navigate to the Kogito Operator in the OpenShift console. Navigate to the Kogito Data Index tab. Click on the kogito-infra CR, and observe that the Install Kafka switch is enabled. I.e. the Kogito Kafka management resides in the same KogitoInfra Custom Resource as the Kogito Infispan infra.
Navigate to Workloads → Deployments and observe the deployed Data Index Service:
Navigate to Networking → Routes. Observe the kogito-data-index route.
Click on the URL in the Location column of the kogito-data-index route, which brings you to the Kogito Data Index Service Graph_i_QL interface.

We have now deployed the full infrastructure required to run our Kogito Travel Agency application, we can now build and deploy our services.

Cloning the Kogito Travel Agency application.

The Kogito Travel Agency application is available on Github: https://github.com/kiegroup/kogito-travel-agency-tutorial

The application is comprised of 2 Kogito services/applications:

Travel Agency: the application in which you book a travel
Visas: the application in which a visa, if required, is managed

The BPMN2 diagrams of these two Kogito Services is shown below:

As can be seen from the diagrams, the semantics of the kogito-travel-agency processes is to book a trip, including flight and hotel, to a destination on a given date. A ruleset defines whether a visa is required for the given destination. The visa approval logic is implemented by the kogito-visas service.

These 2 services expose RESTful APIs, which are fully generated from the project’s business assets (BPMN2 process definitions in this case). Internally they communicate via messaging, in particular Apache Kafka. Also the logic to interact with Kafka to produce and consume messages is fully generated from the BPMN2 process definitions.

To work with the Kogito Travel Agency application and deploy it into our kogito-travel-agency project in OpenShift, we first need to clone it to our local system.

In a terminal, move to a directory in which you would like to clone and store the Kogito Travel Agency application.
Execute the following command to clone the repository to your local filesystem: git clone https://github.com/kiegroup/kogito-travel-agency-tutorial.git

The cloned repository contains a number of different projects, each of them increasing in complexity. In this guide, we will be using the projects 08-kogito-travel-agency and 08-kogito-visas, as these are the most elaborate.

Creating the Kogito Services

To deploy our Kogito application to OpenShift, we can again use the Kogito Operator to provision the OpenShift resources our application requires:

BuildConfig:
1. In this guide we will be using a Binary Build, a build in which we locally build the application and push the built application to the OpenShift Build to be packaged into the runtime container image.
2. Kogito also supports S2I, or Source-to-Image, builds, which build the application in a Build on OpenShift and then pass the built application to the next OpenShift build to be packaged into the runtime container image.
ImageStream: an image stream comprises one or more container images identified by tags.
DeploymentConfig: describes the desired state of a of the Kogito application application as a Pod template.
Service: a Kubernetes internal load-balancer to serve the application Pods.
Route: exposes the Service at a hostname.

To deploy a Kogito service/application that supports binary builds, we can again use the Kogito Operator.

In a terminal, create a new Kogito Service for the kogito-travel-agency application using the following command:

kogito deploy-service kogito-travel-agency --install-infinispan=Always --install-kafka=Always -e MP_MESSAGING_OUTGOING_VISAAPPLICATIONS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_INCOMING_VISASAPPROVED_BOOTSTRAP_SERVERS= -e MP_MESSAGING_INCOMING_VISASREJECTED_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_PROCESSINSTANCES_EVENTS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_USERTASKINSTANCES_EVENTS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_VARIABLES_EVENTS_BOOTSTRAP_SERVERS=

Note

We specify the environment variables that we want the Operator to populate with the values of the current environment. In this case we specify the environment variables that configure the location of the Kafka bootstrap servers. When the Deployment Config of our service is created, the Operator will configure these environment variables to point to the location of the Kafka environment we deployed earlier.

Navigate to the Kogito Operator in the OpenShift console. Navigate to the Kogito Service tab. Click on the kogito-travel-agency CR.
Navigate to Builds → Build Configs, observe that a new kogito-travel-agency-binary BuildConfig has been created.

Go back to the terminal, and create a new Kogito Service for the kogito-visas application with the following command:

kogito deploy-service kogito-visas --install-infinispan=Always --install-kafka=Always -e MP_MESSAGING_INCOMING_VISAAPPLICATIONS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_VISASAPPROVED_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_VISASREJECTED_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_PROCESSINSTANCES_EVENTS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_USERTASKINSTANCES_EVENTS_BOOTSTRAP_SERVERS= -e MP_MESSAGING_OUTGOING_KOGITO_VARIABLES_EVENTS_BOOTSTRAP_SERVERS=

Navigate to the Kogito Operator in the OpenShift console. Navigate to the Kogito Service tab. Click on the kogito-visas CR.
Navigate to Builds → Build Configs, observe that a new kogito-visas-binary BuildConfig has been created.

Note	The Operator will dynamically create the `DeploymentConfig`, `Service` and `Route` for our applications when their first build has successfully completed.

Building the projects

Before we can deploy our application onto OpenShift, we first need to compile and build the binaries.

Note

Kogito provides an S2I, or Source-to-Image, build configuration that allows one to build the project directly from a Git repository on the OpenShift platform itself. In this guide however, we will be building our project locally to show the developer experience of working with a Kogito project on a development machine and pushing to the cloud.

Since the Kogito Travel Agency application is built on Quarkus, we provide 2 ways in which we can build and compile the project:

JDK-mode: This is a standard Maven build, and will package the application as a runner JAR and its dependencies (stored in a libs folder)
Native-mode: This mode requires the GraalVM and SubstrateVM frameworks to build and compile the application into a native executable for your system.

In this guide we will use the JDK-mode as the standard build mode. In the extra section of this guide we will discuss how to compile native executables of the application that are suitable for cloud deployments.

Kogito Travel Agency Application

Navigate to the 08-kogito-travel-agency directory: cd 08-kogito-travel-agency
Build the project using Maven with the following command: mvn clean package
Inspect the target folder that has been created: ls target (Linux/macOS) or dir target (Windows)

You should see the following output:

The directory contains, among other things:

kogito-travel-agency-1.0-SNAPSHOT.jar: containing just the classes and resources of the projects, it’s the regular artifact produced by the Maven build.
kogito-travel-agency-1.0-SNAPSHOT-runner.jar: being an executable jar. Be aware that it’s not an über-jar as the dependencies are copied into the target/lib directory.
lib: directory containing the project dependencies.

The runner JAR and the library directory are needed for the Kogito Travel Agency Binary Build on OpenShift. However, the Kogito Binary Build allows us to send the entire target directory to the builder image. The builder image will filter out the required assets to run and successfully complete the build.

From the 08-kogito-travel-agency directory, run the following command to push the artefacts to OpenShift and start the Binary Build of the application:

$ oc start-build kogito-travel-agency-binary --from-dir=target/

You will see the following output:

Uploading directory "target/" as binary input for the build ...
....
Uploading finished
build.build.openshift.io/kogito-travel-agency-1 started

Check the logs of the builder pod:

$ oc logs -f build/kogito-travel-agency-binary-1

Once your binary build is finished, it will push the result to the kogito-travel-agency ImageStream (the ImageStream that was created by the Operator), which will trigger a new deployment.
Navigate to Workloads → Deployment Configs → kogito-travel-agency. Observe that a new deployment is being provisioned.
Navigate to Networking → Routes. Click on the URL in the Location column of the kogito-travel-agency, which will bring you to the main page of the Kogito Travel Agency application.

Alternatively, the route of the application can also be retrieved via the oc client:

oc get route/kogito-travel-agency

Which will show an output similar to this:

NAME                   HOST/PORT                                                                                        PATH   SERVICES               PORT   TERMINATION   WILDCARD
kogito-travel-agency   kogito-travel-agency-kogito-travel-agency.apps.cluster-rdam-dbe2.rdam-dbe2.example.opentlc.com          kogito-travel-agency   http                 None

Kogito Visas Application

We can now do the same for the kogito-visas application.

Navigate to the 08-kogito-visas directory: cd 08-kogito-visas
Build the project using Maven with the following command: mvn clean package

After the Maven build has finished, run the following command to push the artefacts to OpenShift and start the Binary Build of the application:

$ oc start-build kogito-visas-binary --from-dir=target/

You will see the following output:

Output
Uploading directory "target/" as binary input for the build ...
....
Uploading finished
build.build.openshift.io/kogito-visas-1 started

Check the logs of the builder pod:

$ oc logs -f build/kogito-visas-binary-1

Once your binary build is finished, it will push the result to the kogito-visas ImageStream (the ImageStream that was created by the Operator), which will trigger a new deployment.
Navigate to Workloads → Deployment Configs → kogito-visas, Observe that a new deployment is being provisioned.
Navigate to Networking → Routes. Click on the URL in the Location column of the kogito-visas, which will bring you to the main page of the Kogito Travel Agency application.

Again, alternatively, the route of the application can also be retrieved via the oc client:

oc get route/kogito-visas

Which will show an output similar to this:

NAME           HOST/PORT                                                                                PATH   SERVICES       PORT   TERMINATION   WILDCARD
kogito-visas   kogito-visas-kogito-travel-agency.apps.cluster-rdam-dbe2.rdam-dbe2.example.opentlc.com          kogito-visas   http                 None

Running the Demo

In this section we will walk you through running the Kogito Travel Agency demo/tutorial you’ve just provisioned to OpenShift.

As stated earlier, the aim of the application is to book a trip to a certain destination, including flight and hotel. A ruleset defines whether a visa is required for the given destination. The visa approval logic is implemented by the kogito-visas service.

We will now walk through the end-to-end scenario in which a user books a trip to the United States, and requires a visa.

In the OpenShift Console, with your kogito-travel-agency project selected, navigate to Networking → Routes and click on the Location of the kogito-travel-agency application to navigate to the application’s UI.
Click on the + Plan new trip button to create a new trip.
Fill in the following details. To make sure that our trip requires a visa we set the Nationality to Polish and the destination Country of the trip to US:
The new trip will be shown in the UI. Note that this data is coming from the
In the new trip, click on the Tasks button to open the tasks of this process.
Click on the Apply button. In the next screen enter a random Passport number and a Duration of 40. Click on the Submit application button.
In the OpenShift Console, with your kogito-travel-agency project selected, navigate to Networking → Routes and click on the Location of the kogito-visas application to navigate to the application’s UI. You will see the visa application listed. Note that this process was started via a message sent through Apache Kafka from the Travel Agency application to the Visas application.
Click on the Approval button. In the pop-up form, click on the Approve button to approve the visa application.
Go back to the Kogito Travel Application, you will see that the visa has been approved:
Click on the Tasks button. In the pop-up, click on the Complete button.
The travel is now complete.

With the application completed, we can now inspect the data that created and stored by the DataIndex Service. In Kogito, the Data Index Service allows us to search on domain data. In the case of our application, we can therefore search, for example, for Travels and VisaApplications. Kogito also allows us to search for ProcessInstances and UserTaskInstances if we want to have a more technical view of the underlying processes and tasks.

Furthermore, the GraphQL interface also allows us to do complex, full-text, searches over our business data.

In the OpenShift Console, with your kogito-travel-agency project selected, navigate to Networking → Routes and click on the Location of the kogito-data-index application to navigate to the Graph_i_QL interface of the Data Index Service.

Use the following GraphQL query to retrieve details about our trip:

{ Travels {
  id, traveller {
    email
    firstName
    lastName
    nationality
  }, trip {
    begin
    city
    country
    end
    visaRequired
  }
}

We can also add a query that only retrieves with a lastName like Chop*.

{ Travels (where: {traveller: {lastName: {like: "Chop*"}}}) {
  id, traveller {
    email
    firstName
    lastName
    nationality
  }, trip {
    begin
    city
    country
    end
    visaRequired
  }
} }

Next, use the following query to retrieve the VisaApplications and their details:

{ VisaApplications {
  visaApplication {
    approved
    city
    country
    duration
    firstName
    lastName
    nationality
    passportNumber
  }
} }

Having looked at the domain data, we can now look at a more technical data via the ProcessInstances and UserTaskInstances.

Enter the following query in the Data Index Service UI to list all ProcessInstances:

{ ProcessInstances {
  id,
  processId,
  processName,
  state,
  nodes {
    name,
    type,
    enter,
    exit
  }
} }

To search for UserTaskInstances, we can use the following query:

{ UserTaskInstances {
  name,
  priority,
  processId,
  processInstanceId
} }

Conclusion

In this guide you’ve walked through the setup and provisioning of a Kogito application on OpenShift. You have seen how the Kogito Operator configures and manages the lifecycle of the Kogito infrastucture components and support services, like Infinispan (persistence), Apache Kafka (messaging) and the Data Index Service (search).

After compiling the two projects, you’ve used the Kogito Binary Build functionality to package the Kogito application in two containers on OpenShift.

Finally, you’ve run the full demo, demonstrating the process, rules, messaging, and search capabilities of cloud-native business automation with Kogito and Quarkus on OpenShift.

DuncanDoyle/kogito-openshift-getting-started-guide