This is an automated email from the ASF dual-hosted git repository.
dhanak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 6643c58f0 kie-kogito-docs-746: Document the nativelly HPA support for
SonataFlow workflows and Data Index service deployments (#747)
6643c58f0 is described below
commit 6643c58f0a90e296774f75b5f6fa3a8c6e202c9b
Author: Walter Medvedeo <[email protected]>
AuthorDate: Wed Feb 25 10:26:57 2026 +0100
kie-kogito-docs-746: Document the nativelly HPA support for SonataFlow
workflows and Data Index service deployments (#747)
---
serverlessworkflow/modules/ROOT/nav.adoc | 3 +-
...onfiguring-workflow-scaling-and-disruption.adoc | 228 +++++++++++++++++++++
.../pages/cloud/operator/customize-podspec.adoc | 2 +-
.../pages/cloud/operator/supporting-services.adoc | 90 +++++++-
4 files changed, 319 insertions(+), 4 deletions(-)
diff --git a/serverlessworkflow/modules/ROOT/nav.adoc
b/serverlessworkflow/modules/ROOT/nav.adoc
index 8325af0e1..5821de379 100644
--- a/serverlessworkflow/modules/ROOT/nav.adoc
+++ b/serverlessworkflow/modules/ROOT/nav.adoc
@@ -61,10 +61,11 @@
**** xref:cloud/operator/customize-podspec.adoc[Custom Workflow PodSpec]
**** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to
Workflow Pod]
**** xref:cloud/operator/workflow-status-conditions.adoc[Custom Resource
Status]
-*** xref:cloud/operator/supporting-services.adoc[Deploy Supporting Services]
+*** xref:cloud/operator/supporting-services.adoc[Supporting Services
Deployment]
*** xref:cloud/operator/service-discovery.adoc[Service Discovery]
*** xref:cloud/operator/using-persistence.adoc[Workflow Persistence]
*** xref:cloud/operator/configuring-workflow-eventing-system.adoc[Workflow
Eventing System]
+***
xref:cloud/operator/configuring-workflow-scaling-and-disruption.adoc[Workflow
Scaling and Disruption Protection]
*** Monitoring
**** xref:cloud/operator/monitoring-workflows.adoc[Workflow Monitoring]
**** xref:cloud/operator/sonataflow-metrics.adoc[Prometheus Metrics for
Workflows]
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-workflow-scaling-and-disruption.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-workflow-scaling-and-disruption.adoc
new file mode 100644
index 000000000..af81fc9bc
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-workflow-scaling-and-disruption.adoc
@@ -0,0 +1,228 @@
+= Workflow Scaling and Disruption Protection
+
+:compat-mode!:
+// Metadata:
+:description: Workflow scaling and disruption protection
+:keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes,
autoscaling, disruption
+
+This document describes the different alternatives for scaling a workflow and
how to configure horizontal pod autoscaling and pod disruption budgets.
+
+[#workflow-scaling]
+== Scaling a Workflow
+
+The `SonataFlow` CRD exposes the Kubernetes `scale` subresource, which enables
users and controllers (such as Horizontal Pod Autoscalers) to scale workflows
using the standard Kubernetes API.
+
+Below you can see different options for scaling an `example-workflow` workflow.
+
+.Example workflow
+[source, yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+ name: example-workflow
+ namespace: example-workflow-namespace
+ annotations:
+ sonataflow.org/description: Example Workflow
+ sonataflow.org/version: 0.0.1
+ sonataflow.org/profile: preview
+spec:
+ flow:
+ # Only a fragment of the workflow is shown for simplicity
+ start: ExampleStartState
+----
+
+[NOTE]
+====
+Workflows deployed with the `dev` profile are intended for development
purposes and are not designed to be scaled.
+====
+
+=== Querying the workflow scale subresource
+
+To query the workflow `scale` subresource you can use the following command:
+
+[source,shell]
+----
+kubectl get --subresource=scale example-workflow -n example-workflow-namespace
-o yaml
+----
+
+You must get an output similar to the following:
+
+[source,terminal]
+----
+apiVersion: autoscaling/v1
+kind: Scale
+metadata:
+ creationTimestamp: "2026-02-12T12:48:46Z"
+ name: example-workflow
+ namespace: example-workflow-namespace
+ resourceVersion: "38397"
+ uid: de53b549-dcb5-4b46-bb4e-9a576341e099
+spec:
+ replicas: 1 <1>
+status:
+ replicas: 1 <2>
+ selector:
app=example-workflow,app.kubernetes.io/component=serverless-workflow,app.kubernetes.io/instance=example-workflow,app.kubernetes.io/managed-by=sonataflow-operator,app.kubernetes.io/name=example-workflow,app.kubernetes.io/version=main,sonataflow.org/workflow-app=example-workflow,sonataflow.org/workflow-namespace=example-workflow-namespace
<3>
+----
+
+<1> Number of configured replicas.
+<2> Number of currently available replicas.
+<3> Selector to query the observed Pods.
+
+=== Scaling the workflow
+
+To scale the workflow you can use any of the following alternatives:
+
+.Example of workflow scaling using the kubectl scale command
+[source, bash]
+----
+kubectl scale workflow example-workflow -n example-workflow-namespace
--replicas=3
+----
+
+You must get an output similar to the following:
+
+[source, terminal]
+----
+sonataflow.sonataflow.org/example-workflow scaled
+----
+
+.Example of workflow scaling by configuring the `SonataFlow` CR
+[source, yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+ name: example-workflow
+ namespace: example-workflow-namespace
+ annotations:
+ sonataflow.org/description: Example Workflow
+ sonataflow.org/version: 0.0.1
+ sonataflow.org/profile: preview
+spec:
+ podTemplate:
+ replicas: 3 <1>
+ flow:
+ # Only a fragment of the workflow is shown for simplicity
+ start: ExampleStartState
+----
+
+<1> Use the field `spec.podTemplate.replicas` to configure the number of
replicas.
+
+[source, bash]
+----
+kubectl apply -f example-workflow.yaml -n example-workflow-namespace
+----
+
+You must get an output similar to the following:
+
+[source, terminal]
+----
+sonataflow.sonataflow.org/example-workflow configured
+----
+
+.Example of workflow scaling by patching the field `spec.podTemplate.replicas`
+[source, bash]
+----
+kubectl patch workflow example-workflow -n example-workflow-namespace \
+ --type merge \
+ -p '{
+ "spec": {
+ "podTemplate": {
+ "replicas": 3
+ }
+ }
+ }'
+----
+
+You must get an output similar to the following:
+
+[source, terminal]
+----
+sonataflow.sonataflow.org/example-workflow patched
+----
+
+
+[#workflow-horizontal-pod-autoscaling]
+== Horizontal Pod Autoscaling configuration
+
+Before configuring a `HorizontalPodAutoscaler` for a workflow, ensure that the
resources you want the scaler to use as metrics are defined in the `SonataFlow`
CR.
+
+The following example shows how to configure such resources:
+
+.Example of resources configuration in the `SonataFlow` CR
+[source, yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+ name: example-workflow
+ namespace: example-workflow-namespace
+ annotations:
+ sonataflow.org/description: Example Workflow
+ sonataflow.org/version: 0.0.1
+ sonataflow.org/profile: preview
+spec:
+ podTemplate:
+ container: <1>
+ resources:
+ requests:
+ cpu: 100m <2>
+ memory: 256Mi <3>
+ limits:
+ cpu: 500m
+ memory: 512Mi
+
+ flow:
+ # Only a fragment of the workflow is shown for simplicity
+ start: ExampleStartState
+----
+
+<1> The field `spec.podTemplate.container` supports most of the standard
`PodSpec` configurations. For more information
xref:cloud/operator/customize-podspec.adoc[see].
+<2> Example of `cpu` request resource configuration.
+<3> Example of `memory` request resource configuration.
+
+[NOTE]
+====
+`HorizontalPodAutoscalers` use the request resources for the metrics
calculations. The resource limits in the example are only illustrative and are
not used for scaling.
+====
+
+The following example shows how to configure a `HorizontalPodAutoscaler`:
+
+.Example of `HorizontalPodAutoscaler` configuration
+[source, yaml]
+----
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+ name: example-autoscaler
+spec:
+ scaleTargetRef: <1>
+ apiVersion: sonataflow.org/v1alpha08
+ kind: SonataFlow
+ name: example-workflow
+ minReplicas: 3
+ maxReplicas: 10
+ metrics:
+ - type: Resource
+ resource:
+ name: cpu <2>
+ target:
+ type: Utilization
+ averageUtilization: 70
+----
+<1> Refer the target workflow by configuring the `apiVersion`, `kind` and
`name`.
+<2> Example of a metric based on the cpu resource utilization.
+
+[IMPORTANT]
+====
+Workflows deployed with `spec.podTemplate.deploymentModel: knative` cannot be
scaled via a `HorizontalPodAutoscaler`, since Knative Serving controls the
number of replicas automatically.
+====
+
+For more information on configuring `HorizonalPodAutoscalers` you can refer to
the Kubernetes documentation
+
+== Additional resources
+
+* xref:cloud/operator/using-persistence.adoc[Workflow Persistence]
+* xref:cloud/operator/supporting-services.adoc[Deploying Supporting Services]
+
+include::../../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
index a403c774c..00b68cd22 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
@@ -11,7 +11,7 @@
:knative_serving_initcontainer:
https://knative.dev/docs/serving/configuration/feature-flags/#kubernetes-init-containers
:kubernetes_init_containers:
https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
-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.
+This document describes how to customize the pod specification (`PodSpec`) in
a `SonataFlow` CR 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
xref:cloud/operator/deployment-profile.adoc[Deployment Profiles].
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc
index 1260bdf17..285e413ee 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/supporting-services.adoc
@@ -476,6 +476,81 @@ NAME TYPE
RESOURCE
sonataflow-platform-example-jobs-service-sb SinkBinding
sinkbindings.sources.knative.dev broker:example-broker True
----
+== Configuring Scaling and Disruption Protection
+
+=== Configuring Auto Scaling
+
+Currently, only the Data Index supports auto-scaling configuration.
+
+To configure the auto-scaling, you must create an external
`HorizonalPodAutoscaler` that targets the given Data Index service `Deployment`.
+
+When the {operator_name} detects a `HorizontalPodAutoscaler` in the namespace
targeting the Data Index `Deployment`, replica management is delegated to the
HPA controller. If the `HorizontalPodAutoscaler` is removed, the
{operator_name} controller resumes control of replica management.
+
+To calculate the Data Index `Deployment` name, you must follow this rule:
+
+* Concatenate the name of the `SonataFlowPlatform`, with the suffix
`-data-index-service`.
+For the example below, the calculated name is:
`sonataflow-platform-example-data-index-service`.
+
+.SonataFlowPlatform CR example
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+ name: sonataflow-platform-example
+ namespace: example-namespace
+spec:
+ services:
+ dataIndex:
+ enabled: true
+ jobService:
+ enabled: true
+# Only a fragment of the SonataFlowPlatform is shown for simplicity
+----
+
+The following example shows a `HorizontalPodAutoscaler` configuration for the
`sonataflow-platform-example-data-index-service` `Deployment`:
+
+.Example of HorizontalPodAutoscaler configuration that targets a Data Index
`Deployment`
+[source,yaml]
+----
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+ name: data-index-example-autoscaler <1>
+spec:
+ scaleTargetRef:
+ apiVersion: apps/v1
+ kind: Deployment
+ name: sonataflow-platform-example-data-index-service <2>
+ minReplicas: 3
+ maxReplicas: 5
+ metrics:
+ - type: Resource
+ resource:
+ name: cpu <3>
+ target:
+ type: Utilization
+ averageUtilization: 70
+----
+<1> Any name of your choice.
+<2> The calculated name of the Data Index `Deployment`. The other fields of
the `scaleTargetRef` configuration remains un changed.
+<3> Example of a metric based on the cpu resource utilization.
+
+To configure the `HorizontalPodAutoscaler` metrics, you can use any of the
resources automatically configured by the {operator_name}. Alternatively, to
modify the default values <<advanced_supporting_services_configuration,see>>.
+
+.Default values configured by the {operator_name} for the Data Index
`Deployment`
+[source, yaml]
+----
+ - resources:
+ limits:
+ cpu: 200m
+ memory: 1Gi
+ requests:
+ cpu: 100m
+ memory: 1Gi
+----
+
+[#advanced_supporting_services_configuration]
== Advanced Supporting Services Configurations
To configure the advanced options for any of the supporting services you must
use the `podTemplate` field respectively, for example `dataIndex.podTemplate`:
@@ -499,14 +574,25 @@ spec:
- name: ANY_ADVANCED_CONFIG_PROPERTY
value: any-value
image: <4>
- initContainers: <5>
+ resources:
+ limits:
+ cpu: <5>
+ memory: <6>
+ requests:
+ cpu: <7>
+ memory: <8>
+ initContainers: <9>
----
<1> Number of replicas. Defaults to 1. In the case of the jobService this
value is always overridden to 1 by the operator, since that service is a
singleton service.
<2> Holds the particular configurations for the container that will execute
the given supporting service.
<3> Standard Kubernetes `env` configuration. This can be useful in cases where
you need to fine tune any of the supporting services properties.
<4> Standard Kubernetes `image` configuration. This can be useful in cases
where you need to use an updated image for any of the supporting services.
-<5> Standard Kubernetes `initContainers` for the Pod that executes the
supporting service.
+<5> Standard Kubernetes `cpu` limit configuration. Defaults to 200m.
+<6> Standard Kubernetes `memory` limit configuration. Defaults to 1Gi.
+<7> Standard Kubernetes `cpu` request configuration. Defaults to 100m.
+<8> Standard Kubernetes `memory` request configuration. Defaults to 1Gi.
+<9> Standard Kubernetes `initContainers` for the Pod that executes the
supporting service.
[NOTE]
====
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
