kaldesai commented on code in PR #689:
URL:
https://github.com/apache/incubator-kie-kogito-docs/pull/689#discussion_r1843610089
##########
serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-workflow-eventing-system.adoc:
##########
@@ -0,0 +1,315 @@
+= Configuring the Workflow Eventing system
+:compat-mode!:
+// Metadata:
+:description: Workflows eventing system configuration
+:keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes,
knative, knative-eventing, events
+
+This document describes how to configure the eventing system for a
{product_name} workflow.
+
+In general, the following events are produced in a {product_name} 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 SonataFlow Operator is designed to use the
link:{knative_eventing_url}[Knative Eventing] system to resolve all the event
communication between these services.
+
+[NOTE]
+====
+In a regular SonataFlow installation, the preferred method is to use the
<<platform-scoped-eventing-system-configuration>>, while the
<<workflow-scoped-eventing-system-configuration>> is reserved only for advanced
use cases.
+====
+
+[#platform-scoped-eventing-system-configuration]
+== Platform-scoped Eventing system configuration
+
+To configure a platform-scoped eventing system, you must use the field
`spec.eventing.broker.ref` in the `SonataFlowPlatform` CR to refer to a Knative
Eventing Broker.
+
+This information signals the {operator_name} to automatically link every
workflow deployed in that namespace, to `produce` and `consume` the events by
using that Broker.
+
+Additionally, the supporting services deployed in that namespace, that don't
provide a custom eventing system configuration, will be linked to that Broker.
+For more information about configuring the supporting services eventing
system,
xref:cloud/operator/supporting-services.adoc#configuring-supporting-services-eventing-system[see].
+
+The following `SonataFlowPlatform` CR fragment shows an example of such
configuration:
+
+.Platform scoped eventing system configuration example
+
+include::common/platform-scoped-eventing-system-configuration-example.adoc[]
+
+[#workflow-scoped-eventing-system-configuration]
+== Workflow-scoped Eventing system configuration
+
+A workflow-scoped eventing system configuration provides the ability to do a
fine-grained configuration of the eventing system for the events `produced` and
`consumed` by a workflow.
+
+To configure a workflow-scoped eventing system you must use the fields
`spec.sink.ref` and `spec.sources[]` in the `SonataFlow` CR.
+
+[#outgoing-eventing-system-configuration]
+=== Outgoing Eventing system configuration
+
+To configure a workflow-scoped eventing system for the workflow outgoing
events, you must use the field `spec.sink.ref` in the `SonataFlow` CR.
+
+This information signals the SonataFlow Operator to automatically link the
current workflow, to produce the events by using that Broker.
+That includes, the {product_name} system events, and the workflow business
events.
+
+The following `SonataFlow` CR fragment shows an example of such configuration:
+
+.Workflow-scoped outgoing eventing system configuration example
+[source, yaml]
+----
+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>
+
+ ... <7>
+----
+
+<1> Name of the Knative Eventing Broker to use for all the events produced by
the workflow, including the {product_name} system events.
+<2> Optional: Defines the namespace of the Knative Eventing Broker. Defaults
to the SonataFlow namespace. In general, we recommend creating the Knative
Eventing Broker in the same namespace as the 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 outgoing event `outEvent1`
+<7> Only a fragment of the workflow is shown for simplicity.
+
+[#incoming-eventing-system-configuration]
+=== Incoming Eventing system configuration
+
+To configure a workflow-scoped eventing system for the workflow incoming
events, you must use the field `spec.sources[]` in the `SonataFlow` CR.
+And, you must add an entry in the array, for every event type that requires an
individual configuration.
+
+This information signals the SonataFlow Operator to automatically link the
current workflow, to potentially `consume` the events from different Brokers,
depending on the event type.
+
+Incoming event types not configured with a particular Broker, are consumed by
applying <<eventing-system-configuration-precedence-rules>>.
+
+The following `SonataFlow` CR fragment shows an example of such configuration:
+
+.Workflow-scoped incoming eventing system configuration example
+
+[source, yaml]
+----
+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>
+ ... <13>
+
+----
+
+<1> Eventing system configuration entry for the workflow incoming events of
type `in-event-type1`.
+<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: Defines the namespace of the Knative Eventing Broker. Defaults
to the SonataFlow namespace. In general, we recommend creating the Knative
Eventing Broker in the same namespace as the SonataFlow.
Review Comment:
```suggestion
<3> Optional: Defines the namespace of the Knative Eventing Broker. Defaults
to the SonataFlow namespace. We recommend creating the Knative Eventing Broker
in the same namespace as the SonataFlow.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
