Developing Workflows with the Operator

This document describes how you can develop your Workflows directly on Kubernetes with the SonataFlow Operator.

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

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

Prerequisites

You have set up your environment according to the minimal environment setup guide.
You have the cluster instance up and running. See starting the cluster for local development guide.

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 SonataFlow Custom Resource YAML definition. For example:

Example of a Kubernetes SonataFlow YAML definition

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: greeting
  annotations:
    sonataflow.org/description: Greeting example on k8s!
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: dev (1)
spec:
  flow: (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 `sonataflow.org/profile: dev` tells the operator to deploy the 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 `flow` 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

Prerequisites

You have a new SonataFlow Kubernetes Workflow definition in YAML file. You can use the Greeting example in introduction to development profile section.

Having a Kubernetes Workflow definition in a YAML file , you can deploy it in your cluster with the following command:

Deploying a new SonataFlow 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/apache/incubator-kie-kogito-serverless-operator/main/test/testdata/sonataflow.org_v1alpha08_sonataflow_devmode.yaml -n <your_namespace>

Replace <your_namespace> with the Namespace you’re using to deploy your workflows

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 command:

kubectl edit workflow/greeting -n <your_namespace>

and changing the Workflow definition inside the Custom Resource Spec section.

Alternatively, you can save the Custom Resource definition file and edit it with your desired editor and re-apply it.

For example using VS Code, these are the commands needed:

curl -S https://raw.githubusercontent.com/apache/incubator-kie-kogito-serverless-operator/main/test/testdata/sonataflow.org_v1alpha08_sonataflow_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 in your development scenario and start making requests to it.

Check if the Workflow is running

Prerequisites

You have deployed a workflow to your cluster following the example in deploying new workflow section.

In order to check that the SonataFlow Greeting workflow is up and running, you can try to perform a test HTTP call. First, you must get the service URL:

Exposing the workflow

Minikube

Expose the workflow on minikube

# Input
minikube service greeting -n <your_namespace> --url

# Example output, use the URL as a base to acces the current workflow
http://127.0.0.1:57053

# Your workflow is accessible at http://127.0.0.1:57053/greeting

Kind

Expose the workflow on kind

# Find the service of your workflow
kubectl get service -n <namespace>

# Example output
NAME            TYPE       CLUSTER-IP EXTERNAL-IP PORT(S)  AGE
greetings    ClusterIP    10.96.0.1    <none>    31852/TCP  21h

# Now forward the port and keep the terminal window open
kubectl port-forward service/greeting 31852:80 -n <namespace>

# Your workflow is accessible at localhost:31852/greetings

When running on Minikube, the service is already exposed for you via NodePort.
On OpenShift, a Route is automatically created in devmode.
If you’re running on Kubernetes you can expose your service using an Ingress.

You can now 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 SonataFlow YAML file and see the results using the Swagger UI.

Remove the Workflow

In order to remove the SonataFlow Greeting, you can execute the following command:

Removing the Workflow

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

Referencing resources in the Workflow

See the Referencing Additional Files in the Workflow guide for more complex scenarios where you may need to reference other resources in the workflow definition.

Using another Workflow base image

If your scenario has strict policies for image usage, such as security or hardening constraints, you can replace the default image used by the operator. Alternatively, you might want to test a nightly build with a bug fix or a custom image containing your customizations.

By default, the operator will use the image distributed upstream to run the workflows in the development profile. You can change this image by editing the SonataFlowPlatform custom resource in the namespace where you deployed your workflows:

Patching the current SonataFlowPlatform with the new image

# use `kubectl get sonataflowplatform` to get the SonataFlowPlatform name
kubectl patch sonataflowplatform <name> --patch  'spec:\n devMode:\n    baseImage: <your new image full name with tag>' -n <your_namespace>

From now on, every deployment in the development profile will use this image to run the workflow.

The default image was created to run a Quarkus Java application in dev mode. You can replace this image with another one as long as it has the same concept. One way of doing this is using the default as the base image. See Building a Custom Development Image.

Troubleshooting the Workflow

As you make changes to your workflow during development, it’s likely that you will need to troubleshoot it when something goes wrong.

To ensure the Workflow is running in a healthy state, the operator deploys its Pod with health check probes. If the changes you make to your Workflow cause the health checks to fail, the Pod executing the Workflow will stop responding.

The following will help you discover the reason for any failure during development.

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 workflow logs
```
kubectl logs deployment/<workflow-name> -f -n <your_namespace>
```
If you decide to open an issue or ask for help in SonataFlow 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 SonataFlow Operator is under active development. Sometimes a feature might not be available yet. Please see SonataFlow Operator Known Issues, Limitations and Roadmap for a comprehensive list of available features.

If you identify that you are attempting to use a feature that is not available yet, you can file a new issue, so we can prioritize it. Alternatively, you can ask in SonataFlow communication channels.

Wrong Workflow Configuration

A wrong configuration (or lack of one) might prevent your Workflow from running correctly. The operator deploys a ConfigMap that holds the workflow 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 missing any required properties for a given feature to work. You can make any changes to the configuration by simply editing the content of the ConfigMap.

Once you have updated the configuration in the ConfigMap, the operator ensures that these properties are applied to the workflow.

See Configuring Workflow Services for more information.

Wrong Workflow Definition

The SonataFlow Operator validates the Workflow definition at the moment you create or edit the YAML file, preventing you from creating an invalid workflow. As the operator is under active development, errors during the validation might occur.

In the case where validation has not prevented your error, you might have to make a few modifications to the Workflow definition to fix any problems.

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

If you find an issue with 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!