Skip to content

Commit 6d21f96

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #83119 from kaldesai/SRVLOGIC-352-Supporting-Services
PR for SRVLOGIC-352: Document "Supporting Services" section in the OSL docs.
2 parents 767fa87 + 2a99d82 commit 6d21f96

8 files changed

+281
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -382,6 +382,8 @@ Topics:
382382
File: serverless-logic-job-service
383383
- Name: Data Index service
384384
File: serverless-logic-data-index
385+
- Name: Managing supporting services
386+
File: serverless-logic-managing-supporting-services
385387
---
386388
# Knative kn CLI
387389
Name: Knative CLI

‎modules/serverless-logic-cluster-scope-supporting-services.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="serverless-logic-cluster-scope-supporting-services_{context}"]
7+
= Cluster scoped supporting services
8+
9+
You can define a cluster-wide set of supporting services that can be consumed by workflows across different namespaces, by using the `SonataFlowClusterPlatform` custom resource (CR). By referencing an existing namespace-specific `SonataFlowPlatform` CR, you can extend the use of these services cluster-wide.
10+
11+
You can use the following example of a basic configuration that enables workflows deployed in any namespace to utilize supporting services deployed in a specific namespace, such as `example-namespace`:
12+
13+
.Example of a `SonataFlowClusterPlatform` CR
14+
[source,yaml]
15+
----
16+
apiVersion: sonataflow.org/v1alpha08
17+
kind: SonataFlowClusterPlatform
18+
metadata:
19+
name: cluster-platform
20+
spec:
21+
platformRef:
22+
name: sonataflow-platform-example <1>
23+
namespace: example-namespace <2>
24+
----
25+
26+
<1> Specifies the name of the already installed `SonataFlowPlatform` CR that manages the supporting services.
27+
<2> Specifies the namespace of the `SonataFlowPlatform` CR that manages the supporting services.
28+
29+
[NOTE]
30+
====
31+
You can override these cluster-wide services within any namespace by configuring that namespace in `SonataFlowPlatform.spec.services`.
32+
====

‎modules/serverless-logic-supporting-services-advanced-configuration.adoc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="serverless-logic-supporting-services-advanced-configuration_{context}"]
7+
= Advanced supporting services configurations
8+
9+
In scenarios where you must apply advanced configurations for supporting services, use the `podTemplate` field in the `SonataFlowPlatform` custom resource (CR). This field allows you to customize the service pod deployment by specifying configurations like the number of replicas, environment variables, container images, and initialization options.
10+
11+
You can configure advanced settings for the service by using the following example:
12+
13+
.Advanced configurations example for the Data Index service
14+
[source,yaml]
15+
----
16+
apiVersion: sonataflow.org/v1alpha08
17+
kind: SonataFlowPlatform
18+
metadata:
19+
name: sonataflow-platform-example
20+
namespace: example-namespace
21+
spec:
22+
services:
23+
# This can be either 'dataIndex' or 'jobService'
24+
dataIndex:
25+
enabled: true
26+
podTemplate:
27+
replicas: 2 <1>
28+
container: <2>
29+
env: <3>
30+
- name: <any_advanced_config_property>
31+
value: <any_value>
32+
image: <4>
33+
initContainers: <5>
34+
----
35+
36+
[NOTE]
37+
====
38+
You can set the 'services' field to either 'dataIndex' or 'jobService' depending on your requirement. The rest of the configuration remains the same.
39+
====
40+
41+
<1> Defines the number of replicas. Default value is `1`. In the case of `jobService`, this value is always overridden to `1` because it operates as a singleton service.
42+
<2> Holds specific configurations for the container running the service.
43+
<3> Allows you to fine-tune service properties by specifying environment variables.
44+
<4> Configures the container image for the service, useful if you need to update or customize the image.
45+
<5> Configures init containers for the pod, useful for setting up prerequisites before the main container starts.
46+
47+
[NOTE]
48+
====
49+
The `podTemplate` field provides flexibility for tailoring the deployment of each supporting service. It follows the standard `PodSpec` API, meaning the same API validation rules apply to these fields.
50+
====

