wmedvede commented on code in PR #628:
URL:
https://github.com/apache/incubator-kie-kogito-docs/pull/628#discussion_r1609786505
##########
serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc:
##########
@@ -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
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 ban
the SonataFlowPlatform persistence.
+
+== Persistence configuration and SonataFlow profiles
+
+All the configurations shown in this guide apply exactly the same for both the
`preview` and the `gitops` profiles, however, you must not use them when you
use the `dev` profile.
+
+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.
+
+[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}
+|===
+
+This last can be done by passing the following build argument to the
`kogito-swf-builder`:
+
+
+[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}
Review Comment:
@ricardozanini yes, in the `preview` we already ad them, so the guide here
tries to say.
For `dev`never include.
For `preview`, do nothing. (we automatically inject these extensions at
build time, this is the development I did)
For `gitops` you must add them by your self whey you build the WF, because
we can't handle the image build in that case.
Not sure if this clarifies?
##########
serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc:
##########
@@ -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
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 ban
the SonataFlowPlatform persistence.
+
+== Persistence configuration and SonataFlow profiles
+
+All the configurations shown in this guide apply exactly the same for both the
`preview` and the `gitops` profiles, however, you must not use them when you
use the `dev` profile.
+
+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.
+
+[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}
+|===
+
+This last can be done by passing the following build argument to the
`kogito-swf-builder`:
+
+
+[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}
Review Comment:
@ricardozanini yes, in the `preview` we already add them, so the guide
here tries to say.
For `dev`never include.
For `preview`, do nothing. (we automatically inject these extensions at
build time, this is the development I did)
For `gitops` you must add them by your self whey you build the WF, because
we can't handle the image build in that case.
Not sure if this clarifies?
--
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]
