OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Workflow eventing system

You can set up the eventing system for a SonataFlow workflow.

In a OpenShift Serverless Logic installation, the following types of events are generated:

  • Outgoing and incoming events related to workflow business logic.

  • Events sent from workflows to the Data Index and Job Service.

  • Events sent from the Job Service to the Data Index Service.

The OpenShift Serverless Logic Operator leverages the Knative Eventing system to manage all event communication between these services, ensuring efficient and reliable event handling.

Platform-scoped eventing system configuration

To configure a platform-scoped eventing system, you can use the spec.eventing.broker.ref field in the SonataFlowPlatform custom resource (CR) to reference a Knative Eventing broker.

This configuration instructs the OpenShift Serverless Logic Operator to automatically link every workflow deployed in the specified namespace, using the preview or gitops profile, to produce and consume events through the defined broker.

The supporting services deployed in the namespace without a custom eventing configuration are also linked to this broker.

In production environments, use a production-ready broker, such as the Knative Kafka Broker, for enhanced scalability and reliability.

The following example displays how to configure the SonataFlowPlatform CR for a platform-scoped eventing system:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: <example-namespace>
spec:
  eventing:
    broker:
      ref:
        name: example-broker (1)
        namespace: <example-broker-namespace> (2)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
1 Specifies the Knative Eventing Broker name.
2 Optional: Specifies the namespace of the Knative Eventing Broker. If you do not sepcify the value, then the parameter defaults to the namespace of the SonataFlowPlatform CR. Consider creating the broker in the same namespace as SonataFlowPlatform.

Workflow-scoped eventing system configuration

A workflow-scoped eventing system configuration allows for detailed customization of the events produced and consumed by a specific workflow. You can use the spec.sink.ref and spec.sources[] fields in the SonataFlow CR to configure outgoing and incoming events.

Outgoing eventing system configuration

To configure outgoing events, you can use the spec.sink.ref field in the SonataFlow CR. This configuration ensures the workflow produces events using the specified Knative Eventing Broker, including both system events and workflow business events.

The following example displays how to configure the SonataFlow CR for a workflow-scoped outgoing eventing system:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: example-workflow
  namespace: example-workflow-namespace
  annotations:
    sonataflow.org/description: Example Workflow
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: preview
spec:
  sink:
    ref:
      name: outgoing-example-broker (1)
      namespace: outgoing-example-broker-namespace (2)
      apiVersion: eventing.knative.dev/v1
      kind: Broker
  flow: (3)
    start: ExampleStartState
    events: (4)
      - name: outEvent1 (5)
        source: ''
        kind: produced
        type: out-event-type1 (6)
    ...
1 Name of the Knative Eventing Broker to use for all the events produced by the workflow, including the SonataFlow system events.
2 Defines the namespace of the Knative Eventing Broker. If you do not specify a value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as SonataFlow.
3 Flow definition field in the SonataFlow CR.
4 Events definition field in the SonataFlow CR.
5 Example of an outgoing event outEvent1 definition.
6 Event type for the outEvent1 outgoing event.

Incoming eventing system configuration

To configure incoming events, you can use the spec.sources[] field in the SonataFlow CR. You can add an entry for each event type requiring specific configuration. This setup allows workflows to consume events from different brokers based on event type.

If an incoming event type lacks a specific Broker configuration, the system applies eventing system configuration precedence rules.

The following example displays how to configure the SonataFlow CR for a workflow-scoped incoming eventing system:

The link between a spec.sources[] entry and the workflow event, is by using the event type.

 
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: example-workflow
  namespace: example-workflow-namespace
  annotations:
    sonataflow.org/description: Example Workflow
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: preview
spec:
  sources:
    - eventType: in-event-type1 (1)
      ref:
        name: incoming-example-broker1 (2)
        namespace: incoming-example-broker1-namespace (3)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
    - eventType: in-event-type2 (4)
      ref:
        name: incoming-example-broker2 (5)
        namespace: incoming-example-broker2-namespace (6)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
  flow: (7)
    start: ExampleStartState
    events: (8)
      - name: inEvent1 (9)
        source: ''
        kind: consumed
        type: in-event-type1 (10)
      - name: inEvent2 (11)
        source: ''
        kind: consumed
        type: in-event-type2 (12)
    ...
1 Configure the workflow to consume events of type in-event-type1 using the specified Knative Eventing Broker.
2 Name of the Knative Eventing Broker to use for the consumption of the events of type in-event-type1 sent to this workflow.
3 Optional: If you do not specify the value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as the SonataFlow workflow.
4 Configure the workflow to consume events of type in-event-type2 using the specified Knative Eventing Broker.
5 Name of the Knative Eventing Broker to use for the consumption of the events of type in-event-type2 sent to this workflow.
6 Optional: If you do not specify the value, the parameter defaults to the SonataFlow namespace. Consider creating the broker in the same namespace as the SonataFlow workflow.
7 Flow definition field in the SonataFlow CR.
8 Events definition field in the SonataFlow CR.
9 Example of an incoming event inEvent1 definition.
10 Event type for the incoming event inEvent1. The link of the workflow event, with the corresponding spec.sources[] entry, is by using the event type name in-event-type1.
11 Example of an incoming event inEvent2 definition.
12 Event type for the incoming event inEvent2. The link of the workflow event, with the corresponding spec.sources[] entry, is created by using the event type name in-event-type2.

Cluster-scoped eventing system configuration

In a SonataFlowClusterPlatform setup, workflows are automatically linked to the Broker specified in the associated SonataFlowPlatform CR. This linkage follows the Eventing System configuration precedence rules.

To ensure proper integration, you can configure Broker in the SonataFlowPlatform CR referenced by the SonataFlowClusterPlatform CR.

The following example displays how to configure the SonataFlowClusterPlatform CR and its reference to the SonataFlowPlatform CR:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: global-platform
  namespace: global-namespace
spec:
  eventing:
    broker:
      ref:
        name: global-broker
        namespace: global-namespace
        apiVersion: eventing.knative.dev/v1
        kind: Broker
---
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowClusterPlatform
metadata:
  name: cluster-platform-example
spec:
  platformRef:
    name: global-platform
    namespace: global-namespace
    ...

The SonataFlowClusterPlatform CR can refer to any SonataFlowPlatform CR that has already been deployed.

Eventing system configuration precedence rules

The OpenShift Serverless Logic Operator follows a defined order of precedence to determine the eventing system configuration for a workflow.

Eventing system configuration precedence rules are as follows:

  1. If the workflow has a defined eventing system by using either workflow-scoped outgoing or incoming eventing system configurations, the choice of configuration takes priority over the other configuration and applies to the workflow.

  2. If the SonataFlowPlatform CR enclosing the workflow has a platform-scoped eventing system configured, this configuration is then applied to the next step.

  3. If the current cluster is configured with a cluster-scoped eventing system, it is applied if no workflow-scoped or platform-scoped configuration exists.

  4. Review the following information, if none of the above configurations are defined:

    • The workflow uses direct HTTP calls to deliver SonataFlow system events to supporting services.

    • The workflow consumes incoming events by HTTP POST calls at the workflow service root path /.

    • No eventing system is configured to produce workflow business events. Any attempt to produce such events might result in a failure.

Linking workflows to the eventing system

The OpenShift Serverless Logic Operator links workflows with the eventing system using Knative Eventing, SinkBindings, and triggers. These objects are created automatically by the OpenShift Serverless Logic Operator and simplify the production and consumption of workflow events.

The following example shows the Knative Eventing objects created for an example-workflow workflow configured with a platform-scoped eventing system:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  eventing:
    broker:
      ref:
        name: example-broker (1)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
  services:
    dataIndex: (2)
      enabled: true
    jobService: (3)
      enabled: true
  ...
1 The example-broker object is used by the Data Index, Jobs Service, and the example-workflow workflow.
2 The Data Index is deployed with ephemeral configurations.
3 The Jobs Service is deployed with ephemeral configurations.

The example-broker object is a Kafka class Broker, and its configuration is defined in the kafka-broker-config config map.

The following example displays how to configure a Kafka Knative Broker for use with the SonataFlowPlatform:

apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  annotations:
    eventing.knative.dev/broker.class: Kafka (1)
  name: example-broker
  namespace: example-namespace
spec:
  config:
    apiVersion: v1
    kind: ConfigMap
    name: kafka-broker-config
    namespace: knative-eventing
1 The Kafka class is used to create the example-broker object.

The following example displays how the example-workflow is automatically linked to the example-broker in the example-namespace for event production and consumption:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: example-workflow
  namespace: example-namespace
  annotations:
    sonataflow.org/description: Example Workflow
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: preview
spec:
  flow:
    start: ExampleStartState
    events:
      - name: outEvent1
        source: ''
        kind: produced
        type: out-event-type1 (1)
      - name: inEvent1
        source: ''
        kind: consumed
        type: in-event-type1 (2)
      - name: inEvent2
        source: ''
        kind: consumed
        type: in-event-type2 (3)
    states:
      - name: ExampleStartState
    ...
1 The example-workflow outgoing events are produced by using the SinkBinding named example-workflow-sb.
2 Events of type in-event-type1 are consumed by using the example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11 trigger.
3 Events of type in-event-type2 are consumed by using the example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11 trigger.

You can list the automatically created SinkBinding named example-workflow-sb by using the following command:

$ oc get sinkbindings -n example-namespace
Example output
NAME                   TYPE          RESOURCE                           SINK                    READY
example-workflow-sb    SinkBinding   sinkbindings.sources.knative.dev   broker:example-broker   True

You can use the following command to list the automatically created triggers for event consumption:

$ oc get triggers -n <example-namespace>
Example output
NAME                                                              BROKER           SINK                                                     AGE   CONDITIONS   READY   REASON
example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11    example-broker   service:example-workflow                                 16m   7 OK / 7     True
example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11    example-broker   service:example-workflow                                 16m   7 OK / 7     True