Supporting Services

This document describes how to configure and deploy the SonataFlow’s Data Index and Job Service supporting services, using the SonataFlow Operator.

In general, in a regular SonataFlow 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

Supporting Services and Workflow communications

When you deploy a supporting service in a given namespace, you can do it by using an enabled or disabled deployment.

An enabled deployment, signals the SonataFlow Operator 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.

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.

Deploying the supporting services using the SonataFlowPlatform CR

To deploy the supporting services you must use the sub-fields dataIndex and jobService in the SonataFlowPlatform CR spec.services. That information signals the SonataFlow Operator to deploy each service when the SonataFlowPlatform CR is deployed.

Each service configuration is considered independently, and you can combine these configurations with any other configuration present in the SonataFlowPlatform CR.

The following SonataFlowPlatform CR fragment shows a scaffold configuration that you can use as reference:

Supporting services configuration
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  services:
    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
1 Data Index Service configuration field.
2 If true, produces an enabled Data Index Service deployment, 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, see. Other cases produce a disabled deployment. The default is false.

The configuration above produces an ephemeral deployment of each service, see.

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 and 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.

Additionally, using the SonataFlowClusterPlatform CR it’s possible to configure a cluster scoped deployment of the supporting services.

Configuring the Supporting Services Persistence

Ephemeral persistence configuration

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, here.

PostgreSQL persistence configuration

The PostgreSQL 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 SonataFlow Operator 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
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  services:
    dataIndex:
      enabled: true
      persistence:
        postgresql:
          serviceRef:
            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 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 Kubernetes Secret containing the username and password to connect with the database.
7 Name of the Kubernetes Secret key containing the username to connect with the database.
8 Name of the Kubernetes Secret key containing the password to connect with the database.

The persistence of each service can be configured independently by using the respective persistence field.

To create the secrets for the example above you can use a command like this:

Create secret example
kubectl create secret generic postgres-secrets-example  --from-literal=POSTGRESQL_USER=<user> --from-literal=POSTGRESQL_PASSWORD=<password> -n postgres-example-namespace

Common PostgreSQL persistence configuration

To configure a common PostgreSQL service instance for all the supporting services you must read, Configuring the persistence using the SonataFlowPlatform CR.

In that case, the SonataFlow Operator 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 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.

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.

Configuring the supporting services Eventing system

In general, the following events are produced in a SonataFlow installation:

  • Workflow outgoing and incoming business events.

  • SonataFlow system events sent from the workflow to the Data Index and Job Service respectively.

  • SonataFlow system events sent from the Jobs Service to the Data Index Service.

The SonataFlow Operator is designed to use the Knative Eventing system to resolve all the event communication between these services.

In a regular SonataFlow installation, the preferred method is to use the Platform scoped Eventing System Configuration, while the Service scoped Eventing System configuration is reserved only for advanced use cases.

Platform-scoped Eventing system configuration

To configure a platform-scoped eventing system, you must use the field spec.eventing.broker.ref in the SonataFlowPlatform CR to refer to a Knative Eventing Broker.

This information signals the SonataFlow Operator to automatically link the supporting services to produce and consume the events by using that Broker.

Additionally, workflows deployed in that namespace, that don’t provide a custom eventing system configuration, will be linked to that Broker.

The following SonataFlowPlatform CR fragment shows an example of such configuration:

Platform scoped eventing system configuration example
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  eventing:
    broker:
      ref:
        name: example-broker (1)
        namespace: example-broker-namespace (2)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
1 Name of the Knative Eventing Broker.
2 Optional: Defines the namespace of the Knative Eventing Broker. Defaults to the SonataFlowPlatform namespace. In general, we recommend creating the Knative Eventing Broker in the same namespace as the SonataFlowPlatform.

In production environments, you must use a production-ready broker, like the Knative Kafka Broker.

Service-scoped Eventing system configuration

A service scoped eventing system configuration provides the ability to do a fine-grained configuration of the Eventing system for the Data Index or the Jobs Service.

In a regular SonataFlow installation, the preferred method is to use a Platform-scoped Eventing System Configuration, while the service-scoped configuration is reserved only for advanced use cases.

Data Index Eventing system configuration

To configure a service-scoped eventing system for the Data Index, you must use the field spec.services.dataIndex.source.ref in the SonataFlowPlatform CR to refer to a specific Knative Eventing Broker.

This information signals the SonataFlow Operator to automatically link the Data Index to consume the SonataFlow system events from that Broker.

Data Index service scoped eventing system configuration example
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
spec:
  services:
    dataIndex:
      source:
        ref:
          name: data-index-source-example-broker (1)
          namespace: data-index-source-example-broker-namespace (2)
          apiVersion: eventing.knative.dev/v1
          kind: Broker
1 Name of the Knative Eventing Broker to consume events from.
2 Optional: Defines the namespace of the Knative Eventing Broker. Defaults to the SonataFlowPlatform namespace. In general, we recommend creating the Knative Eventing Broker in the same namespace as the SonataFlowPlatform.

In production environments, you must use a production-ready broker, like the Knative Kafka Broker.

Jobs Service Eventing system configuration

To configure a service-scoped eventing system for the Jobs Service, you must use the fields spec.services.jobService.source.ref and spec.services.jobService.sink.ref in the SonataFlowPlatform CR.

