From 92d8168e5685ab44fcabf449d42e0e2e1bb32568 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 12:41:49 +0200 Subject: [PATCH 1/8] kie-kogito-docs-631: Operator -> Cloud -> Deploy Supporting Services Section Updates --- .../modules/ROOT/pages/cloud/index.adoc | 8 - .../cloud/operator/enabling-jobs-service.adoc | 168 ---------- .../cloud/operator/global-configuration.adoc | 2 +- .../operator/install-serverless-operator.adoc | 2 +- .../cloud/operator/supporting-services.adoc | 309 ++++++++++-------- .../cloud/operator/using-persistence.adoc | 87 ++--- 6 files changed, 227 insertions(+), 349 deletions(-) delete mode 100644 serverlessworkflow/modules/ROOT/pages/cloud/operator/enabling-jobs-service.adoc diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc index ab459adea..e8cf3bbd8 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc @@ -39,14 +39,6 @@ xref:cloud/operator/install-serverless-operator.adoc[] Learn how to install the {operator_name} in a Kubernetes cluster -- -[.card] --- -[.card-title] -xref:cloud/operator/enabling-jobs-service.adoc[] -[.card-description] -Learn how to deploy the Jobs Service using {operator_name} in a Kubernetes cluster --- - [.card] -- [.card-title] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/enabling-jobs-service.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/enabling-jobs-service.adoc deleted file mode 100644 index 7d42dbd31..000000000 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/enabling-jobs-service.adoc +++ /dev/null @@ -1,168 +0,0 @@ -= Managing Jobs Service with the Operator -:compat-mode!: -// Metadata: -:description: Configure Jobs Service using the `SonataFlowPlatform` CR. -:keywords: sonataflow, serverless, operator, kubernetes, jobs service - - -This document describes how to configure the Jobs Service instance using the SonataFlowPlarform CR. - -== Automate the Jobs Service instance management with the `SonataFlow` Operator - -It is possible to deploy the Jobs Service manually, leveraging the Operator offers a more seamless integration by -combining it with namespace configuration through the SonataFlowPlatform Custom Resource (CR). When the Operator oversees -the lifecycle of the jobs service, it automatically injects necessary properties during creation into the SonataFlow workflows. -This integration eliminates the need for including these properties within the SonataFlow workflow CR instance, simplifying workflow management. -== Configuring Jobs Service in the SonataFlowPlatform CR - -To enable the deployment of a Jobs Service instance, the `SonataFlowPlatform` CRD exposes a set of fields that allow the user to -configure the running instance. - -=== Ephemeral persistence -The basic runtime is to deploy the Jobs Service with an ephemeral backend running in the same container -as the Jobs Service runtime. - -[source,yaml,subs="attributes+"] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform -spec: - services: - jobService: {} ---- - -When executing this manifest, the operator will reconcile generating a pod hosting the Jobs Service: - -[source,shell,subs="attributes+"] ---- -$>kubectl get pod -n sonataflow -NAME READY STATUS RESTARTS AGE -sonataflow-platform-jobs-service-cdf85d969-sbwkj 1/1 Running 0 108s ---- - -Keep in mind that this setup is not recommended for production environments, especially because the data does not persist when the pod restarts. - -=== Using an existing PostgreSQL service -For robust environments it is recommened to use a dedicated database service and configure Jobs Service to make use of it. Currently, the Jobs Service -only supports PostgreSQL database. - -Configuring Jobs Service to communicate with an existing PostgreSQL instance is supported in two ways. In both cases it requires providing the persistence -configuration, one by using the Jobs Service's persistence field and the other one using the persistence field defined in the `SonataFlowPlatform` CR -deployed in the same namespace. - -By default, the persistence specification defined in the `SonataFlow` workflow's CR takes priority over the one in the `SonataFlowPlatform` persistence specification. - -==== Using the persistence field defined in the `SonataFlowPlatform` CR -Using the persistence configuration in the `SonataFlowPlatform` CR located in the same namespace requires to have the `SonataFlow` CR persistence field configured -to have an empty `{}` value, signaling the Operator to derive the persistence from the active `SonataFlowPlatform`, when available. If no persistence is defined -the operator will fall back to the ephemeral persistence previously described. - -[source,yaml,subs="attributes+"] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform -spec: - persistence: - postgresql: - secretRef: - name: postgres-secrets - userKey: POSTGRES_USER - passwordKey: POSTGRES_PASSWORD - serviceRef: - name: postgres - port: 5432 - databaseName: sonataflow ---- - -And the `SonataFlow` CR looks like this: - -[source,yaml,subs="attributes+"] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlow -metadata: - name: callbackstatetimeouts - annotations: - sonataflow.org/description: Callback State Timeouts Example k8s - sonataflow.org/version: 0.0.1 -spec: - persistence: {} -... ---- - -When using the `jdbcUrl` field instead of `serviceRef`, the user is responsible for providing the correct JDBC URL connection value that does not contain a `database schema` -because the operator will use verbatim the contents of this field as the JDBC connection in the Jobs Service pod, and if it provides a schema that has been used or formatted -by a different client, the pod will fail to run. - -===== Using the persistence field inside the service specification -You can specify define the persistence configuration directly in the Jobs Service specification. The structure is the same as in the `SonataFlowPlatform` CR and also -consist on the credentials to access the PostgreSQL instance, and the kubernetes service reference to generate the connectivity. - -[source,yaml,subs="attributes+"] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: callbackstatetimeouts -spec: - persistence: - postgresql: - secretRef: - name: postgres-secrets - userKey: POSTGRES_USER - passwordKey: POSTGRES_PASSWORD - serviceRef: - name: postgres - port: 5432 - databaseName: sonataflow - databaseSchema: jobs-service ---- - -In this example we're using a PostgreSQL service located in the same namespace where the Jobs Service is deployed, pointing to the default PostgreSQL port of 5432 -and referencing the database `sonataflow` and schema `jobs-service`. By default, when the Jobs Service pod starts it will recreate the schema in the given location -if it doesn't exist. - -The values of `POSTGRES_USER` and `POSTGRES_PASSWORD` point to the keys in the secret that contains the PostgreSQL credentials. - -[source,shell,subs="attributes+"] ---- -$>kubectl describe secrets postgres-secrets -Name: postgres-secrets -Namespace: default -Labels: -Annotations: - -Type: Opaque - -Data -\\\\==== -PGDATA: 28 bytes -POSTGRES_DATABASE: 10 bytes -POSTGRES_PASSWORD: 10 bytes -POSTGRES_USER: 10 bytes ---- - -Putting everything together will render an output similar to this one below: - -[source,shell,subs="attributes+"] ---- -$>kubectl get pod -w -n sonataflow -NAME READY STATUS RESTARTS AGE -postgres-64c9ddb6bc-v96qb 1/1 Running 0 14m -sonataflow-platform-jobs-service-79bb6bc67f-gvcg4 1/1 Running 0 1m ---- - -== Conclusion -The Operator extends its scope to manage the lifecycle of the Jobs Service instance, thus removing the burden on the users and allowing them to focus on the -implementation of the `Sonataworkflows. It takes care of managing the Jobs Service deployment, dynamically configures its application properties -when the Data Index service is also available and managed by the Operator, and finally inject application properties in `SonataFlow` workflows in the target -namespace when the Jobs Service is available. - -== Additional resources -* xref:cloud/operator/install-serverless-operator.adoc[] - -include::../../../pages/_common-content/report-issue.adoc[] \ No newline at end of file diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc index 5b21d0d1f..e4a3649f5 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc @@ -30,7 +30,7 @@ You can freely edit any of the options in the key `controllers_cfg.yaml` entry. | `jobsServicePostgreSQLImageTag` | empty | The Jobs Service image for PostgreSQL to use, if empty the operator will use the default Apache Community one based on the current operator's version. | `jobsServiceEphemeralImageTag` | empty | The Jobs Service image without persistence to use, if empty the operator will use the default Apache Community one based on the current operator's version. | `dataIndexPostgreSQLImageTag` | empty | The Data Index image for PostgreSQL to use, if empty the operator will use the default Apache Community one based on the current operator's version. -| `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. +| `dataIndexEphemeralImageTag` | 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. diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc index 86c8d1f81..83edf84cf 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc @@ -140,6 +140,6 @@ The URL should be the same as the one you used when installing the operator. * xref:cloud/operator/known-issues.adoc[] * xref:cloud/operator/developing-workflows.adoc[] -* xref:cloud/operator/enabling-jobs-service.adoc[] +* xref:cloud/operator/supporting-services.adoc[Deploying the Supporting Services with the Operator] include::../../../pages/_common-content/report-issue.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index a4aef68d2..00cb4c8c4 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -6,190 +6,228 @@ // 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 <> 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 <> 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, <>. Other cases produce a disabled deployment. The default is `false`. +<3> Job Service configuration field. +<4> If true, produces an enabled Job Service deployment, <>. 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, <>. +==== -.Create a Secret for datasource authentication. -[source,bash,subs="attributes+"] ----- -kubectl create secret generic --from-literal=POSTGRESQL_USER= --from-literal=POSTGRESQL_PASSWORD= --from-literal=POSTGRESQL_DATABASE= -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 <>, 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 <> 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. +And thus, it's only recommended for development and testing purposes. + +The ephemeral deployment of a service requires no additional configurations than the shown, <>. + +[#postgresql-persistence-configuration] +=== PostgreSQL persistence configuration + +The PosgreSQL persistence of a service is supported by a PostgreSQL server instance, that you must previously install on the cluster. +The administration of that instance is totally independent of the {operator_name} scope, and to connect a supporting service with it, you must only configure the correct database connection parameters. + +The following `SonataFlowPlatform` CR fragment shows the configuration options that you must use: + +.PostgreSQL persistence configuration +[source,yaml] ---- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: - name: sonataflow-platform + name: sonataflow-platform-example + namespace: example-namespace spec: services: dataIndex: + enabled: true persistence: postgresql: - secretRef: - name: <1> serviceRef: - name: <2> + name: postgres-example <1> + namespace: postgres-example-namespace <2> + databaseName: example-database <3> + databaseSchema: data-index-schema <4> + port: 1234 <5> + secretRef: + name: postgres-secrets-example <6> + userKey: POSTGRESQL_USER <7> + passwordKey: POSTGRESQL_PASSWORD <8> + jobService: + enabled: true + persistence: + postgresql: + # Specific database configuration for the Job Service + # might be included here. ---- -<1> Name of your postgresql credentials secret -<2> Name of your postgresql k8s service +<1> Name of the Kubernetes Service to connect with the PostgreSQL database server. +<2> (Optional) Kubernetes namespace containing the PostgreSQL Service. Defaults to the `SonataFlowPlatform's` local namespace. +<3> Name of the PostgreSQL database to store the supporting service data. +<4> (Optional) Name of the PostgreSQL database schema to store the supporting service data. +Defaults to the `SonataFlowPlatform's` `name`, suffixed with `-data-index-service` or `-jobs-service`. For example, `sonataflow-platform-example-data-index-service`. +<5> (Optional) Port number to connect with the PostgreSQL Service. Defaults to 5432. +<6> Name of the link:{k8n_secrets_url}[Kubernetes Secret] containing the username and password to connect with the database. +<7> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the username to connect with the database. +<8> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the password to connect with the database. + +[NOTE] +==== +The persistence of each service can be configured independently by using the respective `persistence` field. +==== -.Example of a SonataFlowPlatform instance with a persisted Data Index deployment and custom pod configuration -[source,yaml,subs="attributes+"] +To create the secrets for the example above you can use a command like this: + +.Create secret example +[source,bash] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform -spec: - services: - dataIndex: - enabled: false <1> - persistence: - postgresql: - secretRef: - name: - userKey: <2> - jdbcUrl: "jdbc:postgresql://host:port/database?currentSchema=data-index-service" <3> - podTemplate: - replicas: 1 <4> - container: - image: <5> +kubectl create secret generic postgres-secrets-example --from-literal=POSTGRESQL_USER= --from-literal=POSTGRESQL_PASSWORD= -n postgres-example-namespace ---- -<1> Determines whether "preview" or "gitops" profile workflows should be configured to use this service, defaults to `true` -<2> Secret key of your postgresql credentials user, defaults to `POSTGRESQL_USER` -<3> PostgreSql JDBC URL -<4> Number of Data Index pods, defaults to `1` -<5> Custom Data Index container image name, if customization is required +[#common-persistence-configuration] +=== Common PostgreSQL persistence configuration -[#deploy-job-service] -=== Job Service +To configure common a PostgreSQL service instance for all the supporting services you must read, xref:cloud/operator/using-persistence.adoc#configuring-persistence-using-the-sonataflowplatform-cr[Configuring the persistence using the SonataFlowPlatform CR]. -You can deploy Job Service via `SonataFlowPlatform` configuration. The operator will then configure all new workflows, with the "preview" profile, to use that Job Service. +In that case, the {operator_name} will automatically connect any of the supporting services with that common server configured in the field `spec.persistence`. And, similarly to the workflow's persistence, the following precedence rules apply: -Following is a basic configuration. It will deploy an ephemeral Job Service to the same namespace as the `SonataFlowPlatform`. +* If a supporting service, has a configured persistence, for example, the field `services.dataIndex.persistence` is configured. That configuration will apply. -.Example of a SonataFlowPlatform instance with an ephemeral Job Service deployment -[source,yaml,subs="attributes+"] ----- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform -spec: - services: - jobService: {} ----- +* If a supporting service, has no configured persistence, for example, the field `services.dataIndex.persistence` is not set at all, the persistence configuration will be taken from the current platform. -If your use case requires persistence, Job Service supports a `postgresql` database. -First, you need to create a secret with credentials to access your postgresql deployment. -.Create a Secret for datasource authentication. -[source,bash,subs="attributes+"] ----- -kubectl create secret generic --from-literal=POSTGRESQL_USER= --from-literal=POSTGRESQL_PASSWORD= --from-literal=POSTGRESQL_DATABASE= -n workflows ----- +[NOTE] +==== +When you use the common PostgreSQL configuration, the database schema for each supporting service is automatically configured as the SonataFlowPlatform’s `name`, suffixed with `-data-index-service` or `-jobs-service` respectively. +For example, `sonataflow-platform-example-data-index-service`. +==== -.Example of a SonataFlowPlatform instance with a Job Service deployment persisted to a postgresql database -[source,yaml,subs="attributes+"] ----- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform -spec: - services: - jobService: - persistence: - postgresql: - secretRef: - name: <1> - serviceRef: - name: <2> ----- +== Advanced Supporting Services Configurations -<1> Name of your postgresql credentials secret -<2> Name of your postgresql k8s service +To configure the advanced options for any of the supporting services you must use the `podTemplate` field respectively, for example `dataIndex.podTemplate`: -.Example of a SonataFlowPlatform instance with a persisted Job Service deployment and custom pod configuration -[source,yaml,subs="attributes+"] +.Advanced configurations example for the Data Index Service. +[source,yaml] ---- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: - name: sonataflow-platform + name: sonataflow-platform-example + namespace: example-namespace spec: services: - jobService: - enabled: false <1> - persistence: - postgresql: - secretRef: - name: - userKey: <2> - jdbcUrl: "jdbc:postgresql://host:port/database?currentSchema=data-index-service" <3> + dataIndex: + enabled: true podTemplate: - replicas: 1 <4> - container: - image: <5> + replicas: 2 <1> + container: <2> + env: <3> + - name: ANY_ADVANCED_CONFIG_PROPERTY + value: any-value + image: <4> + initContainers: <5> ---- -<1> Determines whether "preview" or "gitops" profile workflows should be configured to use this service, defaults to `true` -<2> Secret key of your postgresql credentials user, defaults to `POSTGRESQL_USER` -<3> PostgreSql JDBC URL -<4> Number of Job Service pods, defaults to `1` -<5> Custom Job Service container image name, if customization is required +<1> Number of replicas. Defaults to 1. In the case of the jobService this value is always overridden to 1 by the operator, since that service is a singleton service. +<2> Holds the particular configurations for the container that will execute the given supporting service. +<3> Standard Kubernetes `env` configuration. This can be useful in cases where you need to fine tune any of the supporting services properties. +<4> Standard Kubernetes `image` configuration. This can be useful in cases where you need to use an updated image for any of the supporting services. +<5> Standard Kubernetes `initContainers` for the Pod that executes the supporting service. + +[NOTE] +==== +The `podTemplate` field of any supporting has the majority of fields defined in the default Kubernetes PodSpec API. +The same Kubernetes API validation rules applies to these fields. +==== -[#cluster-wide-services] -== Cluster-Wide Supporting Services +[#cluster-scoped-deployment] +== Cluster Scoped Supporting Services -The `SonataFlowClusterPlatform` CR is optionally used to specify a cluster-wide set of supporting services for workflow consumption. This is done by referencing an existing, namespaced `SonataFlowPlatform` resource. +The `SonataFlowClusterPlatform` CR is optionally used to specify a cluster-wide set of supporting services for workflow consumption. +This is done by referencing an existing, namespaced `SonataFlowPlatform` CR. -Following is a basic configuration that allows workflows, deployed in any namespace, to leverage supporting services configured in the chosen "central" namespace. +Following is a basic configuration that allows workflows, deployed in any namespace, to leverage supporting services deployed in the chosen `example-namespace` namespace. -.Example of a basic SonataFlowClusterPlatform CR -[source,yaml,subs="attributes+"] +.Example of a SonataFlowClusterPlatform CR +[source,yaml] ---- apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowClusterPlatform @@ -197,19 +235,30 @@ metadata: name: cluster-platform spec: platformRef: - name: sonataflow-platform - namespace: + name: sonataflow-platform-example <1> + namespace: example-namespace <2> ---- +<1> Name of the already installed `SonatataFlowPlatform` CR that configures the supporting services. +<2> Namespace of the already installed `SontataFlowPlatform` CR that configures the supporting services. + [NOTE] ==== These cluster-wide services can be overridden in any namespace, by configuring that namespace's `SonataFlowPlatform.spec.services`. ==== +== Conclusions + +The {operator_name} extends its scope to manage the lifecycle of the xref:data-index/data-index-core-concepts.adoc[Data Index] and xref:job-services/core-concepts.adoc[Job Service] instances, thus removing the burden on the users and allowing them to focus on the implementation of the workflows. +It takes care also of managing all the configurations to facilitate communication between the workflows and the supporting services. +Additionally, it can manage different persistence options for each service, and advanced configurations. + + == Additional resources -* xref:data-index/data-index-service.adoc[] -* xref:cloud/operator/enabling-jobs-service.adoc[] +* xref:data-index/data-index-core-concepts.adoc[] +* xref:job-services/core-concepts.adoc[Job Service Core Concepts] +* xref:cloud/operator/using-persistence.adoc[] * xref:cloud/operator/known-issues.adoc[] include::../../../pages/_common-content/report-issue.adoc[] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc index 8e39f3580..54a6e1778 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/using-persistence.adoc @@ -10,14 +10,17 @@ Kubernetes's pods are stateless by definition. In some scenarios, this can be a 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. 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. +That configuration must be provided by using the <> or the <<_configuring_the_persistence_using_the_sonataflow_cr, `SonataFlow` CR>>, and has different scopes depending on each case. +[#configuring-persistence-using-the-sonataflowplatform-cr] == Configuring the persistence using the SonataFlowPlatform CR 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>>. +Finally, the {operator_name} can also use this configuration to set the xref:cloud/operator/supporting-services.adoc#common-persistence-configuration[supporting service's persistence]. + [NOTE] ==== Persistence configurations are applied at workflow deployment time, and potential changes in the SonataFlowPlatform will not impact already deployed workflows. @@ -31,30 +34,31 @@ To configure the persistence you must use the `persistence` field in the SonataF apiVersion: sonataflow.org/v1alpha08 kind: SonataFlowPlatform metadata: - name: sonataflow-platform + name: sonataflow-platform-example + namespace: example-namespace spec: 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> - port: 1234 <7> + name: postgres-example <1> + namespace: postgres-example-namespace <2> + databaseName: example-database <3> + port: 1234 <4> + secretRef: + name: postgres-secrets-example <5> + userKey: POSTGRESQL_USER <6> + passwordKey: POSTGRESQL_PASSWORD <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. +<1> Name of the Kubernetes Service to connect with the PostgreSQL database server. +<2> (Optional) Kubernetes namespace containing the PostgreSQL Service. Defaults to the `SonataFlowPlatform's` local namespace. +<3> Name of the PostgreSQL database to store the workflow's data. +<4> (Optional) Port number to connect with the PostgreSQL Service. Defaults to 5432. +<5> Name of the link:{k8n_secrets_url}[Kubernetes Secret] containing the username and password to connect with the database. +<6> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the username to connect with the database. +<7> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the password to connect with the database. -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. +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. @@ -75,18 +79,18 @@ For simplicity, only the `env` configurations related to the persistence has bee - name: QUARKUS_DATASOURCE_USERNAME valueFrom: secretKeyRef: - name: postgres-secrets + name: postgres-secrets-example key: POSTGRESQL_USER - name: QUARKUS_DATASOURCE_PASSWORD valueFrom: secretKeyRef: - name: postgres-secrets + name: postgres-secrets-example 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 + jdbc:postgresql://postgres-example.postgres-example-namespace:1234/sonataflow?currentSchema=example-workflow - name: KOGITO_PERSISTENCE_TYPE value: jdbc ---- @@ -117,28 +121,29 @@ metadata: spec: 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> + name: postgres-example <1> + namespace: postgres-example-namespace <2> + databaseName: example-database <3> + databaseSchema: example-schema <4> + port: 1234 <5> + secretRef: + name: postgres-secrets-example <6> + userKey: POSTGRESQL_USER <7> + passwordKey: POSTGRESQL_PASSWORD <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. +<1> Name of the Kubernetes Service to connect with the PostgreSQL database server. +<2> (Optional) Kubernetes namespace containing the PostgreSQL Service. Defaults to the workflow's local namespace. +<3> Name of the PostgreSQL database to store the workflow's data. +<4> (Optional) Name of the database schema to store workflow's data. Defaults to the workflow's name. +<5> (Optional) Port number to connect with the PostgreSQL Service. Defaults to 5432. +<6> Name of the link:{k8n_secrets_url}[Kubernetes Secret] containing the username and password to connect with the database. +<7> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the username to connect with the database. +<8> Name of the link:{k8n_secrets_url}[Kubernetes Secret] `key` containing the password to connect with the database. + 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 <> to the workflow container. @@ -154,9 +159,9 @@ To learn how to initialize the database schema see: <<_database_schema_initializ == Persistence configuration precedence rules -<<_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>>. +<> can be used with or without the <>. -And, if the current namespace has an already configured <<_configuring_the_persistence_using_the_sonataflowplatform_cr, `SonataFlowPlatform` CR persistence>>, the following rules apply: +And, if the current namespace has an already configured <>, 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. @@ -280,7 +285,7 @@ To initialize the database schema manually, you must be sure that the following 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. +* When you use the <> it is possible to use the schema name of your choice. ==== == Conclusion From 6905ce6037f840b44d08d8f2e27324a652511a06 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:46:53 +0200 Subject: [PATCH 2/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index 00cb4c8c4..e9e142daa 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -93,7 +93,7 @@ Additionally, using the `SonataFlowClusterPlatform` CR it's possible to configur [#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. +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. And thus, it's only recommended for development and testing purposes. The ephemeral deployment of a service requires no additional configurations than the shown, <>. From fc1a8d129562355ca382e645a71f75a3fc52c881 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:47:12 +0200 Subject: [PATCH 3/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index e9e142daa..255f463cf 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -165,7 +165,7 @@ kubectl create secret generic postgres-secrets-example --from-literal=POSTGRESQ [#common-persistence-configuration] === Common PostgreSQL persistence configuration -To configure common a PostgreSQL service instance for all the supporting services you must read, xref:cloud/operator/using-persistence.adoc#configuring-persistence-using-the-sonataflowplatform-cr[Configuring the persistence using the SonataFlowPlatform CR]. +To configure a common PostgreSQL service instance for all the supporting services you must read, xref:cloud/operator/using-persistence.adoc#configuring-persistence-using-the-sonataflowplatform-cr[Configuring the persistence using the SonataFlowPlatform CR]. In that case, the {operator_name} will automatically connect any of the supporting services with that common server configured in the field `spec.persistence`. And, similarly to the workflow's persistence, the following precedence rules apply: From 7eeff41e3257e11c4302f6c65c3be6bb11e5fc68 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:49:44 +0200 Subject: [PATCH 4/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index 255f463cf..1b40c3328 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -169,7 +169,7 @@ To configure a common PostgreSQL service instance for all the supporting service In that case, the {operator_name} will automatically connect any of the supporting services with that common server configured in the field `spec.persistence`. And, similarly to the workflow's persistence, the following precedence rules apply: -* If a supporting service, has a configured persistence, for example, the field `services.dataIndex.persistence` is configured. That configuration will apply. +* If a supporting service has a configured persistence, for example, the field `services.dataIndex.persistence` is configured. That configuration will apply. * If a supporting service, has no configured persistence, for example, the field `services.dataIndex.persistence` is not set at all, the persistence configuration will be taken from the current platform. From e8be04074b3c98872bfc5c1a978c506e9d773ee1 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:50:01 +0200 Subject: [PATCH 5/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index 1b40c3328..1c754c5f9 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -171,7 +171,7 @@ In that case, the {operator_name} will automatically connect any of the supporti * If a supporting service has a configured persistence, for example, the field `services.dataIndex.persistence` is configured. That configuration will apply. -* If a supporting service, has no configured persistence, for example, the field `services.dataIndex.persistence` is not set at all, the persistence configuration will be taken from the current platform. +* If a supporting service has no configured persistence, for example, the field `services.dataIndex.persistence` is not set at all, the persistence configuration will be taken from the current platform. [NOTE] From ef25a69d9230314b0279b4fb1ef17483ea396323 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:50:38 +0200 Subject: [PATCH 6/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index 1c754c5f9..ae30cdeba 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -214,7 +214,7 @@ spec: [NOTE] ==== -The `podTemplate` field of any supporting has the majority of fields defined in the default Kubernetes PodSpec API. +The `podTemplate` field of any supporting service has the majority of fields defined in the default Kubernetes PodSpec API. The same Kubernetes API validation rules applies to these fields. ==== From 1b0281f24933e2ae71010fd9938476767b58b487 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 14:50:52 +0200 Subject: [PATCH 7/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc Co-authored-by: nmirasch --- .../modules/ROOT/pages/cloud/operator/supporting-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc index ae30cdeba..ab1a50469 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc @@ -215,7 +215,7 @@ spec: [NOTE] ==== The `podTemplate` field of any supporting service has the majority of fields defined in the default Kubernetes PodSpec API. -The same Kubernetes API validation rules applies to these fields. +The same Kubernetes API validation rules apply to these fields. ==== [#cluster-scoped-deployment] From cbd969e050321645c8f0c2f8c69f605e7feff32e Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 4 Jun 2024 16:13:13 +0200 Subject: [PATCH 8/8] Update serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- .../ROOT/pages/cloud/operator/install-serverless-operator.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc index 83edf84cf..4f9e2df3d 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc @@ -140,6 +140,6 @@ The URL should be the same as the one you used when installing the operator. * xref:cloud/operator/known-issues.adoc[] * xref:cloud/operator/developing-workflows.adoc[] -* xref:cloud/operator/supporting-services.adoc[Deploying the Supporting Services with the Operator] +* xref:cloud/operator/supporting-services.adoc[Deploying Supporting Services with the Operator] include::../../../pages/_common-content/report-issue.adoc[]