‎modules/serverless-logic-supporting-services-deployment-sonataflowplatform-cr.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="serverless-logic-supporting-services-deployment-sonataflowplatform-cr_{context}"]
7+
= Supporting services deployment with the SonataFlowPlatform CR
8+
9+
To deploy supporting services, configure the `dataIndex` and `jobService` subfields within the `spec.services` section of the `SonataFlowPlatform` custom resource (CR). This configuration instructs the {ServerlessLogicOperatorName} to deploy each service when the `SonataFlowPlatform` CR is applied.
10+
11+
Each configuration of a service is handled independently, allowing you to customize these settings alongside other configurations in the `SonataFlowPlatform` CR.
12+
13+
See the following scaffold example configuration for deploying supporting services:
14+
15+
[source,yaml]
16+
----
17+
apiVersion: sonataflow.org/v1alpha08
18+
kind: SonataFlowPlatform
19+
metadata:
20+
name: sonataflow-platform-example
21+
namespace: example-namespace
22+
spec:
23+
services:
24+
dataIndex: <1>
25+
enabled: true <2>
26+
# Specific configurations for the Data Index Service
27+
# might be included here
28+
jobService: <3>
29+
enabled: true <4>
30+
# Specific configurations for the Job Service
31+
# might be included here
32+
----
33+
34+
<1> Data Index service configuration field.
35+
<2> Setting `enabled: true` deploys the Data Index service. If set to `false` or omitted, the deployment will be disabled. The default value is `false`.
36+
<3> Job Service configuration field.
37+
<4> Setting `enabled: true` deploys the Job Service. If set to `false` or omitted, the deployment will be disabled. The default value is `false`.

‎modules/serverless-logic-supporting-services-persistence-configuration.adoc

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="serverless-logic-supporting-services-persistence-configuration_{context}"]
7+
= Supporting services persistence configurations
8+
9+
The persistence configuration for supporting services in {ServerlessLogicProductName} can be either ephemeral or PostgreSQL, depending on needs of your environment. Ephemeral persistence is ideal for development and testing, while PostgreSQL persistence is recommended for production environments.
10+
11+
[id="serverless-logic-supporting-services-ephemeral-persistence-config_{context}"]
12+
== Ephemeral persistence configuration
13+
14+
The ephemeral persistence uses an embedded PostgreSQL database that is dedicated to each service. The {ServerlessLogicOperatorName} recreates this database with every service restart, making it suitable only for development and testing purposes. You do not need any additional configuration other than the following `SonataFlowPlatform` CR:
15+
16+
[source,yaml]
17+
----
18+
apiVersion: sonataflow.org/v1alpha08
19+
kind: SonataFlowPlatform
20+
metadata:
21+
name: sonataflow-platform-example
22+
namespace: example-namespace
23+
spec:
24+
services:
25+
dataIndex:
26+
enabled: true
27+
# Specific configurations for the Data Index Service
28+
# might be included here
29+
jobService:
30+
enabled: true
31+
# Specific configurations for the Job Service
32+
# might be included here
33+
----
34+
35+
[id="serverless-logic-supporting-services-postgresql-persistence-config_{context}"]
36+
== PostgreSQL persistence configuration
37+
38+
For PostgreSQL persistence, you must set up a PostgreSQL server instance on your cluster. The administration of this instance remains independent of the {ServerlessLogicOperatorName} control. To connect a supporting service with the PostgreSQL server, you must configure the appropriate database connection parameters.
39+
40+
You can configure PostgreSQL persistence in the `SonataFlowPlatform` CR by using the following example:
41+
42+
.Example of PostgreSQL persistence configuration
43+
[source,yaml]
44+
----
45+
apiVersion: sonataflow.org/v1alpha08
46+
kind: SonataFlowPlatform
47+
metadata:
48+
name: sonataflow-platform-example
49+
namespace: example-namespace
50+
spec:
51+
services:
52+
dataIndex:
53+
enabled: true
54+
persistence:
55+
postgresql:
56+
serviceRef:
57+
name: postgres-example <1>
58+
namespace: postgres-example-namespace <2>
59+
databaseName: example-database <3>
60+
databaseSchema: data-index-schema <4>
61+
port: 1234 <5>
62+
secretRef:
63+
name: postgres-secrets-example <6>
64+
userKey: POSTGRESQL_USER <7>
65+
passwordKey: POSTGRESQL_PASSWORD <8>
66+
jobService:
67+
enabled: true
68+
persistence:
69+
postgresql:
70+
# Specific database configuration for the Job Service
71+
# might be included here.
72+
----
73+
74+
<1> Name of the service to connect with the PostgreSQL database server.
75+
<2> Optional: Defines the namespace of the PostgreSQL Service. Defaults to the SonataFlowPlatform namespace.
76+
<3> Defines the name of the PostgreSQL database for storing supporting service data.
77+
<4> Optional: Specifies the schema for storing supporting service data. Default value is `SonataFlowPlatform` name, suffixed with `-data-index-service` or `-jobs-service`. For example, `sonataflow-platform-example-data-index-service`.
78+
<5> Optional: Port number to connect with the PostgreSQL Service. Default value is `5432`.
79+
<6> Defines the name of the secret containing the username and password for database access.
80+
<7> Defines the name of the key in the secret that contains the username to connect with the database.
81+
<8> Defines the name of the key in the secret that contains the password to connect with the database.
82+
83+
[NOTE]
84+
====
85+
You can configure each service’s persistence independently by using the respective persistence field.
86+
====
87+
88+
Create the secrets to access PostgreSQL by running the following command:
89+
90+
[source,terminal]
91+
----
92+
$ oc create secret generic <postgresql_secret_name> \
93+
--from-literal=POSTGRESQL_USER=<user> \
94+
--from-literal=POSTGRESQL_PASSWORD=<password> \
95+
-n <namespace>
96+
----
97+
98+
[id="serverless-logic-supporting-services-common-postgresql-persistence-config_{context}"]
99+
== Common PostgreSQL persistence configuration
100+
101+
The {ServerlessLogicOperatorName} automatically connects supporting services to the common PostgreSQL server configured in the `spec.persistence` field.
102+
103+
For rules, the following precedence is applicable:
104+
105+
* If you configure a specific persistence for a supporting service, for example, `services.dataIndex.persistence`, it uses that configuration.
106+
* If you do not configure persistence for a service, the system uses the common persistence configuration from the current platform.
107+
108+
[NOTE]
109+
====
110+
When using a common PostgreSQL configuration, each service schema is automatically set as the `SonataFlowPlatform` name, suffixed with `-data-index-service` or `-jobs-service`, for example, `sonataflow-platform-example-data-index-service`.
111+
====

