Developing Workflow Services with the Operator

This document describes how you can develop your workflows directly on Kubernetes with the Kogito Serverless Workflow Operator.

Workflows in development profile are not tailored for production environments. To build and deploy an immutable workflow application with the operator, see Building and Deploying Workflows with the Operator.

Kogito Serverless Workflow Operator is under active development with features yet to be implemented. Please see Kogito Serverless Workflow Operator Known Issues, Limitations and Roadmap.

Introduction to the Development Profile

The development profile is the easiest way to start playing around with workflows and the operator.

To get started, you can use an editor of your choice to create a new KogitoServerlessWorkflow Custom Resource YAML definition. For example:

Example of a Kubernetes Kogito Serverless Workflow YAML definition

apiVersion: sw.kogito.kie.org/v1alpha08
kind: KogitoServerlessWorkflow
metadata:
  name: greeting
  annotations:
    sw.kogito.kie.org/description: Greeting example on k8s!
    sw.kogito.kie.org/version: 0.0.1
    sw.kogito.kie.org/profile: dev (1)
spec: (2)
  start: ChooseOnLanguage
  functions:
    - name: greetFunction
      type: custom
      operation: sysout
  states:
    - name: ChooseOnLanguage
      type: switch
      dataConditions:
        - condition: "${ .language == \"English\" }"
          transition: GreetInEnglish
        - condition: "${ .language == \"Spanish\" }"
          transition: GreetInSpanish
      defaultCondition: GreetInEnglish
    - name: GreetInEnglish
      type: inject
      data:
        greeting: "Hello from JSON Workflow, "
      transition: GreetPerson
    - name: GreetInSpanish
      type: inject
      data:
        greeting: "Saludos desde JSON Workflow, "
      transition: GreetPerson
    - name: GreetPerson
      type: operation
      actions:
        - name: greetAction
          functionRef:
            refName: greetFunction
            arguments:
              message:  ".greeting+.name"
      end: true

1	The annotation `sw.kogito.kie.org/profile: dev` tells the operator to deploy your workflow using the development profile. This means that the operator will build a running instance of the workflow ready to receive changes during your development cycle.
2	In the `spec` attribute goes the workflow definition as described by the CNCF Serverless Workflow specification. So if you already have a workflow definition, you can use it there. Alternatively, you can use the editors to create your workflow definition.

Deploying a New Workflow Service

Prerequisites

You have installed the Kogito Serverless Workflow Operator
You have created a new Kogito Serverless Workflow Kubernetes YAML file

Having a new Kubernetes workflow definition in a YAML file (you can use the above example), you can deploy it in your cluster with the following command:

Deploying a new KogitoServerlessWorkflow custom resource in Kubernetes

kubectl apply -f <your_file> -n <your_namespace>

Alternatively, you can try one of the examples available in the operator repository:

Deploying the greeting workflow example

kubectl apply -f https://raw.githubusercontent.com/kiegroup/kogito-serverless-operator/main/config/samples/sw.kogito_v1alpha08_kogitoserverlessworkflow_devmode.yaml -n <your_namespace>

Replace <your_namespace> with the namespace you’re using to deploy your applications

You can follow the workflow status to check if everything is fine with:

Checking the workflow status

kubectl get workflow -n <your_namespace> -w

You should see the workflow conditions evolving to READY in a few seconds:

Example workflow deployment status

NAME       PROFILE   VERSION   ADDRESS   READY   REASON
greeting   dev       0.0.1               False   WaitingForDeployment
greeting   dev       0.0.1               True

The REASON field gives you a cue about the current workflow status.

You can make changes to the workflow YAML using any Kubernetes editor. For example you can use kubectl and the following commanda:

kubectl edit workflow/greeting -n <your_namespace>

and changing the workflow definition inside the CustomResource Spec section.

Otherwhise you can save the CustomResource definition file and edit it with your desired editor and re-applying it.

For example using VSCode, there are the commands needed:

