Chapter 5. Supporting services

You can use the following GraphQL query to retrieve workflow instance details, including node-level data such as input and output arguments.

{
  ProcessInstances {
    id
    processId
    state
    parentProcessInstanceId
    rootProcessId
    rootProcessInstanceId
    variables
    nodes {
      id
      name
      type
      inputArgs
      outputArgs
    }
  }
}

The inputArgs and outputArgs fields provide additional details about the data passed to and produced by each workflow node. These fields help you understand how data flows between nodes during workflow execution.

You can retrieve data from a specific job instance by using the following query example:

{
  Jobs {
    id
    status
    priority
    processId
    processInstanceId
    executionCounter
  }
}

You can filter query results by using the where parameter, allowing multiple combinations based on workflow attributes.

The following example displays a query to filter by state:

{
  ProcessInstances(where: {state: {equal: ACTIVE}}) {
    id
    processId
    processName
    start
    state
    variables
  }
}

The following example displays a query to filter by ID:

{
  ProcessInstances(where: {id: {equal: "d43a56b6-fb11-4066-b689-d70386b9a375"}}) {
    id
    processId
    processName
    start
    state
    variables
  }
}​

By default, filters are combined using the AND Operator. You can change this behavior by combining filters with the AND or OR Operators.

The following example displays a query to combine filters with the OR Operator:

{
  ProcessInstances(where: {or: {state: {equal: ACTIVE}, rootProcessId: {isNull: false}}}) {
    id
    processId
    processName
    start
    end
    state
  }
}

The following example displays a query to combine filters with the AND and OR Operators:

{
  ProcessInstances(where: {and: {processId: {equal: "travels"}, or: {state: {equal: ACTIVE}, rootProcessId: {isNull: false}}}}) {
    id
    processId
    processName
    start
    end
    state
  }
}

Depending on the attribute type, you can use the following available Operators:

You can sort query results based on workflow attributes by using the orderBy parameter. You can also specify the sorting direction in an ascending (ASC) or a descending (DESC) order. Multiple attributes are applied in the order you specified.

The following example displays a query to sort by the start time in an ASC order:

{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}) {
    id
    processId
    processName
    start
    end
    state
  }
}

You can control the number of returned results and specify an offset by using the pagination parameter.

The following example displays a query to limit results to 10, starting from offset 0:

{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}, pagination: {limit: 10, offset: 0}) {
    id
    processId
    processName
    start
    end
    state
  }
}

The ephemeral persistence uses an embedded PostgreSQL database that is dedicated to each service. The OpenShift Serverless Logic Operator 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:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  services:
    dataIndex:
      enabled: true
      # Specific configurations for the Data Index Service
      # might be included here
    jobService:
      enabled: true
      # Specific configurations for the Job Service
      # might be included here

Database migration refers to either initializing a given Data Index or Jobs Service database to its respective schema, or applying data or schema updates when new versions are released. You must configure the database migration strategy individually for each supporting service by using the dataIndex.persistence.dbMigrationStrategy and jobService.persistence.dbMigrationStrategy optional fields. If you do not configure a migration strategy, the system uses service as the default value.

You can configure any of the following database migration strategies:

For PostgreSQL persistence, you must set up a PostgreSQL server instance on your cluster. The administration of this instance remains independent of the OpenShift Serverless Logic Operator control. To connect a supporting service with the PostgreSQL server, you must configure the appropriate database connection parameters.

You can configure PostgreSQL persistence in the SonataFlowPlatform CR by using the following example:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  services:
    dataIndex:
      enabled: true
      persistence:
        dbMigrationStrategy: job 

        postgresql:
          serviceRef:
            name: postgres-example 

            namespace: postgres-example-namespace 

            databaseName: example-database 

            databaseSchema: data-index-schema 

            port: 1234 

          secretRef:
            name: postgres-secrets-example 

            userKey: POSTGRESQL_USER 

            passwordKey: POSTGRESQL_PASSWORD 

    jobService:
      enabled: true
      persistence:
        dbMigrationStrategy: job
        postgresql:
        # Specific database configuration for the Job Service
        # might be included here.

Create the secrets to access PostgreSQL by running the following command:

$ oc create secret generic <postgresql_secret_name> \
  --from-literal=POSTGRESQL_USER=<user> \
  --from-literal=POSTGRESQL_PASSWORD=<password> \
  -n <namespace>

The OpenShift Serverless Logic Operator automatically connects supporting services to the common PostgreSQL server configured in the spec.persistence field.

For rules, the following precedence is applicable:

You can configure a common PostgreSQL service and database for all supporting services by using the spec.persistence.postgresql field in the SonataFlowPlatform Custom Resource (CR). When this field is configured, the OpenShift Serverless Logic Operator connects the supporting services to the specified database. Any workflows deployed in the same namespace using the preview or gitops profiles, and that do not specify a custom persistence configuration, will also connect to this database.

The following rules apply when configuring platform-scoped persistence:

The following SonataFlowPlatform CR fragment shows how to configure platform-scoped PostgreSQL persistence:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  persistence:
    postgresql:
      serviceRef:
        name: postgres-example 

        namespace: postgres-example-namespace 

        databaseName: example-database 

        port: 1234 

      secretRef:
        name: postgres-secrets-example 

        userKey: POSTGRESQL_USER 

        passwordKey: POSTGRESQL_PASSWORD 

    dataIndex:
      enabled: true
      persistence:
        dbMigrationStrategy: job 

    jobService:
      enabled: true
      persistence:
        dbMigrationStrategy: service 

To configure a platform-scoped eventing system, you can use the spec.eventing.broker.ref field in the SonataFlowPlatform CR to reference a Knative Eventing Broker. This configuration instructs the OpenShift Serverless Logic Operator to automatically link the supporting services to produce and consume events by using the specified broker.

