Developing Workflow 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. |
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:
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
-
You have installed the SonataFlow Operator
-
You have created a new SonataFlow 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:
kubectl apply -f <your_file> -n <your_namespace>
Alternatively, you can try one of the examples available in the operator repository:
kubectl apply -f https://raw.githubusercontent.com/kiegroup/kogito-serverless-operator/v1.43.0/test/testdata/sw.kogito_v1alpha08_sonataflow_devmode.yaml -n <your_namespace>
Replace |
You can follow the Workflow status to check if everything is fine with:
kubectl get workflow -n <your_namespace> -w
You should see the Workflow conditions evolving to READY
in a few seconds:
NAME PROFILE VERSION ADDRESS READY REASON
greeting dev 0.0.1 False WaitingForDeployment
greeting dev 0.0.1 True
The |
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 VSCode, there are the commands needed:
curl -S https://raw.githubusercontent.com/kiegroup/kogito-serverless-operator/v1.43.0/config/samples/sw.kogito_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
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:
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
When running on Minikube, the service is already exposed for you via |
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:
{
"name": "Jane Doe"
}
You should see a result similar to this:
{
"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:
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:
# 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. |
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 conditionskubectl 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 logskubectl logs deployment/<workflow-name> -f
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.
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.
Found an issue?
If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!