- Kogito on OpenShift: Getting Started Guide
- Problem Statement
- OpenShift Environment
- Install the Kogito Operator
- 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
- 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
-
Deploy an advanced Kogito application, including supporting services and infrastructure.
-
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:-
Kogito Operator:
-
Infinispan Operator: provides persistence infrastructure to Kogito applications and support services.
-
Strimzi Operator: provides messaging infrastructure to Kogito applications.
-
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 sameKogitoInfra
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.
NoteIt 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 sameKogitoInfra
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:
-
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.
-
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=
NoteWe 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 |
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) ordir 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 thetarget/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 thekogito-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 toUS
: -
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 of40
. 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 thekogito-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 thekogito-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
likeChop*
.{ 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.