A workflow deployed in the same namespace with the preview or gitops profile and without a custom eventing system configuration, automatically links to a specified broker.

The following example displays how to configure the SonataFlowPlatform CR for a platform-scoped eventing system:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  eventing:
    broker:
      ref:
        name: example-broker 

        namespace: example-broker-namespace 

        apiVersion: eventing.knative.dev/v1
        kind: Broker

A service-scoped eventing system configuration allows for fine-grained control over the eventing system, specifically for the Data Index or the Job Service.

To configure a service-scoped eventing system for the Data Index, you must use the spec.services.dataIndex.source.ref field in the SonataFlowPlatform CR to refer to a specific Knative Eventing Broker. This configuration instructs the OpenShift Serverless Logic Operator to automatically link the Data Index to consume SonataFlow system events from that Broker.

The following example displays the Data Index eventing system configuration:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
spec:
  services:
    dataIndex:
      source:
        ref:
          name: data-index-source-example-broker 

          namespace: data-index-source-example-broker-namespace 

          apiVersion: eventing.knative.dev/v1
          kind: Broker

To configure a service-scoped eventing system for the Job Service, you must use the spec.services.jobService.source.ref and spec.services.jobService.sink.ref fields in the SonataFlowPlatform CR. These fields instruct the OpenShift Serverless Logic Operator to automatically link the Job Service to consume and produce SonataFlow system events, based on the provided configuration.

The following example displays the Job Service eventing system configuration:

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
spec:
  services:
    jobService:
      source:
        ref:
          name: jobs-service-source-example-broker 

          namespace: jobs-service-source-example-broker-namespace 

          apiVersion: eventing.knative.dev/v1
          kind: Broker
      sink:
        ref:
          name: jobs-service-sink-example-broker 

          namespace: jobs-service-sink-example-broker-namespace 

          apiVersion: eventing.knative.dev/v1
          kind: Broker

When you deploy cluster-scoped supporting services, the supporting services automatically link to the Broker specified in the SonataFlowPlatform CR, which is referenced by the SonataFlowClusterPlatform CR.

The OpenShift Serverless Logic Operator follows a defined order of precedence to configure the eventing system for a supporting service.

Eventing system configuration precedence rules are as follows:

The OpenShift Serverless Logic Operator automatically creates Knative Eventing, SinkBindings, and triggers to link supporting services with the eventing system. These objects enable the production and consumption of events by the supporting services.

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

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  eventing:
    broker:
      ref:
        name: example-broker 

        apiVersion: eventing.knative.dev/v1
        kind: Broker
  services:
    dataIndex: 

      enabled: true
    jobService: 

      enabled: true

The following example displays how to configure a Knative Kafka Broker for use with the SonataFlowPlatform CR:

apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  annotations:
    eventing.knative.dev/broker.class: Kafka 

  name: example-broker
  namespace: example-namespace
spec:
  config:
    apiVersion: v1
    kind: ConfigMap
    name: kafka-broker-config
    namespace: knative-eventing

The following command displays the list of triggers set up for the Data Index and Job Service events, showing which services are subscribed to the events:

$ oc get triggers -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-instance-mul35f055c67a626f51bb8d2752606a6b54   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-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    -

To see the SinkBinding resource for the Job Service, use the following command:

$ oc get sources -n example-namespace

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

By using a HorizontalPodAutoscaler (HPA), you can configure how a Kubernetes workload resource scales based on a set of metrics, such as CPU or memory usage.

You can configure horizontal pod autoscaling for the Data Index service to automatically scale based on resource utilization. The Job Service does not support autoscaling because it operates as a singleton service.

resources:
  limits:
    cpu: 200m
    memory: 1Gi
  requests:
    cpu: 100m
    memory: 1Gi

By using a PodDisruptionBudget (PDB), you can configure the required availability of a Kubernetes Deployment during a voluntary disruption, such as a node drain, in the cluster. This also applies to the Data Index service Deployment.

A PDB limits the number of pods that can be unavailable simultaneously during such disruptions, ensuring that the Data Index maintains the desired level of availability.

In general, any tool that needs to guarantee availability should respect the PDB by using the Kubernetes Eviction API instead of directly deleting pods or deployments. The Eviction API ensures that disruption constraints defined by the PDB are honored.

The OpenShift Serverless Logic Operator can automatically generate a PDB for the Data Index based on the SonataFlowPlatform custom resource (CR) configuration.

To configure a PDB for the Data Index, use the spec.services.dataIndex.podTemplate.podDisruptionBudget field in your SonataFlowPlatform CR. The following fields are available:

# ...
spec:
  services:
    dataIndex:
      podTemplate:
        podDisruptionBudget:
          minAvailable: 2
          maxUnavailable: 1
# ...

This configuration includes the following fields:

The OpenShift Serverless Logic Operator applies the following generation rules for the PDB:

Given this configuration, the OpenShift Serverless Logic Operator generates the following PDB for the Data Index:

kind: PodDisruptionBudget
apiVersion: policy/v1
metadata:
  name: sonataflow-platform-example-data-index-service
  namespace: example-namespace
  ownerReferences:
    - apiVersion: sonataflow.org/v1alpha08
      kind: SonataFlowPlatform
      name: sonataflow-platform-example
      uid: 5e94401d-e645-47f6-abd0-5261b471a9d7
      controller: true
      blockOwnerDeletion: true
spec:
  minAvailable: 1
  selector:
    matchLabels:
      sonataflow.org/service: sonataflow-platform-example-data-index-service

This generated PDB has the following characteristics: