Customize the PodSpec Definition

This document describes how to customize the pod specification definition in the SonataFlow custom resource.

Sometimes you may have a specific requirement to deploy containers on Kubernetes or OpenShift such as setting Resource Limits.

SonataFlow Operator enables custom PodSpec definitions when deploying a SonataFlow instance by setting the .spec.podTemplate attribute. For example:

Setting PodSpec Resources Limits example

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: simple
  annotations:
    sonataflow.org/description: Simple example on k8s!
    sonataflow.org/version: 0.0.1
spec:
  podTemplate: (1)
    container: (2)
      resources: (3)
        limits:
          cpu: "250m"
          memory: "128Mi"
  flow:
    start: HelloWorld
    states:
      - name: HelloWorld
        type: inject
        data:
          message: Hello World
        end: true

1	The `PodSpec` template definition
2	The default workflow service container
3	Resources configuration

The .spec.podTemplate attribute has the majority of fields defined in the default Kubernetes PodSpec API. The same Kubernetes API validation rules applies to these fields.

The .spec.podTemplate.container is a special attribute that you won’t find in the default Kubernetes API. The reason is to avoid misconfiguration when users require to change the specific container where the workflow application is deployed.

Deployment Model

By default, the SonataFlow Operator deploys a SonataFlow instance in a regular Kubernetes Deployment object. Although it’s possible to change this behavior and deploy the workflow instance as a Knative Serving Service instead.

To change the deployment to Knative, set the .spec.podTemplate.deploymentModel attribute to knative. For example:

Setting PodSpec Resources Limits example

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: simple
  annotations:
    sonataflow.org/description: Simple example on k8s!
    sonataflow.org/version: 0.0.1
    sonataflow.org/version: preview
spec:
  podTemplate:
    deploymentModel: knative (1)
  flow:
    start: HelloWorld
    states:
      - name: HelloWorld
        type: inject
        data:
          message: Hello World
        end: true

1	The `deploymentModel` attribute

After changing the deployment model to knative, the SonataFlow instance will be deployed as a Knative Serving Service.

It’s not possible to deploy a SonataFlow instance as a Knative Service in dev profile. In this profile, this attribute is ignored by the operator.

Note that not every use case leverage a Knative deployment. Long-running workflow instances, for example, that calls services that might take too long to respond, might not be an ideal deployment model. Opt to use Knative deployments for workflows that won’t take too long to run.

The exception are workflows that have callback states. In this case, you must configure persistence. This is required because once the workflow waits for the event to resume the execution, Knative will kill the pod. Since the workflow has persistence, it will resume the execution once it receives the callback event.

Knative does not support initContainers by default. If your workflow requires it, you must first enable the extension in the Knative installation. See more information on the Knative documentation.

Customization Exceptions

Besides customizing the default container, you can add more containers, initContainers, or volumes to the pod. There are a few exceptions listed below:

The containers array can’t have a container named workflow. If you set a container with this name, it will be ignored by the operator. Instead, use .spec.podTemplate.container to modify the workflow container.

There are a few file system paths controlled by the operator within the container where it mounts important files. These volumes can’t be overrided, it will be ignored by the operatror. See the table below:

Table 1. List of immutable volumes
Volume	Type	Path	Profile
workflow-properties	`ConfigMap`	`/deployments/config/application.properties`, `/deployments/config/application-prod.properties`	preview
workflow-properties	`ConfigMap`	`${PROJECT_ROOT}/src/main/resources/application.properties`, `${PROJECT_ROOT}/src/main/resources/application-dev.properties`	dev
resources	`Projected`	`${PROJECT_ROOT}/src/main/resources/`	dev

In dev profile, all the SonataFlow .spec.resources objects are mounted in the resources projected volume listed in this table. Do not mount anything else in this path.

About SonataFlow Operator Profiles

Profiles are a way to change the runtime and deployment behavior of workflows. You can change the SonataFlow custom resource profile using annotations. For example:

Example of a SonataFlow CR with a profile annotation

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: simple
  annotations:
    sonataflow.org/profile: preview (1)
    sonataflow.org/version: 0.0.1
spec:
  flow:
    start: HelloWorld
    states:
      - name: HelloWorld
        type: inject
        data:
          message: Hello World
        end: true

1	Preview profile defined in the `sonataflow.org/profile` annotation. This is the default profile.

The SonataFlow Operator supports three different profiles:

dev: The workflow will be deployed as a mutable container that will react upon any changes on the SonataFlow custom resource immediatelly. Ideal for scenarios where the flow definition is under active development and testing in the cluster context. See Developing Workflows with the Operator.
preview: The operator will rely on an internal build system to build an immutable container based on the flow definition. Every change to the SonataFlow will kick a new build. Use this profile to evaluate the workflow behavior in the cluster or if you have a simple use case where you don’t need any complex build customizations. See Building and Deploying Workflows with the Operator
gitops: Ideal for production use cases. This profile is automatically defined by the operator when the SonataFlow CR is deployed with a custom .spec.podTemplate.container.image. In this scenario, the user is responsible to build the workflow application and provide the image to the operator.

There’s a correlation on the operator profile and the internal runtime workflow Quarkus application. See the table below.

Table 2. Correlation of the operator and Quarkus profiles
Operator Profile	Quarkus Profile	Description
dev	dev	Suitable for testing only. The configuration file managed by the operator is `application-dev.properties`
preview	prod	Suitable for quick evaluation and use of the internal builder system. The configuration file managed by the operator is `application-prod.properties`
gitops	prod	Workflow image externally built by another system. The configuration file managed by the operator is `application-prod.properties`

For more information about configuring workflows see Configuring Workflow Services.

Setting a custom image in the default container

When setting the attribute .spec.podTemplate.container.image the operator understands that the workflow already have an image built and the user is responsible for the build and image maintainence. That means that the operator won’t try to upgrade this image in the future or do any reconciliation changes to it.

Setting a custom image in devmode

In development profile, it’s expected that the image is based on the default quay.io/kiegroup/kogito-swf-devmode:latest.

Setting a custom image in preview

When building workflows, you can opt in to have the operator to handle the build process for you. However, in more complex scenarios it’s expected that the user owns and controls the build process. For this reason, when overriding the image the operator won’t build the workflow. The operator will try to deploy the workflow using the given image.

In this scenario, the .spec.resources attribute is ignored since it’s only used during the build process in the production profile.

In the roadmap you will find that we plan to consider the .spec.resources attribute when the image is specified in the default container.

It’s advised that the SonataFlow .spec.flow definition and the workflow built within the image corresponds to the same workflow. If these definitions don’t match you may experience poor management and configuration. The SonataFlow Operator uses the .spec.flow attribute to configure the application, service discovery, and service binding with other deployments within the topology.

It’s on the roadmap to add integrity check to the built images provided to the operator by customizing the default container.

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!