This is an automated email from the ASF dual-hosted git repository.
ricardozanini pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 2de2970f8 kie-kogito-serverless-operator-459: Restructuring of the
Cloud -> Operator -> Persistence chapter (#628)
2de2970f8 is described below
commit 2de2970f81b23d521646c12bb30f81cf9ff63d94
Author: Walter Medvedeo <[email protected]>
AuthorDate: Wed May 22 14:55:52 2024 +0200
kie-kogito-serverless-operator-459: Restructuring of the Cloud -> Operator
-> Persistence chapter (#628)
---
serverlessworkflow/antora.yml | 16 +-
.../images/persistence/Persistence-Types.drawio | 73 +++++
.../images/persistence/Persistence-Types.png | Bin 0 -> 23504 bytes
.../pages/cloud/operator/global-configuration.adoc | 11 +
.../pages/cloud/operator/using-persistence.adoc | 308 +++++++++++++++++----
.../ROOT/pages/persistence/core-concepts.adoc | 35 ++-
.../persistence/persistence-core-concepts.adoc | 1 +
7 files changed, 377 insertions(+), 67 deletions(-)
diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml
index 865954772..e8e46188e 100644
--- a/serverlessworkflow/antora.yml
+++ b/serverlessworkflow/antora.yml
@@ -60,8 +60,8 @@ asciidoc:
#
# Versions
#
- quarkus_version: 3.2.9.Final
- quarkus_platform_version: 3.2.9.Final
+ quarkus_version: 3.8.4
+ quarkus_platform_version: 3.8.4
java_min_version: 17+
maven_min_version: 3.9.3
graalvm_min_version: 22.3.0
@@ -77,9 +77,20 @@ asciidoc:
knative_version: 1.13
knative_serving_version: 1.13
knative_eventing_version: 1.13
+ kogito_version: 999-SNAPSHOT
# only used in downstream
operator_version: main
+ # Persistence extensions for the kogito-swf-builder
+ groupId_quarkus-agroal: io.quarkus
+ artifactId_quarkus-agroal: quarkus-agroal
+
+ groupId_quarkus-jdbc-postgresql: io.quarkus
+ artifactId_quarkus-jdbc-postgresql: quarkus-jdbc-postgresql
+
+ groupId_kie-addons-quarkus-persistence-jdbc: org.kie
+ artifactId_kie-addons-quarkus-persistence-jdbc:
kie-addons-quarkus-persistence-jdbc
+
#
# URLs
#
@@ -170,6 +181,7 @@ asciidoc:
ocp_knative_serving_install_url:
https://docs.openshift.com/container-platform/4.12/serverless/install/installing-knative-serving.html
ocp_knative_eventing_install_url:
https://docs.openshift.com/container-platform/4.12/serverless/install/installing-knative-eventing.html
ocp_kn_cli_url:
https://docs.openshift.com/container-platform/4.12/serverless/install/installing-kn.html
+ k8n_secrets_url: https://kubernetes.io/docs/concepts/configuration/secret
#
# xreferences to documents within the documentation
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.drawio
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.drawio
new file mode 100644
index 000000000..3191fb71c
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.drawio
@@ -0,0 +1,73 @@
+<mxfile host="Electron" modified="2024-05-21T09:18:40.035Z" agent="Mozilla/5.0
(X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.4.0
Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36"
etag="H0YQd7mQeqnJeK-5HK6e" version="24.4.0" type="device">
+ <diagram name="Page-1" id="CsZ2FxxG6tZcgXgf0lRF">
+ <mxGraphModel dx="1098" dy="502" grid="0" gridSize="10" guides="1"
tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1"
pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-2" value="Workflow runtime
persistence" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="115.5" y="109" width="179" height="40" as="geometry"
/>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-8" value=""
style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;"
parent="1" vertex="1">
+ <mxGeometry x="175" y="177" width="60" height="47" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-14" value=""
style="endArrow=classic;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;dashed=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;"
parent="1" source="QGvM4vl__vyeh6SA8aqo-21" target="QGvM4vl__vyeh6SA8aqo-2"
edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="357.5" y="97" as="sourcePoint" />
+ <mxPoint x="357.5" y="151" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="206" y="67" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-21" value="Workflow instance"
style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="303" y="37" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="NtIaZSLPTitUS9Ow5RH7-1" value="Data Index persistence"
style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="430" y="109" width="179" height="40" as="geometry" />
+ </mxCell>
+ <mxCell id="NtIaZSLPTitUS9Ow5RH7-2" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;" parent="1"
source="QGvM4vl__vyeh6SA8aqo-21" target="NtIaZSLPTitUS9Ow5RH7-1" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="448" y="54" as="sourcePoint" />
+ <mxPoint x="541" y="132" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="520" y="67" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="NtIaZSLPTitUS9Ow5RH7-5" value=""
style="endArrow=classic;startArrow=classic;html=1;rounded=0;dashed=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;"
parent="1" source="QGvM4vl__vyeh6SA8aqo-8" target="QGvM4vl__vyeh6SA8aqo-2"
edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="200" y="227" as="sourcePoint" />
+ <mxPoint x="200" y="187" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="NtIaZSLPTitUS9Ow5RH7-7" value=""
style="endArrow=classic;startArrow=classic;html=1;rounded=0;dashed=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;"
parent="1" source="NtIaZSLPTitUS9Ow5RH7-8" target="NtIaZSLPTitUS9Ow5RH7-1"
edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="516" y="235" as="sourcePoint" />
+ <mxPoint x="521" y="182" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="NtIaZSLPTitUS9Ow5RH7-8" value=""
style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;"
parent="1" vertex="1">
+ <mxGeometry x="488.5" y="177" width="60" height="47" as="geometry" />
+ </mxCell>
+ <mxCell id="2djzuOXhbR6o8aeaAMRS-1" value=""
style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
+ <mxGeometry x="633" y="125.25" width="7.5" height="7.5"
as="geometry" />
+ </mxCell>
+ <mxCell id="2djzuOXhbR6o8aeaAMRS-6" value=""
style="endArrow=none;html=1;rounded=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;"
parent="1" source="2djzuOXhbR6o8aeaAMRS-1" target="NtIaZSLPTitUS9Ow5RH7-1"
edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="538" y="197" as="sourcePoint" />
+ <mxPoint x="588" y="147" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="2djzuOXhbR6o8aeaAMRS-8" value="<i
style="font-size: 10px;"><font style="font-size:
10px;">graphql&nbsp;</font></i>"
style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=10;"
parent="1" vertex="1">
+ <mxGeometry x="616" y="125.25" width="60" height="30" as="geometry"
/>
+ </mxCell>
+ <mxCell id="2djzuOXhbR6o8aeaAMRS-11" value="<font
style="font-size: 10px;">workflow instance
snapshots</font><div style="font-size: 10px;"><font
style="font-size: 10px;">(internal
format)</font></div>"
style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=10;"
parent="1" vertex="1">
+ <mxGeometry x="139.25" y="229" width="131.5" height="30"
as="geometry" />
+ </mxCell>
+ <mxCell id="2djzuOXhbR6o8aeaAMRS-13" value="<font
style="font-size: 10px;">workflow instance
snapshots</font><div style="font-size: 10px;"><font
style="font-size: 10px;">(queryable
format)</font></div>"
style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=10;"
parent="1" vertex="1">
+ <mxGeometry x="453.75" y="229" width="131.5" height="30"
as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.png
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.png
new file mode 100644
index 000000000..226836a1e
Binary files /dev/null and
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Types.png
differ
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
index 4bf338fd1..5b21d0d1f 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
@@ -33,6 +33,17 @@ You can freely edit any of the options in the key
`controllers_cfg.yaml` entry.
| `dataIndexEphemeralTag` | empty | The Data Index image without persistence
to use, if empty the operator will use the default Apache Community one based
on the current operator's version.
| `sonataFlowBaseBuilderImageTag` | empty | {product_name} base builder image
used in the internal Dockerfile to build workflow applications in preview
profile. If empty the operator will use the default Apache Community one based
on the current operator's version.
| `sonataFlowDevModeImageTag` | empty | The image to use to deploy
{product_name} workflow images in devmode profile. If empty the operator will
use the default Apache Community one based on the current operator's version.
+| `builderConfigMapName` | sonataflow-operator-builder-config | The default
name of the builder configMap in the operator's namespace.
+| `postgreSQLPersistenceExtensions` | next column
+| Quarkus extensions required for workflows persistence. These extensions are
used by the {operator_name} builder in cases where the workflow being built has
configured xref:cloud/operator/using-persistence.adoc[postgresql persistence].
+
+`Default values`:
+
+{groupId_quarkus-agroal}:{artifactId_quarkus-agroal}:{quarkus_version}
+
+{groupId_quarkus-jdbc-postgresql}:{artifactId_quarkus-jdbc-postgresql}:{quarkus_version}
+
+{groupId_kie-addons-quarkus-persistence-jdbc}:{artifactId_kie-addons-quarkus-persistence-jdbc}:{kogito_version}
|===
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc
index a94ad32bd..8e39f3580 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc
@@ -1,26 +1,33 @@
-= Using persistence in the SonataFlow Workflow CR
+= Using persistence in {product_name} workflows
:compat-mode!:
// Metadata:
:description: Using persistence in the workflow instance to store its context
:keywords: sonataflow, workflow, serverless, operator, kubernetes, persistence
+This document describes how to configure a `SonataFlow` instance to use
persistence and store the workflow context in a relational database.
-This document describes how to configure a SonataFlow instance to use
persistence to store the flow's context in a relational database.
+Kubernetes's pods are stateless by definition. In some scenarios, this can be
a challenge for workloads that require maintaining the status of
+the application regardless of the pod's lifecycle. In the case of
{product_name}, by default, the context of the workflow is lost when the pod
restarts.
-== Configuring the SonataFlow CR to use persistence
+If your workflow requires recovery from such scenarios, you must provide
additional configuration to enable the
xref:persistence/core-concepts.adoc#_workflow_runtime_persistence[Workflow
Runtime Persistence].
+That configuration must be provided by using the
<<_configuring_the_persistence_using_the_sonataflowplatform_cr,
`SonataFlowPlatform` CR>> or the
<<_configuring_the_persistence_using_the_sonataflow_cr, `SonataFlow` CR>>, and
has different scopes depending on each case.
-Kubernetes's pods are stateless by definition. In some scenarios, this can be
a challenge for workloads that require maintaining the status of
-the application regardless of the pod's lifecycle. In the case of
{product_name}, the context of the workflow is lost when the pod restarts.
-If your workflow requires recovery from such scenarios, you have to make these
additions to your workflow CR:
-Use the `persistence` field in the `SonataFlow` workflow spec to define the
database service located in the same cluster.
-There are 2 ways to accomplish this:
+== Configuring the persistence using the SonataFlowPlatform CR
-* Using the Platform CR's defined persistence
-When the Platform CR is deployed with its persistence spec populated it
enables workflows to leverage its configuration to populate the persistence
-properties in the workflows.
+The `SonataFlowPlatform` CR facilitates the configuration of the persistence
with namespace scope. It means that it will be automatically applied to all the
workflows deployed in
+that namespace. This can be useful to reduce the amount resources to
configure, for example, in cases where the workflows deployed in that namespace
belongs to the same application, etc.
+That decision is left to each particular use case, however, it's important to
know, that this configuration can be overridden by any workflow in that
namespace by using the <<_configuring_the_persistence_using_the_sonataflow_cr,
`SonataFlow` CR>>.
-[source,yaml,subs="attributes+"]
----
+[NOTE]
+====
+Persistence configurations are applied at workflow deployment time, and
potential changes in the SonataFlowPlatform will not impact already deployed
workflows.
+====
+
+To configure the persistence you must use the `persistence` field in the
SonataFlowPlatform CR `spec`:
+
+.SonataFlowPlatform CR persistence configuration example
+[source,yaml]
+----
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
@@ -29,82 +36,261 @@ spec:
persistence:
postgresql:
secretRef:
- name: postgres-secrets
- userKey: POSTGRES_USER
- passwordKey: POSTGRES_PASSWORD
+ name: postgres-secrets <1>
+ userKey: POSTGRESQL_USER <2>
+ passwordKey: POSTGRESQL_PASSWORD <3>
serviceRef:
- name: postgres
- port: 5432
- databaseName: sonataflow
- databaseSchema: shared
- build:
- config:
- strategyOptions:
- KanikoBuildCacheEnabled: "true"
----
-
-The values of `POSTGRES_USER` and `POSTGRES_PASSWORD` are the keys in the
[Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/)
that contains the credentials to connect to the postgreSQL instance.
-The SonataFlow Workflow CR
-is defined with its `Persistence` field defined as empty.
+ name: postgres <4>
+ namespace: sonataflow-infra <5>
+ databaseName: sonataflow <6>
+ port: 1234 <7>
+----
+
+<1> Name of the link:{k8n_secrets_url}[Kubernetes Secret] containing the
username and password to connect with the database.
+<2> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the
username to connect with the database.
+<3> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the
password to connect with the database.
+<4> Name of the Kubernetes Service to connect with the PostgreSQL database
server.
+<5> (Optional) Kubernetes namespace containing the PostgreSQL Service.
Defaults to the `SonataFlowPlatform`'s local namespace.
+<6> Name of the PostgreSQL database to store the workflow's data.
+<7> (Optional) Port number to connect with the PostgreSQL Service. Defaults to
5432.
+
+This configuration signals the operator that every workflow deployed in the
current `SonataFlowPlatform`'s namespace must be properly configured to connect
with that PostgreSQL database server.
+And the operator will add the relevant JDBC connection parameters in the form
of environment variables to the workflow container.
+
+Additionally, for `SonataFlow` CR deployments that use the `preview` profile,
it will configure the {product_name} build system to include specific Quarkus
extensions required for persistence.
+[NOTE]
+====
+Currently, PostgreSQL is the only supported persistence.
+====
+
+Below you can see an example of the configurations produced for a workflow
with the name `example-workflow`, that was deployed using the previous
`SonataFlowPlatform`.
+For simplicity, only the `env` configurations related to the persistence has
been included. These operator managed configurations are immutable.
+
+[#persistence_env_vars_config_example]
+.Generated persistence `env` configurations in the workflow container
[source,yaml,subs="attributes+"]
+----
+ env:
+ - name: QUARKUS_DATASOURCE_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: postgres-secrets
+ key: POSTGRESQL_USER
+ - name: QUARKUS_DATASOURCE_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: postgres-secrets
+ key: POSTGRESQL_PASSWORD
+ - name: QUARKUS_DATASOURCE_DB_KIND
+ value: postgresql
+ - name: QUARKUS_DATASOURCE_JDBC_URL
+ value: >-
+
jdbc:postgresql://postgres.sonataflow-infra:1234/sonataflow?currentSchema=example-workflow
+ - name: KOGITO_PERSISTENCE_TYPE
+ value: jdbc
+----
+
+[IMPORTANT]
+====
+When you use the `SonataFlowPlatform` persistence, every workflow is
configured to use a PostgreSQL schema name equal to the workflow name.
+====
+
+To learn how to initialize the database schema see:
<<_database_schema_initialization, Database schema initialization>>.
+
+== Configuring the persistence using the SonataFlow CR
+
+The `SonataFlow` CR facilitates the configuration of the persistence with
workflow scope, and you can use it independently if the `SonataFlowPlatform`
persistence was already configured in the current namespace, see:
<<_persistence_configuration_precedence_rules, Persistence configuration
precedence rules>>.
+
+To configure the persistence, you must use the `persistence` field in the
`SonataFlow` CR `spec`:
+
+.SonataFlow CR persistence configuration example
+[source,yaml]
+----
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
- name: callbackstatetimeouts
+ name: example-workflow
annotations:
- sonataflow.org/description: Callback State Timeouts Example k8s
+ sonataflow.org/description: Example Workflow
sonataflow.org/version: 0.0.1
spec:
- persistence: {}
- ...
----
+ persistence:
+ postgresql:
+ secretRef:
+ name: postgres-secrets <1>
+ userKey: POSTGRESQL_USER <2>
+ passwordKey: POSTGRESQL_PASSWORD <3>
+ serviceRef:
+ name: postgres <4>
+ namespace: sonataflow-infra <5>
+ databaseName: sonataflow <6>
+ databaseSchema: my-example-schema <7>
+ port: 1234 <8>
+ flow:
+ ...
+----
+
+<1> Name of the link:{k8n_secrets_url}[Kubernetes Secret] containing the
username and password to connect with the database.
+<2> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the
username to connect with the database.
+<3> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the
password to connect with the database.
+<4> Name of the Kubernetes Service to connect with the PostgreSQL database
server.
+<5> (Optional) Kubernetes namespace containing the PostgreSQL Service.
Defaults to the workflow's local namespace.
+<6> Name of the PostgreSQL database to store the workflow's data.
+<7> (Optional) Name of the database schema to store workflow's data. Defaults
to the workflow's name.
+<8> (Optional) Port number to connect with the PostgreSQL Service. Defaults to
5432.
-This configuration signals the operator that the workflow requires persistence
and that it expects its configuration to be populated accordingly.
-The operator will add the relevant JDBC properties in the
`application.properties`
-generated and as part of the pod´s environment so that it can connect to the
persistence service defined in the `Platform` CR.
+This configuration signals the operator that the current workflow must be
properly configured to connect with that PostgreSQL database server when
deployed.
+Similar to the `SonataFlowPlatform` persistence, the operator will add the
relevant JDBC connection parameters in the form of
<<persistence_env_vars_config_example, environment variables>> to the workflow
container.
+
+Additionally, for `SonataFlow` CR deployments that use the `preview` profile,
it can configure the {product_name} build system to include specific Quarkus
extensions required for persistence.
[NOTE]
====
-Currently, PostgreSQL is the only persistence supported.
+Currently, PostgreSQL is the only supported persistence.
====
-* Using the custom defined persistence in the `SonataFlow` CR
+To learn how to initialize the database schema see:
<<_database_schema_initialization, Database schema initialization>>.
-Alternatively, you can define a dedicated configuration in the `SonataFlow` CR
instance using the same schema format found in the Platform CRD:
+== Persistence configuration precedence rules
-[source,yaml,subs="attributes+"]
+<<_configuring_the_persistence_using_the_sonataflow_cr, `SonataFlow` CR
persistence>> can be used with or without the
<<_configuring_the_persistence_using_the_sonataflowplatform_cr,
`SonataFlowPlatform` CR persistence>>.
+
+And, if the current namespace has an already configured
<<_configuring_the_persistence_using_the_sonataflowplatform_cr,
`SonataFlowPlatform` CR persistence>>, the following rules apply:
+
+* If the `SonataFlow` CR has a configured persistence, that configuration will
apply.
+* If the `SonataFlow` CR has no configured persistence, i.e., the field
`spec.persistence` is not present at all, the persistence configuration will be
taken from the current platform.
+* If you don't want the current workflow to use `persistence`, you must use
the following configuration in the SonataFlow CR: `spec.persistence : {}` to
ignore the `SonataFlowPlatform` persistence configuration.
+
+== Persistence configuration and SonataFlow profiles
+
+All the configurations shown for the `SonataFlowPlatform CR` and `SonataFlow
CR`, apply exactly the same for both the `preview` and the `gitops` profiles.
+However, you must not use them in the `dev` profile, since this profile will
simply ignore them.
+
+Finally, the only distinction between `preview` and `gitops` profiles is that,
when you use the `gitops` profile, the following Quarkus extensions must be
added when you build your workflow image. Since that build is accomplished
outside the operator scope.
+
+[cols="40%,40%,20%", options="header"]
+|===
+|groupId
+|artifactId
+|version
+
+| {groupId_quarkus-agroal}
+| {artifactId_quarkus-agroal}
+| {quarkus_version}
+
+| {groupId_quarkus-jdbc-postgresql}
+| {artifactId_quarkus-jdbc-postgresql}
+| {quarkus_version}
+
+| {groupId_kie-addons-quarkus-persistence-jdbc}
+| {artifactId_kie-addons-quarkus-persistence-jdbc}
+| {kogito_version}
+|===
+
+If you generate your images by using the `kogito-swf-builder`, you can do it
by passing it the following build argument:
+
+[source,bash,subs="attributes+"]
+----
+QUARKUS_EXTENSIONS={groupId_quarkus-agroal}:{artifactId_quarkus-agroal}:{quarkus_version},{groupId_quarkus-jdbc-postgresql}:{artifactId_quarkus-jdbc-postgresql}:{quarkus_version},{groupId_kie-addons-quarkus-persistence-jdbc}:{artifactId_kie-addons-quarkus-persistence-jdbc}:{kogito_version}
+----
+
+== Database schema initialization
+
+When you use the `SonataFlow` PostgreSQL persistence, you can either opt to
use Flyway to produce the database initialization, or manually upgrade your
database via DDL scripts.
+
+=== Flyway managed database initialization
+
+To enable Flyway you must use any of the following configuration procedures:
+
+[NOTE]
+====
+The Flyway schema initialization is disabled by default.
+====
+
+=== Flyway configuration by using the workflow ConfigMap
+
+Add the following property to your workflow ConfigMap.
+
+.Example of enabling Flyway by using the workflow ConfigMap
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ labels:
+ app: example-workflow
+ name: example-workflow-props
+data:
+ application.properties: |
+ quarkus.flyway.migrate-at-start = true
+----
+
+=== Flyway configuration by using the workflow container env vars
+
+Add the following `env` var in the `spec.podTemplate.container` of the
`SonataFlow` CR.
+
+.Example of enabling Flyway by using the workflow container env vars
+[source, yaml]
+----
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
- name: callbackstatetimeouts
+ name: example-workflow
annotations:
- sonataflow.org/description: Callback State Timeouts
+ sonataflow.org/description: Example Workflow
sonataflow.org/version: 0.0.1
spec:
- persistence:
- postgresql:
- secretRef:
- name: postgres-secrets
- userKey: POSTGRES_USER
- passwordKey: POSTGRES_PASSWORD
- serviceRef:
- name: postgres
- port: 5432
- databaseName: sonataflow
- databaseSchema: callbackstatetimeouts
- ...
----
+ podTemplate:
+ container:
+ env:
+ - name: QUARKUS_FLYWAY_MIGRATE_AT_START
+ value: 'true'
+ flow: ...
+----
-Like in the Platform CR case, the values of the `POSTGRES_USER` and
`POSTGRES_PASSWORD` are the secret keys in the secret that contain the
credentials to connect to
-the PostgreSQL instace.
+=== Flyway configuration by using SonataFlowPlatForm properties
+
+To apply a common Flyway configuration to all the workflows in a given
namespace, you can use the `spec.properties` of the `SonataFlowPlatform` in
that namespace.
+
+.Example of enabling Flyway by using the SonataFlowPlatform properties.
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+ name: sonataflow-platform
+spec:
+ properties:
+ - name: quarkus.flyway.migrate-at-start
+ value: true
+----
+
+[NOTE]
+====
+The configuration above takes effect at workflow deployment time, so you must
be sure that property is configured before you deploy your workflows.
+====
+
+=== Manual database initialization by using DDL
+
+To initialize the database schema manually, you must be sure that the
following application property `quarkus.flyway.migrate-at-start` is not
configured, or is set to `false`, and follow this
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc#manually-executing-scripts[procedure].
+
+[NOTE]
+====
+Remember that:
+
+* By default, every workflow is configured use a schema name equal to the
workflow name, and thus, that manual initialization must be applied for every
workflow.
+* When you use the <<_configuring_the_persistence_using_the_sonataflow_cr,
`SonataFlow` CR persistence configuration>> it is possible to use the schema
name of your choice.
+====
== Conclusion
-You can enable SQL persistence in your workflows by configuring each
`SonataFlow` CR instance. And when the `SonataFlowPlatform` CR contains the
persistence field configured,
-the operator uses this information to configure those `SonataFlow` CRs that
request persistence. When both the `Platform CR` and the `SonataFlow CR`
contain persistence
-configuration, the operator will use the `Persistence` values from the
`SonataFlow` CR.
+By using the `SonataFlowPlatform` CR you can enable the persistence for all
the workflows that you deploy in that namespace.
+And, by using the `SonataFlow` CR you can enable the persistence of a
particular workflow. If both methods are present in the current namespace, the
`SonataFlow` CR configuration has precedence over the `SonataFlowpPlatform`
configuration.
+
+
== Additional resources
* xref:cloud/operator/developing-workflows.adoc[]
+* xref:persistence/core-concepts.adoc[]
include::../../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
diff --git
a/serverlessworkflow/modules/ROOT/pages/persistence/core-concepts.adoc
b/serverlessworkflow/modules/ROOT/pages/persistence/core-concepts.adoc
index e76e183b5..b20818d4b 100644
--- a/serverlessworkflow/modules/ROOT/pages/persistence/core-concepts.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/persistence/core-concepts.adoc
@@ -6,11 +6,38 @@
:keywords: sonataflow, workflow, serverless, timeout, timer, expiration,
persistence
// links
-Persistence in {product_name} is available on demand as a service.
-Using configuration properties, users are able to configure the persistence
for their workflows as required.
+SonataFlow provides two persistence mechanisms to store information about the
workflow instances.
+The <<_workflow_runtime_persistence, Workflow runtime persistence>>, and
<<_data_index_persistence, Data Index persistence>>.
-The persistence is provided by our Data Index service.
-To learn more about the service, examine the links in additional resources.
+Each mechanism is intended for different a purpose:
+
+image::persistence/Persistence-Types.png[]
+
+== Workflow runtime persistence
+The workflow runtime persistence ensures that your workflow instances remain
consistent during an error or a runtime restart. For example, a pod restart, a
programmed maintenance shutdown, etc.
+This is achieved by storing snapshots of the executing workflow instances
[xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc#saving_of_workflow_snapshots[see
more details]].
+That information is stored in an internal format, and usually, you must only
focus on providing the proper configurations to use it.
+
+To learn how to configure it we recommend that you read the following sections
depending on your use case:
+
+* xref:cloud/operator/using-persistence.adoc[Using persistence in
{operator_name} managed workflow deployments]
+*
xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[Using
persistence in advanced development cases of {product_name} applications using
Quarkus and Java]
+
+[NOTE]
+====
+In production environments, or when your workflows use timeouts, or you use
operator managed knative serving deployments, it's strongly recommended that
you configure the workflow runtime persistence.
+====
+
+== Data Index persistence
+The Data Index persistence is designed to store information about your
workflow instances in a way that this information can be consumed by other
services using GraphQL queries.
+This is achieved by properly configuring and deploying the
xref:data-index/data-index-core-concepts.adoc[Data Index Service] in your
installation.
+
+To learn how to configure and deploy the Data Index Service we recommend that
you read the following sections depending on your use case:
+
+* xref:cloud/operator/supporting-services.adoc[Deploying supporting services
with {operator_name}]
+* xref:data-index/data-index-service.adoc/[Data Index standalone service]
+
+To learn more about this service, examine the links in additional resources.
== Additional resources
diff --git
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
index d88596675..bb0ca34bf 100644
---
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
@@ -8,6 +8,7 @@ The {product_name} workflow runtime persistence is the
mechanism to ensure that
Every workflow instance requires some status information and data to execute,
this information is automatically managed by the workflow's runtime and is
persisted at different moments of the workflow execution.
+[#saving_of_workflow_snapshots]
For example, when a workflow instance reaches a state that needs to wait for
an event, the engine takes a snapshot of the most relevant information, stores
it in the database, and pauses that instance execution.
In this way, resources like memory are released and can be used by other
executing instances.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
