Customize the PodSpec Definition

This document describes how to customize the pod specification definition in thew 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.

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`	prod
workflow-properties	`ConfigMap`	`${PROJECT_ROOT}/src/main/resources/application.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.

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 production

When deploying in production, 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 poorly 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.