Skip to content

Commit f6f91d0

Browse files
xenolinuxxenolinux
authored
Merge pull request #85644 from kaldesai/SRVLOGIC-481-Part1-subtask
PR for SRVLOGIC-481: Document "workflow eventing system" section in the Serverless Logic product docs
2 parents 1488c6d + 5a8f924 commit f6f91d0

7 files changed

+372
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,8 @@ Topics:
394394
File: serverless-logic-managing-supporting-services
395395
- Name: Managing workflow persistence
396396
File: serverless-logic-managing-persistence
397+
- Name: Workflow eventing system
398+
File: serverless-logic-workflow-eventing-system
397399
---
398400
# Knative kn CLI
399401
Name: Knative CLI

‎modules/serverless-logic-cluster-scoped-eventing-system-config.adoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-workflow-eventing-system
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="serverless-logic-cluster-scoped-eventing-system-config_{context}"]
6+
= Cluster-scoped eventing system configuration
7+
8+
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.
9+
10+
To ensure proper integration, you can configure `Broker` in the `SonataFlowPlatform` CR referenced by the `SonataFlowClusterPlatform` CR.
11+
12+
The following example displays how to configure the `SonataFlowClusterPlatform` CR and its reference to the `SonataFlowPlatform` CR:
13+
14+
[source,yaml]
15+
----
16+
apiVersion: sonataflow.org/v1alpha08
17+
kind: SonataFlowPlatform
18+
metadata:
19+
name: global-platform
20+
namespace: global-namespace
21+
spec:
22+
eventing:
23+
broker:
24+
ref:
25+
name: global-broker
26+
namespace: global-namespace
27+
apiVersion: eventing.knative.dev/v1
28+
kind: Broker
29+
---
30+
apiVersion: sonataflow.org/v1alpha08
31+
kind: SonataFlowClusterPlatform
32+
metadata:
33+
name: cluster-platform-example
34+
spec:
35+
platformRef:
36+
name: global-platform
37+
namespace: global-namespace
38+
...
39+
----
40+
41+
[NOTE]
42+
====
43+
The `SonataFlowClusterPlatform` CR can refer to any `SonataFlowPlatform` CR that has already been deployed.
44+
====

‎modules/serverless-logic-eventing-system-config-precedence-rule.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-workflow-eventing-system
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="serverless-logic-eventing-system-config-precedence-rule_{context}"]
6+
= Eventing system configuration precedence rules
7+
8+
The {ServerlessLogicOperatorName} follows a defined order of precedence to determine the eventing system configuration for a workflow.
9+
10+
Eventing system configuration precedence rules are as follows:
11+
12+
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.
13+
14+
2. If the `SonataFlowPlatform` CR enclosing the workflow has a platform-scoped eventing system configured, this configuration is then applied to the next step.
15+
16+
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.
17+
18+
4. Review the following information, if none of the above configurations are defined:
19+
20+
* The workflow uses direct HTTP calls to deliver SonataFlow system events to supporting services.
21+
* The workflow consumes incoming events by HTTP POST calls at the workflow service root path `/`.
22+
* No eventing system is configured to produce workflow business events. Any attempt to produce such events might result in a failure.

