Deploying your SonataFlow application on OpenShift

This document describes how to deploy a SonataFlow application using a OpenShift cluster, along with a procedure to run the OpenShift Serverless Operator, which is based on Knative.

Prerequisites

For the following steps we will be using the OpenShift Local. However, the steps described here can be used on any OpenShift 4.x version that has support for OpenShift Serverless.

Installing OpenShift Local

If you already have an OpenShift cluster available you can skip this section.

Instructions to install Openshift Local can be found here.

Once you have OpenShift Local running, proceed to the next topic.

If you are running OpenShift Local on Mac with M1 processors, you might not find the OpenShift Serverless Operator available.

Before proceeding further, make sure that you have access to the OpenShift cluster, the OpenShift Serverless operator is properly installed and the Knative Serving is ready for use. For more information on each topic, please refer the following guides:

If you get error messages related to Istio, this article might be helpful.

Deploying your workflow application on OpenShift

Once Knative Serving is ready, you can initiate the process of deploying your SonataFlow application on OpenShift.

Prerequisites

After checking the prerequisites, prepare the project that will be used to deploy your application:

Procedure

  1. Create project

    oc new-project kogito-serverless

  2. Set the Kubernetes context to the newly created namespace using the following command:

    Set OpenShift current project
    oc project kogito-serverless

You can use the native image for a faster startup.

Preparing the OpenShift’s Registry

OpenShift comes with a registry where you can push your images built locally to be deployed.

First, let’s check if the Registry is already exposed, to do that, check if the route is exposed:

Check whether the OpenShift registry is exposed
oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}'

If no information or an error is returned, it does mean that the registry is not exposed. To expose the registry follow these steps.

Now that we have the OpenShift registry exposed, let’s store into the OPENSHIFT_REGISTRY_URL environment variable, so we can use it easily in the next steps:

Retrieve the OpenShift registry
OPENSHIFT_REGISTRY_URL=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')

The OpenShift’s registry requires you to be logged in to be allowed to push Container Images. If you are already logged in the cluster you can use your token to authenticate to the OpenShift’s registry:

Log in to the OpenShift’s registry
podman login -u <USERNAME> -p $(oc whoami -t) --tls-verify=false $OPENSHIFT_REGISTRY_URL

If everything is working, you should get the Login Succeeded! message.

Pushing SonataFlow Application To OpenShift’s registry

First step, get the Container Image tag built previously:

podman images

With the Container Image, use the following command to tag the application image with the OpenShift’s registry and the namespace being used:

podman tag <IMAGE_TAG> $OPENSHIFT_REGISTRY_URL/kogito-serverless/serverless-workflow-greeting-quarkus:1.0

Then, push:

podman push $OPENSHIFT_REGISTRY_URL/kogito-serverless/serverless-workflow-greeting-quarkus:1.0

The kogito-serverless is the current project/namespace created earlier to deploy your SonataFlow application.

The next step is to deploy your workflow application and execute it. You can read further the next sections which explain different approaches to deploy your SonataFlow application:

In the next steps you will notice the value image-registry.openshift-image-registry.svc:5000 being used. It is the internal OpenShift’s registry address where the images of the deployments will pulled from. Note that, the Container Image pushed in the previous step will be queried as image-registry.openshift-image-registry.svc:5000/kogito-serverless/serverless-workflow-greeting-quarkus:1.0

Deploying your workflow application using Knative CLI

Once you have pushed your workflow application into the OpenShift’s registry, you can use the command-line tools, such as Knative CLI or OpenShift CLI to initiate the deployment process.

Prerequisites
Procedure

  1. In a command terminal, execute the following command to deploy your workflow application using Knative CLI:

    Example of deploying workflow application using Knative CLI
    kn service create hello-workflow \
    --image=image-registry.openshift-image-registry.svc:5000/kogito-serverless/serverless-workflow-greeting-quarkus:1.0 \
    --pull-policy=IfNotPresent \
    --port 8080
    Example output
    Creating service 'hello-workflow' in namespace 'serverless-workflow-greeting-quarkus':

  0.066s The Route is still working to reflect the latest desired specification.
  0.099s ...
  0.322s Configuration "hello-workflow" is waiting for a Revision to become ready.
  4.885s ...
  5.061s Ingress has not yet been reconciled.
  5.322s Waiting for load balancer to be ready
  5.460s Ready to serve.

Service 'hello-workflow' created to latest revision 'hello-workflow-00001' is available at URL:
http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io

Depending on the cluster type where you have deployed the workflow application, the service URL might be different. Pay attention to the output to use the correct URL in the next topic.

Verify if the workflow application is deployed correctly:

  • On OpenShift CLI

  • On Knative CLI

oc get services.serving.knative.dev hello-workflow
kn service list hello-workflow
Example output
NAME             URL                                                                                LATEST                 AGE    CONDITIONS   READY   REASON
hello-workflow   http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io   hello-workflow-00001   7m6s   3 OK / 3     True
Use the URL in the output to send request to your workflow application.
Example request
curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"name": "John", "language": "English"}' http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet
Example response
{"id":"0f77abce-837e-4bd2-b4f1-a0e5e0265fcb","workflowdata":{"name":"John","language":"English","greeting":"Hello from JSON Workflow, "}}

Deploying your workflow application using OpenShift CLI

You can also use oc command-line interface and plain Kubernetes objects to deploy your workflow application.
And, instead of creating knative yaml|json descriptors, you can leverage the Quarkus Kubernetes extension and Kogito Knative add-on to generate the descriptors.

Prerequisites

  • Kogito Workflow application ready to use.

  • OpenShift CLI command-line tool is installed.

  • (Optional) Quarkus CLI is installed
    For more information about installing the Quarkus CLI, see Installing the Quarkus CLI.

