diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index 025015412..b96f96a62 100644 --- a/serverlessworkflow/antora.yml +++ b/serverlessworkflow/antora.yml @@ -138,6 +138,8 @@ asciidoc: docker_compose_install_url: https://docs.docker.com/compose/install/ kn_cli_install_url: https://knative.dev/docs/client/install-kn/ knative_eventing_url: https://knative.dev/docs/eventing/ + knative_eventing_broker_url: https://knative.dev/docs/eventing/brokers/ + knative_eventing_kafka_broker_url: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ knative_eventing_trigger_url: https://knative.dev/docs/eventing/triggers/ knative_eventing_sink_binding_url: https://knative.dev/docs/eventing/sinks/#sink-parameter-example knative_quickstart_url: https://knative.dev/docs/install/quickstart-install/#install-the-knative-cli/ diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-knative-eventing-resources.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-knative-eventing-resources.adoc index 8ce4fa6bd..ef09bfa8c 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-knative-eventing-resources.adoc +++ b/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 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` -== Configuring the workflow +1. The {operator_name} is installed. See xref:cloud/operator/install-serverless-operator.adoc[] guide. +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 +---- + +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 <>. + +== Workflow configuration + +=== 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 +[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 <>. The remaining env variables are fixed configurations, and you must add them as is. +<3> Every consumed event requires a trigger, <>. +<4> Every consumed event requires a trigger, <>. + +=== 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!: == Additional resources * https://knative.dev/docs/eventing/[Knative Eventing official site]