‎modules/serverless-logic-supporting-services-scope.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="serverless-logic-supporting-services-scope_{context}"]
7+
= Supporting services scope
8+
9+
The `SonataFlowPlatform` custom resource (CR) enables the deployment of supporting services within a specific namespace. This means all automatically configured supporting services and workflow communications are restricted to the namespace of the deployed platform.
10+
11+
This feature is particularly useful when separate instances of supporting services are required for different sets of workflows. For example, you can deploy an application in isolation with its workflows and supporting services, ensuring they remain independent from other deployments.

‎modules/serverless-logic-supporting-services-workflow-integration.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Module included in the following assemblies:
2+
// * serverless-logic/serverless-logic-managing-supporting-services
3+
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="serverless-logic-supporting-services-workflow-integration_{context}"]
7+
= Supporting services and workflow integration
8+
9+
When you deploy a supporting service in a given namespace, you can choose between an enabled or disabled deployment. An enabled deployment signals the {ServerlessLogicOperatorName} to automatically intercept workflow deployments using the `preview` or `gitops` profile within the namespace and configure them to connect with the service.
10+
11+
For example, when the Data Index service is enabled, workflows are automatically configured to send status change events to it. Similarly, enabling the Job Service ensures that a job is created whenever a workflow requires a timeout. The {ServerlessLogicOperatorName} also configures the Job Service to send events to the Data Index service, facilitating seamless integration between the services.
12+
13+
The {ServerlessLogicOperatorName} does not just deploy supporting services, it also manages other necessary configurations to ensure successful workflow execution. All these configurations are handled automatically. You only need to provide the supporting services configuration in the `SonataFlowPlatform` CR.
14+
15+
[NOTE]
16+
====
17+
Deploying only one of the supporting services or using a disabled deployment are advanced use cases. In a standard installation, you must enable both services to ensure smooth workflow execution.
18+
====
19+

‎serverless-logic/serverless-logic-supporting-services/serverless-logic-managing-supporting-services.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="serverless-logic-managing-supporting-services"]
3+
= Managing supporting services
4+
include::_attributes/common-attributes.adoc[]
5+
:context: serverless-logic-managing-supporting-services
6+
7+
toc::[]
8+
9+
This section provides an overview of the supporting services essential for {ServerlessLogicProductName}. It specifically focuses on configuring and deploying the Data Index service and Job Service supporting services using the {ServerlessLogicOperatorName}.
10+
11+
In a typical {ServerlessLogicProductName} installation, you must deploy both services to ensure successful workflow execution. The Data Index service allows for efficient data management, while the Job Service ensures reliable job handling.
12+
13+
include::modules/serverless-logic-supporting-services-workflow-integration.adoc[leveloffset=+1]
14+
include::modules/serverless-logic-supporting-services-deployment-sonataflowplatform-cr.adoc[leveloffset=+1]
15+
include::modules/serverless-logic-supporting-services-scope.adoc[leveloffset=+1]
16+
include::modules/serverless-logic-supporting-services-persistence-configuration.adoc[leveloffset=+1]
17+
include::modules/serverless-logic-supporting-services-advanced-configuration.adoc[leveloffset=+1]
18+
include::modules/serverless-logic-cluster-scope-supporting-services.adoc[leveloffset=+1]
19+

0 commit comments

Comments
 (0)