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.

Serverless Logic 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
About Serverless Logic Operator Profiles

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 Serverless Logic 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 Serverless Logic 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 registry.redhat.io/openshift-serverless-1-tech-preview/logic-swf-devmode-rhel8:1.32.0.

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 poorly management and configuration. The Serverless Logic 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.