From eb78bb1d9badea3d2192515171017724c76b0482 Mon Sep 17 00:00:00 2001 From: Dominik Hanak Date: Tue, 20 Feb 2024 15:53:29 +0100 Subject: [PATCH] Move data-index and remaining chapter to advanced, minor fixes --- serverlessworkflow/modules/ROOT/nav.adoc | 22 +-- .../pages/data-index/data-index-service.adoc | 133 +---------------- .../_dataindex_deployment_operator.adoc | 0 .../data-index/common/_prerequisites.adoc | 0 .../common/_querying_dataindex.adoc | 0 .../data-index-as-quarkus-dev-service.adoc | 141 ++++++++++++++++++ .../data-index-quarkus-extension.adoc | 0 .../data-index/data-index-usecase-multi.adoc | 2 +- .../data-index-usecase-singleton.adoc | 4 +- 9 files changed, 157 insertions(+), 145 deletions(-) rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/common/_dataindex_deployment_operator.adoc (100%) rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/common/_prerequisites.adoc (100%) rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/common/_querying_dataindex.adoc (100%) create mode 100644 serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-as-quarkus-dev-service.adoc rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/data-index-quarkus-extension.adoc (100%) rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/data-index-usecase-multi.adoc (98%) rename serverlessworkflow/modules/ROOT/pages/{ => use-cases/advanced-developer-use-cases}/data-index/data-index-usecase-singleton.adoc (97%) diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index 12cf718c39..28c331e616 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -19,12 +19,17 @@ * Getting Started ** xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[] * Core Concepts -// all guides here reference quarkus examples, we basically need every example without quarkus to solve this ** xref:core/cncf-serverless-workflow-specification-support.adoc[] +// TODO: Introduce getting-started-with-events guide ** xref:core/handling-events-on-workflows.adoc[Events] +// TODO: Introduce getting-started-with-callbacks guide +// TODO: Split the quarkus parts to advanced section ** xref:core/working-with-callbacks.adoc[Callbacks] +// TODO: Reference a non-quarkus example ??? ** xref:core/understanding-jq-expressions.adoc[] +// TODO: very long - consider shorting this ** xref:core/understanding-workflow-error-handling.adoc[Error handling] +// TODO: Remove description of old databases ** xref:core/configuration-properties.adoc[Configuration] // TODO: Consider splitting the Schemas to Input and Output guides // TODO: Ensure that the guide we reference is not using Quarkus - right now it does @@ -54,9 +59,6 @@ ** Client Authentication *** xref:security/authention-support-for-openapi-services.adoc[OpenAPI Authentication] *** xref:security/orchestrating-third-party-services-with-oauth2.adoc[OpenAPI OAuth2] -//* Running Workflows Locally -//** Running a Workflow Project TODO: https://issues.redhat.com/browse/KOGITO-9457 -// ** Running a Quarkus Workflow Project TODO: https://issues.redhat.com/browse/KOGITO-9458 * Executing, Testing and Troubleshooting ** Executing and Testing Workflows *** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[Developer UI] @@ -65,7 +67,6 @@ **** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-monitoring-page.adoc[Monitoring] **** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-custom-dashboard-page.adoc[Dashboards] *** xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Command Line] -// *** Swagger UI, GraphiQL, Console logging TODO: https://issues.redhat.com/browse/KOGITO-9462 * Persistence ** xref:persistence/core-concepts.adoc[Core concepts] // * Java Workflow Library TODO: https://issues.redhat.com/browse/KOGITO-9454 @@ -86,18 +87,14 @@ ** xref:integrations/core-conepts.adoc[] * Job Service ** xref:job-services/core-concepts.adoc[Core Concepts] -** xref:job-services/quarkus-extensions.adoc[Quarkus Extensions] * Data Index ** xref:data-index/data-index-core-concepts.adoc[Core concepts] ** xref:data-index/data-index-service.adoc[Standalone service] -** xref:data-index/data-index-quarkus-extension.adoc[Quarkus Extensions] ** Operator *** xref:data-index/data-index-usecase-singleton.adoc[] *** xref:data-index/data-index-usecase-multi.adoc[] -//** Quarkus Extensions TODO: https://issues.redhat.com/browse/KOGITO-9463 * Use Cases -** Advanced Development Use Cases -// TODO: Explain the purpose of this section +** xref:use-cases/advanced-developer-use-cases/index.adoc[Advanced Development Use Cases] *** Getting started with {product_name} applications and Quarkus **** xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[] **** xref:use-cases/advanced-developer-use-cases/getting-started/build-workflow-image-with-quarkus-cli.adoc[] @@ -115,6 +112,11 @@ **** xref:use-cases/advanced-developer-use-cases/persistence/integration-tests-with-postgresql.adoc[] *** Job Service in SonataFlow applications and Quarkus **** xref:use-cases/advanced-developer-use-cases/job-service/quarkus-extensions.adoc[] +*** Data Index in {product_name} applications and Quarkus +**** xref:data-index/data-index-as-quarkus-dev-service.adoc[Data Index as a Quarkus Development Service] +**** xref:data-index/data-index-usecase-singleton.adoc[Data Index as a Quarkus Development Service] +**** xref:data-index/data-index-usecase-multi.adoc[Data Index as a Quarkus Development Service] +**** xref:data-index/data-index-quarkus-extension.adoc[Quarkus Extensions] *** Service Orchestration in {product_name} applicatios and Quarkus **** xref:use-cases/advanced-developer-use-cases/service-orchestration/configuring-openapi-services-endpoints-with-quarkus.adoc[] **** xref:use-cases/advanced-developer-use-cases/service-orchestration/orchestration-of-grpc-services.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-service.adoc b/serverlessworkflow/modules/ROOT/pages/data-index/data-index-service.adoc index dd63bf517a..ef8e44597f 100644 --- a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-service.adoc +++ b/serverlessworkflow/modules/ROOT/pages/data-index/data-index-service.adoc @@ -15,7 +15,7 @@ :workflow_instances: {workflow_instance}s [#data-index-service] -== {data_index_ref} service deployment. +== {data_index_ref} service deployment {data_index_ref} service can be deployed referencing directly a distributed {data_index_ref} image. There are different images provided that take into account what persistence layer is required in each case. In each distribution, there are some properties to configure things like the connection with the database or the communication with other services. @@ -257,137 +257,6 @@ A full example where the {data_index_ref} service standalone is deployed using K --- -[#data-index-dev-service-details] -== {data_index_ref} as a Quarkus Development service -When you use the {product_name} Process Quarkus extension, a temporary {data_index_ref} service is automatically provisioned while the Quarkus application is running in development mode. When you use one of the following Quarkus extensions, the Dev Service is set up for immediate use: - -.{product_name} main Quarkus extension -[source,xml] ----- - - org.kie.kogito - kogito-quarkus - ----- - -.{product_name} Quarkus extension -[source,xml] ----- - - org.kie.kogito - kogito-quarkus-serverless-workflow - ----- - -When you start your Quarkus project in development mode, an in-memory instance of the {data_index_ref} service is automatically started in the background. This feature is enabled by link:{dev_services_url}[Quarkus Dev Services], and leverages link:{test_containers_url}[Testcontainers] to start an image of the {data_index_ref} service. - -The {product_name} Process Quarkus extension sets up your Quarkus application to automatically replicate any {product_name} messaging events related to {workflow_instances} or jobs into the provisioned {data_index_ref} instance. - -Once the service is up and running, you can query the GraphQL interface directly using `http://localhost:8180/graphql` or using the Quarkus Dev UI console `http://localhost:8080/q/dev`. - -The {data_index_ref} GraphQL endpoint can query for `ProcessInstances` and `Jobs`. For more information about operations and attributes to query, see xref:data-index/data-index-core-concepts.adoc#data-index-graphql[GraphQL endpoint provided by {data_index_ref}] section. - -You can share the same {data_index_ref} instance across multiple {product_name} services during development. Sharing {data_index_ref} instances is enabled by default, therefore, only one {data_index_ref} instance is started. This behavior can be adjusted to start multiple instances using the `quarkus.kogito.devservices.shared` property. - -The Quarkus Dev Service also allows further configuration options including: - -* To disable {data_index_ref} Dev Service, use the `quarkus.kogito.devservices.enabled=false` property. -* To change the port where the {data_index_ref} Dev Service runs, use the `quarkus.kogito.devservices.port=8180` property. -* To adjust the provisioned image, use `quarkus.kogito.devservices.imageName=quay.io/kiegroup/kogito-data-index-ephemeral` property. -* To disable sharing the {data_index_ref} instance across multiple Quarkus applications, use `quarkus.kogito.devservices.shared=false` property. - -For more information about Quarkus Dev Services, see link:{dev_services_url}[Dev Services guide]. - -[#data-index-service-configuration-properties] -== {data_index_ref} service configuration properties -The following table serves as a quick reference for commonly {data_index_ref} configuration properties supported. - -.Common configuration properties -[cols="40%,35%,10%,10%,5%", options="header"] -|=== -|Property|Description|Type|Default value|Override at runtime - -|`QUARKUS_DATASOURCE_JDBC_URL` -| The datasource URL -| string -| -| Yes - -|`QUARKUS_DATASOURCE_USERNAME` -| The datasource username -| string -| -| Yes - -|`QUARKUS_DATASOURCE_PASSWORD` -| The datasource password -| string -| -| Yes - -|`QUARKUS_DATASOURCE_DB_KIND` -a|The kind of database to connect: `postgresql`,.. -|string -| -|Yes - -|`QUARKUS_FLYWAY_MIGRATE_AT_START` -| `true` to execute Flyway automatically when the application starts, false otherwise. -| boolean -| false -| Yes - -|`KOGITO_DATA_INDEX_QUARKUS_PROFILE` -a| (Only when referencing an image distribution) - -Allows to change the event connection type. The possible values are: - -* `kafka-events-support` -* `http-events-support` - -| string -| `kafka-events-support` -| Yes - -|`kogito.persistence.query.timeout.millis` -|Defines timeout for a query execution. -|long -|`10000` -|Yes - -|`quarkus.kogito.devservices.enabled` -|Enables or disables the Dev Services for workflows. By default, the Dev Services are enabled, unless an existing configuration is present. -|boolean -|`true` -|No - -|`quarkus.kogito.devservices.port` -|Defines the optional fixed port that the Dev Services listen to. -|int -|`8180` -|No - -|`quarkus.kogito.devservices.image-name` -|Defines the {data_index_ref} image to use in Dev Service. -|string -|`quay.io/kiegroup/kogito-data-index-ephemeral:{page-component-version}` -|No - -|`quarkus.kogito.devservices.shared` -|Indicates if the {data_index_ref} instance, which is managed by Quarkus Dev Services, is shared. -|boolean -|`true` -|No - -|`quarkus.kogito.devservices.service-name` -|Defines the value of the label that is attached to the started container. This property is used when `shared` is set to `true`. -|string -|`kogito-data-index` -|No - - -|=== - == Additional resources * xref:data-index/data-index-core-concepts.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/common/_dataindex_deployment_operator.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_dataindex_deployment_operator.adoc similarity index 100% rename from serverlessworkflow/modules/ROOT/pages/data-index/common/_dataindex_deployment_operator.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_dataindex_deployment_operator.adoc diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/common/_prerequisites.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_prerequisites.adoc similarity index 100% rename from serverlessworkflow/modules/ROOT/pages/data-index/common/_prerequisites.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_prerequisites.adoc diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/common/_querying_dataindex.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_querying_dataindex.adoc similarity index 100% rename from serverlessworkflow/modules/ROOT/pages/data-index/common/_querying_dataindex.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/common/_querying_dataindex.adoc diff --git a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-as-quarkus-dev-service.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-as-quarkus-dev-service.adoc new file mode 100644 index 0000000000..69df572b15 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-as-quarkus-dev-service.adoc @@ -0,0 +1,141 @@ += {data_index_ref} as a Quarkus Development service +When you use the {product_name} Process Quarkus extension, a temporary {data_index_ref} service is automatically provisioned while the Quarkus application is running in development mode. When you use one of the following Quarkus extensions, the Dev Service is set up for immediate use: + +.{product_name} main Quarkus extension +[source,xml] +---- + + org.kie.kogito + kogito-quarkus + +---- + +.{product_name} Quarkus extension +[source,xml] +---- + + org.kie.kogito + kogito-quarkus-serverless-workflow + +---- + +When you start your Quarkus project in development mode, an in-memory instance of the {data_index_ref} service is automatically started in the background. This feature is enabled by link:{dev_services_url}[Quarkus Dev Services], and leverages link:{test_containers_url}[Testcontainers] to start an image of the {data_index_ref} service. + +The {product_name} Process Quarkus extension sets up your Quarkus application to automatically replicate any {product_name} messaging events related to {workflow_instances} or jobs into the provisioned {data_index_ref} instance. + +Once the service is up and running, you can query the GraphQL interface directly using `http://localhost:8180/graphql` or using the Quarkus Dev UI console `http://localhost:8080/q/dev`. + +The {data_index_ref} GraphQL endpoint can query for `ProcessInstances` and `Jobs`. For more information about operations and attributes to query, see xref:data-index/data-index-core-concepts.adoc#data-index-graphql[GraphQL endpoint provided by {data_index_ref}] section. + +You can share the same {data_index_ref} instance across multiple {product_name} services during development. Sharing {data_index_ref} instances is enabled by default, therefore, only one {data_index_ref} instance is started. This behavior can be adjusted to start multiple instances using the `quarkus.kogito.devservices.shared` property. + +The Quarkus Dev Service also allows further configuration options including: + +* To disable {data_index_ref} Dev Service, use the `quarkus.kogito.devservices.enabled=false` property. +* To change the port where the {data_index_ref} Dev Service runs, use the `quarkus.kogito.devservices.port=8180` property. +* To adjust the provisioned image, use `quarkus.kogito.devservices.imageName=quay.io/kiegroup/kogito-data-index-ephemeral` property. +* To disable sharing the {data_index_ref} instance across multiple Quarkus applications, use `quarkus.kogito.devservices.shared=false` property. + +For more information about Quarkus Dev Services, see link:{dev_services_url}[Dev Services guide]. + +[#data-index-service-configuration-properties] +== {data_index_ref} service configuration properties +The following table serves as a quick reference for commonly {data_index_ref} configuration properties supported. + +.Common configuration properties +[cols="40%,35%,10%,10%,5%", options="header"] +|=== +|Property|Description|Type|Default value|Override at runtime + +|`QUARKUS_DATASOURCE_JDBC_URL` +| The datasource URL +| string +| +| Yes + +|`QUARKUS_DATASOURCE_USERNAME` +| The datasource username +| string +| +| Yes + +|`QUARKUS_DATASOURCE_PASSWORD` +| The datasource password +| string +| +| Yes + +|`QUARKUS_DATASOURCE_DB_KIND` +a|The kind of database to connect: `postgresql`,.. +|string +| +|Yes + +|`QUARKUS_FLYWAY_MIGRATE_AT_START` +| `true` to execute Flyway automatically when the application starts, false otherwise. +| boolean +| false +| Yes + +|`KOGITO_DATA_INDEX_QUARKUS_PROFILE` +a| (Only when referencing an image distribution) + +Allows to change the event connection type. The possible values are: + +* `kafka-events-support` +* `http-events-support` + +| string +| `kafka-events-support` +| Yes + +|`kogito.persistence.query.timeout.millis` +|Defines timeout for a query execution. +|long +|`10000` +|Yes + +|`quarkus.kogito.devservices.enabled` +|Enables or disables the Dev Services for workflows. By default, the Dev Services are enabled, unless an existing configuration is present. +|boolean +|`true` +|No + +|`quarkus.kogito.devservices.port` +|Defines the optional fixed port that the Dev Services listen to. +|int +|`8180` +|No + +|`quarkus.kogito.devservices.image-name` +|Defines the {data_index_ref} image to use in Dev Service. +|string +|`quay.io/kiegroup/kogito-data-index-ephemeral:{page-component-version}` +|No + +|`quarkus.kogito.devservices.shared` +|Indicates if the {data_index_ref} instance, which is managed by Quarkus Dev Services, is shared. +|boolean +|`true` +|No + +|`quarkus.kogito.devservices.service-name` +|Defines the value of the label that is attached to the started container. This property is used when `shared` is set to `true`. +|string +|`kogito-data-index` +|No + + +|=== + +--- + +== Additional resources + +* xref:data-index/data-index-core-concepts.adoc[] +* xref:cloud/quarkus/deploying-on-minikube.adoc[] +* xref:eventing/consume-producing-events-with-kafka.adoc[] +* xref:eventing/consume-produce-events-with-knative-eventing.adoc[] +* xref:use-cases/timeout-showcase-example.adoc[Timeout example in {product_name}] + +include::../../../_common-content/report-issue.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-quarkus-extension.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-quarkus-extension.adoc similarity index 100% rename from serverlessworkflow/modules/ROOT/pages/data-index/data-index-quarkus-extension.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-quarkus-extension.adoc diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-multi.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-multi.adoc similarity index 98% rename from serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-multi.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-multi.adoc index c71d1191a3..5f99a766f2 100644 --- a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-multi.adoc +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-multi.adoc @@ -1,4 +1,4 @@ -= Deploying Data Index and multiple {product_name} application on Minikube += Deploying Data Index and multiple {product_name} applications on Minikube :compat-mode!: // Metadata: :description: Deploying Multiple {product_name} pushing to single Data Index on Minikube diff --git a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-singleton.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-singleton.adoc similarity index 97% rename from serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-singleton.adoc rename to serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-singleton.adoc index e496a93f21..e11984327b 100644 --- a/serverlessworkflow/modules/ROOT/pages/data-index/data-index-usecase-singleton.adoc +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/data-index/data-index-usecase-singleton.adoc @@ -74,7 +74,7 @@ kubectl create namespace usecase1 . Deploy the {data_index_ref} Service and postgresql database: + -- -include::common/_dataindex_deployment_operator.adoc[] +include:common/_dataindex_deployment_operator.adoc[] Perform the deployments executing [source,shell] @@ -193,4 +193,4 @@ include::common/_querying_dataindex.adoc[] * xref:cloud/quarkus/deploying-on-minikube.adoc[] * xref:cloud/operator/install-serverless-operator.adoc[] -include::../../pages/_common-content/report-issue.adoc[] +include::../../../../pages/_common-content/report-issue.adoc[]