Procedure

  1. Add the Quarkus extensions to generate knative yaml|json descriptors.

    To use the Quarkus Kubernetes extension and Kogito Knative add-on, ensure that the following dependencies are available in the pom.xml file and Gradle:

    • pom.xml

    • Gradle

    • Quarkus CLI

    <dependency>
  <groupId>org.kie.kogito</groupId>
  <artifactId>kogito-addons-quarkus-knative-eventing</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-openshift</artifactId>
</dependency>
    quarkus-kubernetes 'io.quarkus:quarkus-openshift:2.16.10.Final'
quarkus-kubernetes 'org.kie.kogito:kogito-addons-quarkus-knative-eventing:main'
    quarkus ext add org.kie.kogito:kogito-addons-quarkus-knative-eventing quarkus-openshiftmain'

  2. To generate the knative yaml|json descriptors, set the following properties in the application.properties file of your workflow application:

    System properties to generate knative descriptors
    quarkus.kubernetes.deployment-target=knative
quarkus.knative.name=hello-workflow

  3. Build your workflow application.

    Once you have built your application, you can find the generated descriptors files in the target/kubernetes directory:

    • knative.json

    • knative.yml

    The image used in this section is the one built in the following guide: Build Workflow Image with Quarkus CLI.

    Following is an example of the generated files:

    Knative descriptor example for a workflow application
    ---
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    app.quarkus.io/commit-id: 06c3fe8e2dfc42e2211cbcc41224f5a3d6bd1f26
    app.quarkus.io/build-timestamp: 2022-06-23 - 23:53:38 +0000
  labels:
    app.kubernetes.io/name: hello-workflow
  name: hello-workflow
spec:
  template:
    metadata:
      labels:
        app.kubernetes.io/name: hello-workflow
    spec:
      containerConcurrency: 0
      containers:
        - image: image-registry.openshift-image-registry.svc:5000/kogito-serverless/serverless-workflow-greeting-quarkus:1.0-native
          livenessProbe:
            failureThreshold: 3
            httpGet:
              path: /q/health/live
              port: null
              scheme: HTTP
            initialDelaySeconds: 0
            periodSeconds: 30
            successThreshold: 1
            timeoutSeconds: 10
          name: hello-workflow
          ports:
            - containerPort: 8080
              name: http1
              protocol: TCP
          readinessProbe:
            failureThreshold: 3
            httpGet:
              path: /q/health/ready
              port: null
              scheme: HTTP
            initialDelaySeconds: 0
            periodSeconds: 30
            successThreshold: 1
            timeoutSeconds: 10

    Once the files are generated, you must add the imagePullPolicy manually before deploying the workflow application.

  4. Enter the following command to deploy the workflow application using oc:

    Deploy the workflow application using oc
    oc apply -f target/kubernetes/knative.yml

Verify if the workflow application is deployed correctly:

  • On OpenShift CLI

  • On Knative CLI

oc get services.serving.knative.dev hello-workflow
kn service list hello-workflow
Example output
NAME             URL                                                                                LATEST                 AGE    CONDITIONS   READY   REASON
hello-workflow   http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io   hello-workflow-00001   7m6s   3 OK / 3     True
Use the URL in the output to send request to your workflow application.
Example request
curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"name": "John", "language": "English"}' http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet
Example response
{"id":"0f77abce-837e-4bd2-b4f1-a0e5e0265fcb","workflowdata":{"name":"John","language":"English","greeting":"Hello from JSON Workflow, "}}

Deploying your workflow application using Quarkus CLI

Prerequisites
Procedure

  1. Add the Quarkus extensions to deploy the knative service.

    You can add the OpenShift and the Kogito Knative extensions to your project with the Quarkus CLI:

    Add OpenShift and Kogito Knative extensions to the project with Quarkus CLI
    quarkus ext add quarkus-openshift kogito-addons-quarkus-knative-eventing

  2. To deploy the workflow application using Quarkus CLI, set the following system properties in application.properties file:

    Required system properties
    quarkus.knative.name=hello-workflow (1)
quarkus.kubernetes.deployment-target=knative (2)
quarkus.kubernetes.deploy=true (3)
quarkus.container-image.push=true (4)
quarkus.container-image.group=kogito-serverless (5)
quarkus.container-image.registry=image-registry.openshift-image-registry.svc:5000 (6)
quarkus.container-image.tag=1.0-SNAPSHOT (7)
    1 Property to set the Knative service name
    2 Property to set the target deployment type
    3 Property to set whether or not deploy on an active OpenShift cluster
    4 This property should be removed if deploying on OpenShift Clusters
    5 Property to define which registry group/namespace the built image belongs to
    6 Property to define to which registry the built image will be pushed to
    7 Sets the built Container Image tag

    This feature works with Quarkus 2.10.2.Final or later. For more information, see link.
Build and Deploy your workflow application
quarkus build -DskipTests

The kogito-examples already have this extension added by default, and can be activated with the container Maven profile.

Verify if the workflow application is deployed correctly:

  • On OpenShift CLI

  • On Knative CLI

oc get services.serving.knative.dev hello-workflow
kn service list hello-workflow
Example output
NAME             URL                                                                                LATEST                 AGE    CONDITIONS   READY   REASON
hello-workflow   http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io   hello-workflow-00001   7m6s   3 OK / 3     True
Use the URL in the output to send request to your workflow application.
Example request
curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"name": "John", "language": "English"}' http://hello-workflow.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet
Example response
{"id":"0f77abce-837e-4bd2-b4f1-a0e5e0265fcb","workflowdata":{"name":"John","language":"English","greeting":"Hello from JSON Workflow, "}}

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!