‎modules/serverless-logic-linking-workflows-eventing-system.adoc

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-workflow-eventing-system
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="serverless-logic-linking-workflows-eventing-system_{context}"]
6+
= Linking workflows to the eventing system
7+
8+
The {ServerlessLogicOperatorName} links workflows with the eventing system using Knative Eventing, SinkBindings, and triggers. These objects are created automatically by the {ServerlessLogicOperatorName} and simplify the production and consumption of workflow events.
9+
10+
The following example shows the Knative Eventing objects created for an `example-workflow` workflow configured with a platform-scoped eventing system:
11+
12+
[source,yaml]
13+
----
14+
apiVersion: sonataflow.org/v1alpha08
15+
kind: SonataFlowPlatform
16+
metadata:
17+
name: sonataflow-platform-example
18+
namespace: example-namespace
19+
spec:
20+
eventing:
21+
broker:
22+
ref:
23+
name: example-broker <1>
24+
apiVersion: eventing.knative.dev/v1
25+
kind: Broker
26+
services:
27+
dataIndex: <2>
28+
enabled: true
29+
jobService: <3>
30+
enabled: true
31+
...
32+
----
33+
34+
<1> The `example-broker` object is used by the Data Index, Jobs Service, and the `example-workflow` workflow.
35+
<2> The Data Index is deployed with ephemeral configurations.
36+
<3> The Jobs Service is deployed with ephemeral configurations.
37+
38+
The `example-broker` object is a Kafka class Broker, and its configuration is defined in the `kafka-broker-config` config map.
39+
40+
The following example displays how to configure a Kafka Knative Broker for use with the SonataFlowPlatform:
41+
42+
[source,yaml]
43+
----
44+
apiVersion: eventing.knative.dev/v1
45+
kind: Broker
46+
metadata:
47+
annotations:
48+
eventing.knative.dev/broker.class: Kafka <1>
49+
name: example-broker
50+
namespace: example-namespace
51+
spec:
52+
config:
53+
apiVersion: v1
54+
kind: ConfigMap
55+
name: kafka-broker-config
56+
namespace: knative-eventing
57+
----
58+
59+
<1> The Kafka class is used to create the `example-broker` object.
60+
61+
The following example displays how the `example-workflow` is automatically linked to the `example-broker` in the `example-namespace` for event production and consumption:
62+
63+
[source,yaml]
64+
----
65+
apiVersion: sonataflow.org/v1alpha08
66+
kind: SonataFlow
67+
metadata:
68+
name: example-workflow
69+
namespace: example-namespace
70+
annotations:
71+
sonataflow.org/description: Example Workflow
72+
sonataflow.org/version: 0.0.1
73+
sonataflow.org/profile: preview
74+
spec:
75+
flow:
76+
start: ExampleStartState
77+
events:
78+
- name: outEvent1
79+
source: ''
80+
kind: produced
81+
type: out-event-type1 <1>
82+
- name: inEvent1
83+
source: ''
84+
kind: consumed
85+
type: in-event-type1 <2>
86+
- name: inEvent2
87+
source: ''
88+
kind: consumed
89+
type: in-event-type2 <3>
90+
states:
91+
- name: ExampleStartState
92+
...
93+
----
94+
95+
<1> The `example-workflow` outgoing events are produced by using the `SinkBinding` named `example-workflow-sb`.
96+
<2> Events of type `in-event-type1` are consumed by using the `example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11` trigger.
97+
<3> Events of type `in-event-type2` are consumed by using the `example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11` trigger.
98+
99+
You can list the automatically created `SinkBinding` named `example-workflow-sb` by using the following command:
100+
101+
[source,terminal]
102+
----
103+
$ oc get sinkbindings -n example-namespace
104+
----
105+
106+
.Example output
107+
[source,terminal,options="nowrap"]
108+
----
109+
NAME TYPE RESOURCE SINK READY
110+
example-workflow-sb SinkBinding sinkbindings.sources.knative.dev broker:example-broker True
111+
----
112+
113+
You can use the following command to list the automatically created triggers for event consumption:
114+
115+
[source,terminal]
116+
----
117+
$ oc get triggers -n <example-namespace>
118+
----
119+
120+
.Example output
121+
[source,terminal]
122+
----
123+
NAME BROKER SINK AGE CONDITIONS READY REASON
124+
example-workflow-inevent1-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True
125+
example-workflow-inevent2-b40c067c-595b-4913-81a4-c8efa980bc11 example-broker service:example-workflow 16m 7 OK / 7 True
126+
----

