Customize the PodSpec Definition

This document describes how to customize the pod specification (PodSpec) in a SonataFlow custom resource to meet runtime requirements in Kubernetes and OpenShift, such as adding volumes, setting resource limits, or using a custom container image.

If you’re looking to understand how the operator builds and manages workflow lifecycles (e.g., live updates or immutable builds), refer to Deployment Profiles.

Overview

The .spec.podTemplate attribute allows you to define a custom PodSpec for the deployed workflow instance. This enables fine-grained control over how the workflow runs inside the container.

Use .spec.podTemplate.container to customize the default workflow container (named workflow). This field is not part of the standard PodSpec, but was introduced by the operator to simplify configuration.

Example: Setting Resource Limits

spec:
  podTemplate:
    container:
      resources:
        limits:
          cpu: "250m"
          memory: "128Mi"

Customizing the Workflow Container

You can customize the workflow container via .spec.podTemplate.container with fields like:

  • resources

  • image

  • env

  • command and args

Avoid using the main containers array to redefine the workflow container — the operator will ignore conflicting names.

Adding Additional Containers and Volumes

You may add:

  • containers (sidecars)

  • initContainers

  • volumes

  • volumeMounts (on sidecars or initContainers)

You cannot override volumes or mount paths controlled by the operator. See Customization Exceptions.

Deployment Model

By default, the SonataFlow Operator deploys workflow instances using a standard Kubernetes Deployment. You can opt into using a serverless model via Knative Serving.

To enable Knative deployment:

spec:
  podTemplate:
    deploymentModel: knative (1)
1 Valid values: kubernetes (default), knative

After enabling this option, the workflow will be deployed as a Knative Service.

The deploymentModel: knative is only honored in the preview and gitops profiles. It is ignored when using the dev profile.

Use Knative when: - You need scale-to-zero or autoscaling based on HTTP traffic. - The workflow is short-lived or event-driven. - You have persistence enabled for workflows with callbacks or long waits.

See: - Deployment Profiles - Using persistence in SonataFlow workflows - Knative InitContainer support

Customization Exceptions

Some paths and volumes are managed by the operator and must not be overridden:

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, application-dev.properties

dev

resources

Projected

${PROJECT_ROOT}/src/main/resources/

dev

In the dev profile, all .spec.resources are mounted in the resources projected volume. Avoid mounting anything else at that path.

Using a Custom Image

You may override the workflow container image using:

spec:
  podTemplate:
    container:
      image: quay.io/myorg/myworkflow:latest

When this is set, the operator assumes you’re using the gitops deployment profile and won’t attempt to build or update the image automatically.

For more information, see cloud/operator/deployment-profile.adoc#custom-image-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!