Knative Eventing

This document describes how to configure workflows, and the supporting services, to use Knative Eventing as the preferred eventing system.

In general, the following events are produced in a SonataFlow installation:

  • Workflow outgoing and incoming business events.

  • SonataFlow system events sent from the workflow to the Data Index and Job Service respectively.

  • SonataFlow system events sent from the Jobs Service to the Data Index Service.

The content of this guide must be used only when you work with workflows using the preview and gitops profiles.

To produce a successful configuration you must follow this procedure:

1. Prerequisite

  1. The SonataFlow Operator is installed. See Install the SonataFlow Operator guide.

  2. The Knative Eventing system is installed and property initiated in the cluster.

2. Configuring the Knative Broker

Create a Knative Broker to define the event mesh to collect the events with a resource like this:

apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  name: default
  namespace: example-namespace

For more information on Knative Brokers see.

The example creates an in-memory broker for simplicity. In production environments, you must use a production-ready broker, like the Knative Kafka broker.

Finally, to get the Broker URL that is needed in the next steps of the configuration, you can execute the following command:

kubectl get broker -n example-namespace

NAME      URL                                                                     AGE     READY   REASON
default   http://broker-ingress.knative-eventing.svc.cluster.local/example-namespace/default   4m50s   True

For a Knative Kafka broker that the URL will look like this instead.

http://kafka-broker-ingress.knative-eventing.svc.cluster.local/example-namespace/default

3. Configuring the Data Index Knative Eventing Resources

3.1. Workflows to DataIndex system events

Create the following Knative Triggers to deliver all the SonataFlow system events sent from the workflows to the Data Index Service:

In your installation you might have to adjust the spec.broker, the spec.subscriber.ref.name, and spec.subscriber.ref.namespace fields to use the correct names for every trigger.

For more information on Knative Triggers see.

Process definition events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-def-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessDefinitionEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /definitions
Process instance state events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-state-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessInstanceStateDataEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /processes
Process instance node events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-node-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessInstanceNodeDataEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /processes
Process instance error events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-error-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessInstanceErrorDataEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /processes
Process instance SLA events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-sla-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessInstanceSLADataEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /processes
Process instance variable events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-process-variable-trigger
spec:
  broker: default
  filter:
    attributes:
      type: ProcessInstanceVariableDataEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /processes

3.2. Job Service to Data Index system events

Create the following Knative Trigger to deliver all the SonataFlow system events sent from the Job Service to the Data Index Service:

In your installation you might have to adjust the spec.broker, the spec.subscriber.ref.name, and spec.subscriber.ref.namespace fields to use the correct names for every trigger.

For more information on Knative Triggers see.

Job events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-data-index-service-jobs-trigger
spec:
  broker: default
  filter:
    attributes:
      type: JobEvent
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-data-index-service
      namespace: example-namespace
    uri: /jobs

4. Configuring the Job Service Knative Eventing Resources

Create the following Knative Triggers to deliver all the SonataFlow system events produced by the workflows to the Job Service:

In your installation you might have to adjust the spec.broker, the spec.subscriber.ref.name, and spec.subscriber.ref.namespace fields to use the correct names for every trigger.
Create Job events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: sonataflow-platform-jobs-service-create-job-trigger
spec:
  broker: default
  filter:
    attributes:
      type: job.create
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-jobs-service
      namespace: example-namespace
    uri: /v2/jobs/events
Delete Job events trigger
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: jobs-service-postgresql-delete-job-trigger
  namespace: example-namespace
spec:
  broker: default
  filter:
    attributes:
      type: job.delete
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: sonataflow-platform-jobs-service
      namespace: example-namespace
    uri: /v2/jobs/events

5. Data Index and Job Service installation

To deploy these services you must use a SonataFlowPlatform CR and configure it according to the Supporting Services guide. Finally, prior to deployment into the cluster, you must add the env variable shown below to the field spec.jobService.podTemplate.container.

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform
  namespace: example-namespace
spec:
  services:
    dataIndex:
      # Data Index requires no additional configurations to use knative eventing.
      # Use the configuration of your choice according to the Supporting Services guide.
    jobService:
      podTemplate:
        container:
          env:
            - name: MP_MESSAGING_OUTGOING_KOGITO_JOB_SERVICE_JOB_STATUS_EVENTS_HTTP_URL (1)
              value: http://broker-ingress.knative-eventing.svc.cluster.local/example-namespace/default (2)
1 Fixed env variable name that contains the URL of the Broker created in Configuring the Knative Broker.
2 To query the Broker URL see.

6. Workflow configuration

6.1. SonataFlow CR configuration

To configure a workflow you must create a SonataFlow CR that fulfills your requirements. And finally, prior to deployment into the cluster, add the env variables shown below to the field spec.podTemplate.container.

Workflow configuration
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: example-workflow
  namespace: example-namespace
  annotations:
    sonataflow.org/description: Example Workflow that show Knative Eventing configuration.
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: preview
spec:
  podTemplate:
    container:
      env:
        - name: K_SINK (1)
          value: http://broker-ingress.knative-eventing.svc.cluster.local/example-namespace/default (2)
        - name: MP_MESSAGING_OUTGOING_KOGITO_JOB_SERVICE_JOB_REQUEST_EVENTS_URL
          value: ${K_SINK}
        - name: MP_MESSAGING_OUTGOING_KOGITO_PROCESSINSTANCES_EVENTS_URL
          value: ${K_SINK}
        - name: MP_MESSAGING_OUTGOING_KOGITO_PROCESSDEFINITIONS_EVENTS_URL
          value: ${K_SINK}
  flow:
    start: ExampleState
    events:
      - name: exampleConsumedEvent1
        source: ''
        type: example_event_1 (3)
        kind: consumed
      - name: exampleConsumedEvent2
        source: ''
        type: example_event_2 (4)
        kind: consumed
1 Fixed env variable name that contains the URL of the broker created in Configuring the Knative Broker.
2 Must contain the broker URL. To get this value see. The remaining env variables are fixed configurations, and you must add them as is.
3 Every consumed event requires a trigger, see.
4 Every consumed event requires a trigger, see.

6.2. Configuring the Workflow Knative Eventing Resources

For every event type consumed by the workflow you must create a corresponding trigger to deliver it from the broker.

Unlike the triggers related to the Data Index Service and the Jobs Service, these triggers must be created for every workflow that consume events. So it’s recommended that you use trigger names that are linked to the workflow name.
Trigger to consume events of type example_event_1
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: example-workflow-example-event-1-trigger (1)
spec:
  broker: default
  filter:
    attributes:
      type: example_event_1 (2)
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: example-workflow
      namespace: example-namespace
1 Name for the trigger.
2 Event type consumed by the workflow example-workflow.
Trigger to consume events of type example_event_2
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: example-workflow-example-event-2-trigger (1)
spec:
  broker: default
  filter:
    attributes:
      type: example_event_2
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: example-workflow
      namespace: example-namespace

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!