curl -S https://raw.githubusercontent.com/kiegroup/kogito-serverless-operator/main/config/samples/sw.kogito_v1alpha08_kogitoserverlessworkflow_devmode.yaml > workflow_devmode.yaml
code workflow_devmode.yaml
kubectl apply -f workflow_devmode.yaml -n <your_namespace>

The operator ensures that the latest workflow definition is running and ready. This way, you can include the workflow application in your development scenario and start making requests to it.

Check the workflow application is running

In order to check that the Kogito Serverless Workflow Greeting application is up and running, you can try to perform a test HTTP call. First, you must expose the service:

Exposing the workflow application

kubectl patch svc greeting -n <your_namespace> -p '{"spec": {"type": "NodePort"}}'
minikube service greeting -n <your_namespace> --url
http://127.0.0.1:57053

# use the above output to get the current workflow URL in your environment

Alter exposing the workflow service, you can point your browser to the Swagger UI and start making requests with the REST interface.

For example, using the above command execution you can access the Swagger UI via http://127.0.0.1:57053/q/swagger-ui/.

At the Swagger UI, click on "POST /greeting", then on "Try it out!". Copy the following JSON message and hit execute:

Operation Greeting result

{
  "name": "Jane Doe"
}

Figure 1. The Swagger UI executing the POST /greeting operation

You should see a result similar to this:

Operation Greeting result

{
  "id": "984b5c6c-36ef-48ba-aa11-89fa54d25e98",
  "workflowdata": {
    "name": "Jane Doe",
    "greeting": "Hello from JSON Workflow, "
  }
}

You can even make changes to your KogitoServerlessWorkflow YAML file and see the results using the Swagger UI.

Troubleshooting the Workflow Service

Since during development you are iterating over the deployed workflow service, it’s likely that you will need to troubleshoot the application if something goes wrong.

To ensure the workflow is running in a healthy state, the operator deploys the application pod with health checks probes. So if your changes impact the application somehow, the pod will stop responding.

Basic Troubleshooting

Analyze the workflow status with:
Get the workflow status conditions
```
kubectl get workflow <name> -o jsonpath={.status.conditions} | jq .
```
It can give you a clue about what might be happening. See Understanding Workflow Services Status Conditions for more information.
Fetch the logs and look for ERROR messages:
Watch the application logs
```
kubectl logs deployment/<workflow-name> -f
```
If you are looking for opening an issue or ask in Kogito Serverless Workflow communication channels, this logging information is always useful for the person who will try to help you.

Possible Failure Scenarios

Feature Not Yet Supported

The Kogito Serverless Workflow Operator is under active development. Sometimes a feature might not be available yet. Please see Kogito Serverless Workflow Operator Known Issues, Limitations and Roadmap for a comprehensive list of available features.

If you identify you’re refering to a feature not yet available, please file a new issue so we can prioritize it for you or ask in Kogito Serverless Workflow communication channels.

Wrong Application Configuration

A wrong configuration, or lack of one might impact your workflow to run correctly. The operator deploys a ConfigMap that holds the application properties for the workflow.

Get the properties ConfigMap

kubectl get cm <workflow-name>-props

The ConfigMap name pattern is the workflow name followed by -props.

Make sure that the configuration is correct and you’re not lacking any required properties for a given feature to work. If so, you can make your changes to the configuration as you normally would to any ConfigMap.

The operator ensures that these properties are applied to the application.

See Configuring Workflow Services for more information.

Wrong Workflow Definition

The Kogito Serverless Workflow Operator validates the workflow definition at the moment you create or edit the YAML file, avoiding to persist a workflow in an invalid state. Although, the operator is under active development, so errors during the validation might occur.

In this case, you might have to make a few modifications to the workflow definition to fix any structural error.

You can identify such problems by looking at the deployed workflow application logs as explained here.

If you found an issue that a cause is not listed in this section, please let us know.

Additional resources

Found an issue?

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