‎modules/serverless-logic-platform-scoped-eventing-system-config.adoc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-workflow-eventing-system
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="serverless-logic-platform-scoped-eventing-system-config_{context}"]
6+
= Platform-scoped eventing system configuration
7+
8+
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.
9+
10+
This configuration instructs the {ServerlessLogicOperatorName} 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.
11+
12+
The supporting services deployed in the namespace without a custom eventing configuration are also linked to this broker.
13+
14+
[NOTE]
15+
====
16+
In production environments, use a production-ready broker, such as the Knative Kafka Broker, for enhanced scalability and reliability.
17+
====
18+
19+
The following example displays how to configure the `SonataFlowPlatform` CR for a platform-scoped eventing system:
20+
21+
[source,yaml]
22+
----
23+
apiVersion: sonataflow.org/v1alpha08
24+
kind: SonataFlowPlatform
25+
metadata:
26+
name: sonataflow-platform-example
27+
namespace: <example-namespace>
28+
spec:
29+
eventing:
30+
broker:
31+
ref:
32+
name: example-broker <1>
33+
namespace: <example-broker-namespace> <2>
34+
apiVersion: eventing.knative.dev/v1
35+
kind: Broker
36+
----
37+
38+
<1> Specifies the Knative Eventing Broker name.
39+
<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`.

‎modules/serverless-logic-workflow-scoped-eventing-system-config.adoc

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-workflow-eventing-system
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="serverless-logic-workflow-scoped-eventing-system-config_{context}"]
6+
= Workflow-scoped eventing system configuration
7+
8+
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.
9+
10+
[id="serverless-logic-outgoing-eventing-system-config_{context}"]
11+
== Outgoing eventing system configuration
12+
13+
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.
14+
15+
The following example displays how to configure the `SonataFlow` CR for a workflow-scoped outgoing eventing system:
16+
17+
[source,yaml]
18+
----
19+
apiVersion: sonataflow.org/v1alpha08
20+
kind: SonataFlow
21+
metadata:
22+
name: example-workflow
23+
namespace: example-workflow-namespace
24+
annotations:
25+
sonataflow.org/description: Example Workflow
26+
sonataflow.org/version: 0.0.1
27+
sonataflow.org/profile: preview
28+
spec:
29+
sink:
30+
ref:
31+
name: outgoing-example-broker <1>
32+
namespace: outgoing-example-broker-namespace <2>
33+
apiVersion: eventing.knative.dev/v1
34+
kind: Broker
35+
flow: <3>
36+
start: ExampleStartState
37+
events: <4>
38+
- name: outEvent1 <5>
39+
source: ''
40+
kind: produced
41+
type: out-event-type1 <6>
42+
...
43+
----
44+
45+
<1> Name of the Knative Eventing Broker to use for all the events produced by the workflow, including the SonataFlow system events.
46+
<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`.
47+
<3> Flow definition field in the `SonataFlow` CR.
48+
<4> Events definition field in the `SonataFlow` CR.
49+
<5> Example of an outgoing event `outEvent1` definition.
50+
<6> Event type for the `outEvent1` outgoing event.
51+
52+
[id="serverless-logic-incoming-eventing-system-config_{context}"]
53+
== Incoming eventing system configuration
54+
55+
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.
56+
57+
If an incoming event type lacks a specific Broker configuration, the system applies eventing system configuration precedence rules.
58+
59+
The following example displays how to configure the `SonataFlow` CR for a workflow-scoped incoming eventing system:
60+
61+
[NOTE]
62+
====
63+
The link between a `spec.sources[]` entry and the workflow event, is by using the event type.
64+
====
65+
66+
[source,yaml]
67+
----
68+
apiVersion: sonataflow.org/v1alpha08
69+
kind: SonataFlow
70+
metadata:
71+
name: example-workflow
72+
namespace: example-workflow-namespace
73+
annotations:
74+
sonataflow.org/description: Example Workflow
75+
sonataflow.org/version: 0.0.1
76+
sonataflow.org/profile: preview
77+
spec:
78+
sources:
79+
- eventType: in-event-type1 <1>
80+
ref:
81+
name: incoming-example-broker1 <2>
82+
namespace: incoming-example-broker1-namespace <3>
83+
apiVersion: eventing.knative.dev/v1
84+
kind: Broker
85+
- eventType: in-event-type2 <4>
86+
ref:
87+
name: incoming-example-broker2 <5>
88+
namespace: incoming-example-broker2-namespace <6>
89+
apiVersion: eventing.knative.dev/v1
90+
kind: Broker
91+
flow: <7>
92+
start: ExampleStartState
93+
events: <8>
94+
- name: inEvent1 <9>
95+
source: ''
96+
kind: consumed
97+
type: in-event-type1 <10>
98+
- name: inEvent2 <11>
99+
source: ''
100+
kind: consumed
101+
type: in-event-type2 <12>
102+
...
103+
----
104+
105+
<1> Configure the workflow to consume events of type `in-event-type1` using the specified Knative Eventing Broker.
106+
<2> Name of the Knative Eventing Broker to use for the consumption of the events of type `in-event-type1` sent to this workflow.
107+
<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.
108+
<4> Configure the workflow to consume events of type `in-event-type2` using the specified Knative Eventing Broker.
109+
<5> Name of the Knative Eventing Broker to use for the consumption of the events of type `in-event-type2` sent to this workflow.
110+
<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.
111+
<7> Flow definition field in the `SonataFlow` CR.
112+
<8> Events definition field in the `SonataFlow` CR.
113+
<9> Example of an incoming event `inEvent1` definition.
114+
<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`.
115+
<11> Example of an incoming event `inEvent2` definition.
116+
<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.

‎serverless-logic/serverless-logic-workflow-eventing-system.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:_content-type: ASSEMBLY
2+
[id="serverless-logic-workflow-eventing-system"]
3+
= Workflow eventing system
4+
:context: serverless-logic-workflow-eventing-system
5+
include::_attributes/common-attributes.adoc[]
6+
7+
toc::[]
8+
9+
You can set up the eventing system for a `SonataFlow` workflow.
10+
11+
In a {ServerlessLogicProductName} installation, the following types of events are generated:
12+
13+
* Outgoing and incoming events related to workflow business logic.
14+
* Events sent from workflows to the Data Index and Job Service.
15+
* Events sent from the Job Service to the Data Index Service.
16+
17+
The {ServerlessLogicOperatorName} leverages the Knative Eventing system to manage all event communication between these services, ensuring efficient and reliable event handling.
18+
19+
include::modules/serverless-logic-platform-scoped-eventing-system-config.adoc[leveloffset=+1]
20+
include::modules/serverless-logic-workflow-scoped-eventing-system-config.adoc[leveloffset=+1]
21+
include::modules/serverless-logic-cluster-scoped-eventing-system-config.adoc[leveloffset=+1]
22+
include::modules/serverless-logic-eventing-system-config-precedence-rule.adoc[leveloffset=+1]
23+
include::modules/serverless-logic-linking-workflows-eventing-system.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)