This information signals the SonataFlow Operator to automatically link the Jobs Service to consume and produce the SonataFlow system events from that configuration respectively.

Jobs Service scoped eventing system configuration example
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
spec:
  services:
    jobService:
      source:
        ref:
          name: jobs-service-source-example-broker (1)
          namespace: jobs-service-source-example-broker-namespace (2)
          apiVersion: eventing.knative.dev/v1
          kind: Broker
      sink:
        ref:
          name: jobs-service-sink-example-broker (3)
          namespace: jobs-service-sink-example-broker-namespace (4)
          apiVersion: eventing.knative.dev/v1
          kind: Broker
1 Name of the Knative Eventing Broker to consume events from.
2 Optional: Defines the namespace of the Knative Eventing Broker. Defaults to the SonataFlowPlatform namespace. In general, we recommend creating the Knative Eventing Broker in the same namespace as the SonataFlowPlatform.
3 Name of the Knative Eventing Broker to produce events on.
4 Optional: Defines the namespace of the Knative Eventing Broker. Defaults to the SonataFlowPlatform namespace. In general, we recommend creating the Knative Eventing Broker in the same namespace as the SonataFlowPlatform.

In production environments, you must use production-ready brokers, like the Knative Kafka Broker.

Cluster-scoped Eventing system configuration

When you use a Cluster Scoped Supporting Services deployment, the supporting services are automatically linked to the Broker configured in the SonataFlowPlatform CR referred to by the SonataFlowClusterPlatform CR.

Eventing system configuration precedence rules

To configure the eventing system for a supporting service, the SonataFlow Operator use the following precedence rules:

Eventing System linking objects

The linking of the supporting services with the Eventing System is produced by using Knative Eventing SinkBindings and Triggers. These objects are automatically created by the SonataFlow Operator, and facilitate the events production and consumption from the supporting services.

The following example shows the Knative Native eventing objects created for the SonataFlowPlatform CR:

SonataFlowPlatform eventing system configuration example
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  eventing:
    broker:
      ref:
        name: example-broker (1)
        apiVersion: eventing.knative.dev/v1
        kind: Broker
  services:
    dataIndex: (2)
      enabled: true
    jobService: (3)
      enabled: true
1 Platform Broker configuration used by the Data Index, Jobs Service, and the workflows if not overridden.
2 Data Index ephemeral deployment.
3 Jobs Service ephemeral deployment.
Knative Kafka Broker example used by the SonataFlowPlatform
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  annotations:
    eventing.knative.dev/broker.class: Kafka (1)
  name: example-broker
  namespace: example-namespace
spec:
  config:
    apiVersion: v1
    kind: ConfigMap
    name: kafka-broker-config
    namespace: knative-eventing
1 Use the Kafka class to create a Kafka Knative Broker
Knative Eventing Triggers created for the Data Index and Jobs Service events consumption
kn trigger list -n example-namespace

NAME                                                              BROKER           SINK                                                     AGE    CONDITIONS   READY   REASON
data-index-jobs-fbf285df-c0a4-4545-b77a-c232ec2890e2              example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-definition-e48b4e4bf73e22b90ecf7e093ff6b1eaf   example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-error-fbf285df-c0a4-4545-b77a-c232ec2890e2     example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-node-fbf285df-c0a4-4545-b77a-c232ec2890e2      example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-sla-fbf285df-c0a4-4545-b77a-c232ec2890e2       example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-state-fbf285df-c0a4-4545-b77a-c232ec2890e2     example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True
data-index-process-variable-ac727d6051750888dedb72f697737c0dfbf   example-broker   service:sonataflow-platform-example-data-index-service   106s   7 OK / 7     True

jobs-service-create-job-fbf285df-c0a4-4545-b77a-c232ec2890e2      example-broker   service:sonataflow-platform-example-jobs-service         106s   7 OK / 7     True
jobs-service-delete-job-fbf285df-c0a4-4545-b77a-c232ec2890e2      example-broker   service:sonataflow-platform-example-jobs-service         106s   7 OK / 7     True
Knative Eventing SinkBinding created for the Jobs Service events production
kn source list -n example-namespace

NAME                                          TYPE          RESOURCE                           SINK                    READY
sonataflow-platform-example-jobs-service-sb   SinkBinding   sinkbindings.sources.knative.dev   broker:example-broker   True

Advanced Supporting Services Configurations

To configure the advanced options for any of the supporting services you must use the podTemplate field respectively, for example dataIndex.podTemplate:

Advanced configurations example for the Data Index Service.
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  services:
    dataIndex:
      enabled: true
      podTemplate:
        replicas: 2 (1)
        container: (2)
          env: (3)
            - name: ANY_ADVANCED_CONFIG_PROPERTY
              value: any-value
          image: (4)
        initContainers: (5)
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.

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 apply to these fields.

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 CR.

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 SonataFlowClusterPlatform CR
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowClusterPlatform
metadata:
  name: cluster-platform
spec:
  platformRef:
    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.

These cluster-wide services can be overridden in any namespace, by configuring that namespace’s SonataFlowPlatform.spec.services.

Conclusions

The SonataFlow Operator extends its scope to manage the lifecycle of the Data Index and 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

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!