From 4ba0f6c3ee4c81397dee8dd0409b8bacf6f2feb6 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 28 May 2024 17:11:23 +0200 Subject: [PATCH] Draft PR Changes --- serverlessworkflow/antora.yml | 3 + .../pages/job-services/core-concepts.adoc | 93 +++++-------------- 2 files changed, 25 insertions(+), 71 deletions(-) diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index 025015412..5861cee87 100644 --- a/serverlessworkflow/antora.yml +++ b/serverlessworkflow/antora.yml @@ -54,7 +54,10 @@ asciidoc: # 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: docker.io/apache/incubator-kie-kogito-jobs-service-allinone + jobs_service_image_ephemeral_name: incubator-kie-kogito-jobs-service-ephemeral jobs_service_image_ephemeral_url: https://hub.docker.com/r/apache/incubator-kie-kogito-jobs-service-ephemeral + jobs_service_image_postgresql_name: incubator-kie-kogito-jobs-service-postgresql + jobs_service_image_postgresql: docker.io/apache/incubator-kie-kogito-jobs-service-postgresql jobs_service_image_postgresql_url: https://hub.docker.com/r/apache/incubator-kie-kogito-jobs-service-postgresql jobs_service_image_usage_url: https://github.com/apache/incubator-kie-kogito-images#jobs-services-all-in-one diff --git a/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc b/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc index 1a47fe9d2..2759b2d5c 100644 --- a/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc +++ b/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc @@ -51,40 +51,25 @@ To learn how to install and configure the Job Service in this case, you must rea [#executing] == Executing -To execute the Job Service in your docker or Kubernetes environment, you must use the following image: +To execute the Job Service in your docker or Kubernetes environment, you must use any of the following images, depending on the persistence mechanism to use <> or <>. -* link:{jobs_service_image_allinone_url}[kogito-jobs-service-allinone] +* link:{jobs_service_image_postgresql_url}[{jobs_service_image_postgresql_name}] +* link:{jobs_service_image_ephemeral_url}[{jobs_service_image_ephemeral_name}] -In the next topics you can see the different configuration parameters that you must use, for example, to configure the <>, the <>, etc. -More information on this image can be found link:{jobs_service_image_usage_url}[here]. +In the next topics you can set how to configure them. + +[NOTE] +==== +The <> and the <> is configured the same for both images. +==== We recommend that you follow this procedure: -1. Identify the <> to use and see the required configuration parameters. +1. Identify the image to use depending on the persistence mechanism, and see the required configuration parameters specific for that image. 2. Identify if the <> is required for your needs and see the required configuration parameters. 3. Identify if the project containing your workflows is configured with the appropriate xref:use-cases/advanced-developer-use-cases/job-service/quarkus-extensions.adoc#job-service-quarkus-extensions[Job Service Quarkus Extension]. -Finally, to run the image, you must use the <>, and other configurations that you can set using <> or using <>. - -[#exposed-environment-variables] -=== Exposed environment variables - -[cols="1,2"] -|=== -|Variable | Description - -|`SCRIPT_DEBUG` -|Enable debug level of the image and its operations. - -|`JOBS_SERVICE_PERSISTENCE` -|Any of the following values: `postgresql` or `ephemeral`, to select the persistence mechanism to use, <>. - -|=== - -[NOTE] -==== -If used, these values must always be passed as environment variables. -==== +Finally, when you run the image, you must pass these configurations using <> or using <>. [#using-environent-variables] === Using environment variables @@ -94,7 +79,7 @@ To configure the image by using environment variables you must pass one environm .Job Service image configuration for docker execution example [source, bash,subs="attributes+"] ---- -docker run -it -e JOBS_SERVICE_PERSISTENCE=postgresql -e VARIABLE_NAME=value {jobs_service_image_allinone}:latest +docker run -it -e QUARKUS_DATASOURCE_USERNAME=postgresql -e VARIABLE_NAME=value {jobs_service_image_postgresql}:latest ---- .Job Service image configuration for Kubernetes execution example @@ -103,7 +88,7 @@ docker run -it -e JOBS_SERVICE_PERSISTENCE=postgresql -e VARIABLE_NAME=value {jo spec: containers: - name: jobs-service-postgresql - image: {jobs_service_image_allinone}:latest + image: {jobs_service_image_postgresql}:latest imagePullPolicy: Always ports: - containerPort: 8080 @@ -115,8 +100,6 @@ spec: valueFrom: fieldRef: fieldPath: metadata.namespace - - name: JOBS_SERVICE_PERSISTENCE - value: "postgresql" - name: QUARKUS_DATASOURCE_USERNAME value: postgres - name: QUARKUS_DATASOURCE_PASSWORD @@ -142,8 +125,8 @@ To configure the image by using system properties you must pass one property per .Job Service image configuration for docker execution example [source, bash,subs="attributes+"] ---- -docker run -it -e JOBS_SERVICE_PERSISTENCE=postgresql -e JAVA_OPTIONS='-Dmy.sys.prop1=value1 -Dmy.sys.prop2=value2' \ -{jobs_service_image_allinone}:latest +docker run -it -e JAVA_OPTIONS='-Dquarkus.datasource.username=postgres -Dmy.sys.prop1=value1 -Dmy.sys.prop2=value2' \ +{jobs_service_image_postgresql}:latest ---- [NOTE] @@ -153,9 +136,9 @@ For example, the name `quarkus.datasource.jdbc.url` must be converted to `QUARKU ==== [#job-service-global-configurations] -== Global configurations +== Common configurations -Global configurations that affect the job execution retries, startup procedure, etc. +Common configurations that affect the job execution retries, startup procedure, etc. [tabs] ==== @@ -196,22 +179,8 @@ Using system properties with java like names:: ==== [#job-service-persistence] -== Persistence - -An important configuration aspect of the Job Service is the persistence mechanism, it is where all the jobs information is stored, and guarantees no information is lost upon service restarts. - -The Job Service image is shipped with the <> and <> persistence mechanisms, that can be switched by setting the JOBS_SERVICE_PERSISTENCE environment variable to any of these values `postgresql` or `ephemeral`. If not set, it defaults to the `ephemeral` option. - -[NOTE] -==== -The <> image is a composite packaging that include one different image per each persistence mechanism, making it clearly bigger sized than the individual ones. If that size represents an issue in your installation you can use the individual ones instead. -Finally, if you use this alternative, the JOBS_SERVICE_PERSISTENCE must not be used, since the persistence mechanism is auto-determined. - -These are the individual images: {jobs_service_image_postgresql_url}[kogito-jobs-service-postgresql] and {jobs_service_image_ephemeral_url}[kogito-jobs-service-ephemeral]. -==== - [#job-service-postgresql] -=== PostgreSQL +== Job Service PostgreSQL Configuration PostgreSQL is the recommended database to use with the Job Service. Additionally, it provides an initialization procedure that integrates Flyway for the database initialization. Which automatically controls the database schema, in this way, the tables are created or updated by the service when required. @@ -219,7 +188,7 @@ Additionally, it provides an initialization procedure that integrates Flyway for In case you need to externally control the database schema, you can check and apply the DDL scripts for the Job Service in the same way as described in xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc#manually-executing-scripts[Manually executing scripts] guide. -To configure the PostgreSQL persistence you must provide these configurations: +To configure the Job Service PostgreSQL you must provide these configurations: [tabs] ==== @@ -230,10 +199,6 @@ Using environment variables:: |=== |Variable | Description| Example value -|`JOBS_SERVICE_PERSISTENCE` -|Configure the persistence mechanism that must be used. -|`postgresql` - |`QUARKUS_DATASOURCE_USERNAME` |Username to connect to the database. |`postgres` @@ -259,10 +224,6 @@ Using system properties with java like names:: |=== |Variable | Description| Example value -|`JOBS_SERVICE_PERSISTENCE` -|**Always an environment variable** -|`postgresql` - |`quarkus.datasource.username` |Username to connect to the database. |`postgres` @@ -286,23 +247,13 @@ The timeouts showcase example xref:use-cases/advanced-developer-use-cases/timeou In your local environment you might have to change some of these values to point to your own PostgreSQL database. [#job-service-ephemeral] -=== Ephemeral - -The Ephemeral persistence mechanism is based on an embedded PostgreSQL database and does not require any external configuration. However, the database is recreated on each service restart, and thus, it must be used only for testing purposes. - -[cols="2,1,1"] -|=== -|Variable | Description| Example value +== Job Service Ephemeral Configuration -|`JOBS_SERVICE_PERSISTENCE` -|Configure the persistence mechanism that must be used. -|`ephemeral` - -|=== +The Ephemeral persistence mechanism is based on an embedded PostgreSQL database and does not require any specific configuration other thant the <> and the <>. [NOTE] ==== -If the image is started by not configuring any persistence mechanism, the Ephemeral will be defaulted. +The database is recreated on each service restart, and thus, it must be used only for testing purposes. ==== [#job-service-eventing-api]