wmedvede commented on code in PR #639:
URL:
https://github.com/apache/incubator-kie-kogito-docs/pull/639#discussion_r1619223402
##########
serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-knative-eventing-resources.adoc:
##########
@@ -1,60 +1,425 @@
= Knative Eventing
+:sectnums:
+
:compat-mode!:
// Metadata:
-:description: Configuration of knatve eventing deployed by the operator
+:description: Configuration of knative eventing deployed by the operator
:keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes,
knative, knative-eventing, events
-This document describes how you can configure the workflows to let operator
create the Knative eventing resources on Kubernetes.
+This document describes how to configure the workflows, and the supporting
services, to use link:{knative_eventing_url}[Knative Eventing] as the preferred
eventing system.
-{operator_name} can analyze the event definitions from the `spec.flow` and
create `SinkBinding`/`Trigger` based on the type of the event. Then the
workflow service can utilize them for event communications.
+In general, the following events are produced in a {product_name} installation:
-[NOTE]
+* Workflow outgoing and incoming business events.
+* {product_name} system events sent from the workflow to the Data Index and
Job Service respectively.
+* {product_name} system events sent from the Jobs Service to the Data Index
Service.
+
+[IMPORTANT]
====
- Alternativelly, you can follow our
xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc#ref-example-sw-event-definition-knative[advanced
guide] that uses Java and Quarkus to introduce this feature.
+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:
+
== Prerequisite
+
1. The {operator_name} installed. See
xref:cloud/operator/install-serverless-operator.adoc[] guide.
-2. Knative is installed on the cluster and Knative Eventing is initiated with
a `KnativeEventing` CR.
-3. A broker named `default` is created. Currently, all Triggers created by the
{operator_name} will read events from `default`
+2. The link:{knative_eventing_url}[Knative Eventing] system is installed and
property initiated in the cluster.
+
+== Configuring the Knative Broker
+
+Create a Knative Broker to define the event mesh to collect the events with a
resource like this:
+
+[source,yaml]
+----
+apiVersion: eventing.knative.dev/v1
+kind: Broker
+metadata:
+ name: default
+ namespace: example-namespace
+----
+
+For more information on Knative Brokers
link:{knative_eventing_broker_url}[see].
+
+[NOTE]
+====
+The example creates an in-memory broker for simplicity. In production
environments, you must use a production-ready broker, like the
link:{knative_eventing_kafka_broker_url}[Knative Kafka] broker.
+====
+
+[[querying_broker_url]]
+Finally, to get the Broker URL that is needed in the next steps of the
configuration, you can execute the following command:
+
+[source,bash]
+----
+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
+----
-== Configuring the workflow
+For a link:{knative_eventing_kafka_broker_url}[Knative Kafka] broker that the
URL will look like this instead.
-For the operator to create the `SinkBinding` resources, the workflow must
provide the sink information in `spec.sink`.
+[source,bash]
+----
+http://kafka-broker-ingress.knative-eventing.svc.cluster.local/example-namespace/default
+----
+
+== Configuring the Data Index Knative Eventing Resources
+
+=== Workflows to DataIndex system events
+
+Create the following Knative Triggers to deliver all the {product_name} system
events sent from the workflows to the Data Index Service:
+
+[NOTE]
+====
+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
link:{knative_eventing_trigger_url}[see].
+
+.Process definition events trigger
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+----
-.Example of a workflow with events
-[source,yaml,subs="attributes+"]
---
+=== Job Service to Data Index system events
+
+Create the following Knative Trigger to deliver all the {product_name} system
events sent from the Job Service to the Data Index Service:
+
+[NOTE]
+====
+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
link:{knative_eventing_trigger_url}[see].
+
+.Job events trigger
+[source,yaml]
+----
+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
+----
+
+== Configuring the Job Service Knative Eventing Resources
+
+Create the following Knative Triggers to deliver all the {product_name} system
events produced by the workflows to the Job Service:
+
+[NOTE]
+====
+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
+[source,yaml]
+----
+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
+[source,yaml]
+----
+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
+----
+
+== Data Index and Job Service installation
+
+To deploy these services you must use a `SonataFlowPlatform CR` and configure
it according to the xref:cloud/operator/supporting-services.adoc[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`.
+
+[source,yaml]
+----
+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 <<querying_broker_url, see>>.
+
+== Workflow configuration
+
+=== SonataFlow CR configuration
+
+To configure a workflow you must create a `SonataFlow CR` that fulfills your
requirements as usual.
+And finally, prior to deployment into the cluster, add the `env` variables
shown below to the field `spec.podTemplate.container`.
+
+.Workflow configuration
+[source,yaml]
+----
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:
- sink:
- ref: <1>
- name: default
- namespace: greeting
- apiVersion: eventing.knative.dev/v1
- kind: Broker
+ 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:
- events: <2>
- - name: requestQuote
- type: kogito.sw.request.quote
- kind: produced
- - name: aggregatedQuotesResponse,
- type: kogito.loanbroker.aggregated.quotes.response,
- kind: consumed,
- source: /kogito/serverless/loanbroker/aggregator
-...
---
-<1> `spec.sink.ref` defines the sink that all created sinkBinding will use as
the destination sink for producing events
-<2> `spec.flow.events` lists all the events referenced in the workflow. Events
with `produced` kind will trigger the creation of `SinkBindings` by the
{operator_name}, while those labeled as `consumed` will lead to the generation
of `Triggers`.
+ 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 <<querying_broker_url,
see>>. The remaining env variables are fixed configurations, and you must add
them as is.
+<3> Every consumed event requires a trigger, <<trigger-event-type1, see>>.
+<4> Every consumed event requires a trigger, <<trigger-event-type2, see>>.
+
+=== 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.
[NOTE]
====
-Knative resources are not watched by the operator, indicating they will not
undergo automatic reconciliation. This grants users the freedom to make updates
at their preference.
+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-event-type1]]
+.Trigger to consume events of type example_event_1
+[source,yaml]
+----
+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-event-type2]]
+.Trigger to consume events of type example_event_2
+[source,yaml]
+----
+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
+----
+
+:sectnums!:
Review Comment:
we can try to add something, but we are running out-of-time at the same
time. I think, we should merge this, try to finish the revisting of the
supporting services guide, and hopefully, add more stuff on this.
--
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]
