nmirasch commented on code in PR #645: URL: https://github.com/apache/incubator-kie-kogito-docs/pull/645#discussion_r1625878137
########## serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc: ########## @@ -6,210 +6,259 @@ // links :kogito_serverless_operator_url: https://github.com/apache/incubator-kie-kogito-serverless-operator/ -Under the hood, {operator_name} supports several services that enhance its capabilities. For example -xref:data-index/data-index-core-concepts.adoc[Data Index] or xref:job-services/core-concepts.adoc[Job service]. -Please take a look at these guides to learn more about them. -By default, workflows deployed by the operator use an embedded version of xref:data-index/data-index-core-concepts.adoc[Data Index], however non-embedded options are supported as well. This document describes how to deploy and configure supporting services, like Data Index or Job Service, on a cluster using the link:{kogito_serverless_operator_url}[{operator_name}]. +This document describes how to configure and deploy the {product_name}'s xref:data-index/data-index-core-concepts.adoc[Data Index] and xref:job-services/core-concepts.adoc[Job Service] supporting services, using the {operator_name}. -[IMPORTANT] -==== -{operator_name} is under active development with features yet to be implemented. Please see xref:cloud/operator/known-issues.adoc[]. -==== +In general, in a regular {product_name} installation you must deploy both services to ensure a successful execution of your workflows. To get more information about each service please read the respective guides. .Prerequisites -* The {operator_name} installed. See xref:cloud/operator/install-serverless-operator.adoc[] guide -* A postgresql database. Required if you are planning to use non-embedded postgresql versions of supporting services. We recommend creating a postgresql deployment in your cluster. Please note your credentials. +* The {operator_name} installed. See xref:cloud/operator/install-serverless-operator.adoc[] guide. +* A PostgreSQL database service instance. Required if you are planning to use the <<postgresql-persistence-configuration>> for a supporting service. -[#deploy-supporting-services] -== Deploy supporting services +[#supporting-services-workflow-communications] +== Supporting Services and Workflow communications + +When you deploy a supporting service in a given namespace, you can do it by using an <<enabled-deployment-field, enabled or disabled>> deployment. + +An enabled deployment, signals the {operator_name} to automatically intercept every workflow deployment with the `preview` or `gitops` profile, in this namespace, and automatically configure it to connect with that service. + +For example, if the Data Index is enabled, a workflow will be automatically configured to send workflow status change events to it. +And, similar configurations are produced if the Job Service is enabled, to create a Job, every time a workflow requires a timeout. +Additionally, the operator will configure the Job Service to send events to the Data Index Service, etc. + +As you can see, the operator can not only deploy a supporting service, but also, manage other configurations to ensure the successful execution of a workflow. + +Fortunately, all these configurations are managed automatically, and you must only provide the supporting services configuration in the `SonataFlowPlatform` CR. + +[NOTE] +==== +Scenarios where you only deploy one of the supporting services, or configure a disabled deployment, are intended for advanced use cases. +In a regular installation, you must normally configure an enabled deployment of both services to ensure a successful execution of your workflows. +==== -[#deploy-data-index-service] -=== Data Index +[#deploy-supporting-services] +== Deploying the supporting services using the `SonataFlowPlatform` CR -You can deploy Data Index via `SonataFlowPlatform` configuration. The operator will then configure all new workflows, with the "preview" or "gitops" profile, to use that Data Index. +To deploy the supporting services you must use the sub-fields `dataIndex` and `jobService` in the `SonataFlowPlatform` CR `spec.services`. +That information signals the {operator_name} to deploy each service when the `SonataFlowPlatform` CR is deployed. -Following is a basic configuration. It will deploy an ephemeral Data Index to the same namespace as the `SonataFlowPlatform`. +[NOTE] +==== +Each service configuration is considered independently, and you can combine these configurations with any other configuration present in the `SonataFlowPlatform` CR. +==== -.Example of a SonataFlowPlatform instance with an ephemeral Data Index deployment -[source,yaml,subs="attributes+"] +The following `SonataFlowPlatform` CR fragment shows a scaffold configuration that you can use as reference: +[#supporting-services-configuration] +.Supporting services configuration +[source,yam] ---- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: - name: sonataflow-platform + name: sonataflow-platform-example + namespace: example-namespace spec: services: - dataIndex: {} + dataIndex: <1> + enabled: true <2> + # Specific configurations for the Data Index Service + # might be included here + jobService: <3> + enabled: true <4> + # Specific configurations for the Job Service + # might be included here ---- +[#enabled-deployment-field] +<1> Data Index Service configuration field. +<2> If true, produces an enabled Data Index Service deployment, <<supporting-services-workflow-communications, see>>. Other cases produce a disabled deployment. The default is `false`. +<3> Job Service configuration field. +<4> If true, produces an enabled Job Service deployment, <<supporting-services-workflow-communications, see>>. Other cases produce a disabled deployment. The default is `false`. -If your use case requires persistence, Data Index supports a `postgresql` database. -First, you need to create a secret with credentials to access your postgresql deployment. +[NOTE] +==== +The configuration above produces an ephemeral deployment of each service, <<ephemeral-persistence-configuration, see>>. +==== -.Create a Secret for datasource authentication. -[source,bash,subs="attributes+"] ----- -kubectl create secret generic <creds-secret> --from-literal=POSTGRESQL_USER=<user> --from-literal=POSTGRESQL_PASSWORD=<password> --from-literal=POSTGRESQL_DATABASE=<db_name> -n workflows ----- +== Supporting Services Scope + +The `SonataFlowPlatform` CR facilitates the deployment of the supporting services with namespace scope. +It means that, all the automatically configured <<supporting-services-workflow-communications>>, are restricted to the namespace of the given platform. +This can be useful, in cases where you need separate supporting service instances for a set of workflows. +For example, a given application can be deployed isolated with its workflows, and the supporting services. -.Example of a SonataFlowPlatform instance with a Data Index deployment persisted to a postgresql database -[source,yaml,subs="attributes+"] +Additionally, using the `SonataFlowClusterPlatform` CR it's possible to configure a <<cluster-scoped-deployment, cluster scoped deployment>> of the supporting services. + +== Configuring the Supporting Services Persistence + +[#ephemeral-persistence-configuration] +=== Ephemeral persistence configuration + +The ephemeral persistence of a service is supported by and embedded PostgreSQL database dedicated to it. That database, is re-created by the operator on every service restart. Review Comment: ```suggestion The ephemeral persistence of a service is supported by an embedded PostgreSQL database dedicated to it. That database, is re-created by the operator on every service restart. ``` -- 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]
