Building and Deploying Serverless Workflows

GitHub Actions · jmagak · commit dc98a9a2969c · 2025-09-30T01:06:30.000+02:00
diff --git a/assemblies/assembly-building-and-deploying-serverless-workflows.adoc b/assemblies/assembly-building-and-deploying-serverless-workflows.adoc
@@ -0,0 +1,37 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="assembly-building-and-deploying-serverless-workflows"]
+endif::[]
+ifdef::context[]
+[id="assembly-building-and-deploying-serverless-workflows"]
+endif::[]
+:context: orchestrator-rhdh
+= Building and deploying serverless workflows
+
+The Orchestrator provides a way to run workflows directly from {product-custom-resource-type} and {product}. This guide takes you through the lifecycle of running a workflow locally on your machine to having it deployed on a cluster and available in the Orchestrator plugin.
+
+The overall process involves the following main steps, which can often be accomplished from a single script:
+
+* Building workflow images
+* Generating workflow manifests
+* Deploying workflows to a cluster
+
+// why build workflow images
+include::modules/orchestrator/con-why-build-workflow-images.adoc[leveloffset=+1]
+
+// project structure
+include::modules/orchestrator/con-project-structure-overview.adoc[leveloffset=+1]
+
+// building locally and generating artifacts
+include::modules/orchestrator/proc-building-locally.adoc[leveloffset=+1]
+
+include::modules/orchestrator/con-build-sh-script-and-its-uses.adoc[leveloffset=+1]
+
+include::modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffset=+1]
+
+include::modules/orchestrator/con-generated-workflow-manifests.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]
diff --git a/modules/orchestrator/con-build-sh-script-and-its-uses.adoc b/modules/orchestrator/con-build-sh-script-and-its-uses.adoc
@@ -0,0 +1,34 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-build-sh-script-and-its-uses.adoc_{context}"]
+= Uses of the `build-sh` script and important flags
+
+The script does the following in the order provided here:
+
+* Generates workflow manifests using the `kn-workflow` CLI.
+* Builds the workflow image using `podman` or `docker`.
+* Optional: The script pushes the images to an image registry and deploys the workflow using `kubectl`.
+
+You can check the help menu of the script as shown in the following example:
+
+.Script usage
+[source,bash]
+----
+./scripts/build.sh [flags]
+----
+
+The following flags are essential for running the script:
+
+[cols="1,3", options="header"]
+|===
+|Flag |Description
+|-i, --image (required) |Full image path, e.g. quay.io/orchestrator/demo:latest
+|-w, --workflow-directory |Workflow source directory (default: current directory)
+|-m, --manifests-directory |Where to save generated manifests
+|--push |Push the image to the registry
+|--deploy |Deploy the workflow
+|-h, --help |Show help message
+|===
+
+[TIP]
+The script also supports builder and runtime image overrides, namespace targeting, and persistence flags.
diff --git a/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc b/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc
@@ -0,0 +1,40 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="con-environment-variables-supported-by-the-build-script.adoc_{context}"]
+= Environment variables supported by the build script and required tools
+
+The `build-sh` script supports the following environment variables to customize the workflow build process without modifying the script itself.
+
+* `QUARKUS_EXTENSIONS`
+
+The `QUARKUS_EXTENSIONS` variable specifies additional Quarkus extensions required by the workflow.
+
+This variable takes the format of a comma-separated list of fully qualified extension IDs as shown in the following example:
++
+[source,yaml]
+----
+export QUARKUS_EXTENSIONS="io.quarkus:quarkus-smallrye-reactive-messaging-kafka"
+----
++
+Add Kafka messaging support or other integrations at build time.
+
+* `MAVEN_ARGS_APPEND`
+
+The `MAVEN_ARGS_APPEND` variable appends additional arguments to the Maven build command.
+This variable takes the format of the string of Maven CLI arguments as shown in the following example:
++
+[source,yaml]
+----
+export MAVEN_ARGS_APPEND="-DmaxYamlCodePoints=35000000"
+----
+
+.Required tools
+[cols="1,3", options="header"]
+|===
+|Tool |Conceptual Purpose
+|podman or docker |Container runtime required for building the workflow images.
+|kubectl |Kubernetes CLI
+|yq JSON |processor
+|curl, git, find, |which Shell utilities
+|kn-workflow |CLI for generating workflow manifests
+|===
diff --git a/modules/orchestrator/con-generated-workflow-manifests.adoc b/modules/orchestrator/con-generated-workflow-manifests.adoc
@@ -0,0 +1,71 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="con-generated-workflow-manifests.adoc_{context}"]
+= Generated workflow manifests
+
+The following example is an illustration of what is generated under the `01_basic/manifests`:
++
+[source,yaml]
+----
+01_basic/manifests
+├── 00-secret_basic-secrets.yaml
+├── 01-configmap_basic-props.yaml
+├── 02-configmap_01-basic-resources-schemas.yaml
+└── 03-sonataflow_basic.yaml
+----
+
+Here is a quick overview of each of these manifests:
+
+`00-secret_basic-secrets.yaml`::
+Contains secrets from `01_basic/src/main/resources/secret.properties`.
+Values are not required at this stage as you can set them later (after applying CRs or when using GitOps).
+
+[Important]
+====
+In OpenShift Serverless Logic `v1.35`, after updating a secret, you must manually restart the workflow Pod for changes to apply.
+====
+
+`01-configmap_basic-props.yaml`::
+Holds application properties from application.properties.
+Any change to this ConfigMap triggers an automatic Pod restart.
+
+`02-configmap_01-basic-resources-schemas.yaml`::
+Contains JSON schemas from src/main/resources/schemas.
+Note: When using the GitOps profile, this ConfigMap (and similar ones like specs) does not need to be deployed.
+
+`03-sonataflow_basic.yaml`::
+The SonataFlow custom resource (CR) that defines the workflow.
+A few important parts:
+
+.The image and secrets mounting example:
+[source,yaml]
+----
+podTemplate:
+  container:
+    image: quay.io/orchestrator/demo-basic
+    resources: {}
+    envFrom:
+      - secretRef:
+          name: basic-secrets
+----
+
+.The persistence configuration example:
+[source,yaml]
+----
+persistence:
+  postgresql:
+    secretRef:
+      name: sonataflow-psql-postgresql
+      userKey: postgres-username
+      passwordKey: postgres-password
+    serviceRef:
+      name: sonataflow-psql-postgresql
+      port: 5432
+      databaseName: sonataflow
+      databaseSchema: basic
+----
+
+If you need to connect to an external database, you must replace `serviceRef` with a `jdbcUrl`. See link:https://sonataflow.org/serverlessworkflow/latest/cloud/operator/enabling-jobs-service.html#_using_the_persistence_field_defined_in_the_sonataflowplatform_cr[SonataFlow Guides] for more information.
+here.
+
+By default, all the manifests are generated without a namespace. You can specify a namespace to the script by the `--namespace` flag if you know the target namespace in advance. Otherwise, the namespace needs to be provided when applying the manifests to the cluster. See link:https://sonataflow.org/serverlessworkflow/latest/cloud/operator/configuring-workflows.html[Configuring Workflow Services].
diff --git a/modules/orchestrator/con-project-structure-overview.adoc b/modules/orchestrator/con-project-structure-overview.adoc
@@ -0,0 +1,32 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-project-structure-overview.adoc_{context}"]
+= Project structure overview
+
+We focus on a *Quarkus project layout* (Maven project structure), specifically the following `01_basic` workflow example:
+
+[source, yaml]
+----
+01_basic
+├── pom.xml
+├── README.md
+└── src
+    └── main
+        ├── docker
+        │   ├── Dockerfile.jvm
+        │   ├── Dockerfile.legacy-jar
+        │   ├── Dockerfile.native
+        │   └── Dockerfile.native-micro
+        └── resources
+            ├── application.properties
+            ├── basic.svg
+            ├── basic.sw.yaml
+            ├── schemas
+            │   ├── basic__main-schema.json
+            │   └── workflow-output-schema.json
+            └── secret.properties
+----
+
+The main workflow resources are located under the `src/main/resources/` directory.
+
+The structure of this project was generated using the `kn-workflow CLI`. For more information on the Quarkus project, see link:https://quarkus.io/guides/getting-started[Creating your first application].
diff --git a/modules/orchestrator/con-why-build-workflow-images.adoc b/modules/orchestrator/con-why-build-workflow-images.adoc
@@ -0,0 +1,10 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-why-build-workflow-images.adoc_{context}"]
+= Why build workflow images?
+
+While the OpenShift Serverless Logic Operator supports building workflows on the fly, this approach is primarily for experimentation. For production deployments, building images is preferred method due to the following reasons:
+
+* Production readiness: Prebuilt images can be scanned, secured, and tested before going live.
+* GitOps compatibility: The Orchestrator relies on a central OpenShift Serverless Logic Operator instance to track workflows and their state. To use this tracking service, you must deploy workflows with the `gitops` profile, which expects a prebuilt image.
+* Testing & quality: Building an image gives you more control over the testing process.
diff --git a/modules/orchestrator/proc-building-locally.adoc b/modules/orchestrator/proc-building-locally.adoc
@@ -0,0 +1,38 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-building-locally.adoc_{context}"]
+= Building workflow images locally
+
+You can use the build script (`build.sh`) to build workflow images. You can run it either locally or inside a container. This section highlights how build workflow images locally.
+
+.Prerequisites
+
+* You have cloned the project as shown in the following example:
+
+[source, yaml]
+----
+git clone git@github.com:rhdhorchestrator/orchestrator-demo.git
+cd orchestrator-demo
+----
+
+.Procedure
+
+. You have cloned the project.
+
+. Check the help menu of the script:
+[source,yaml]
+----
+./scripts/build.sh --help
+----
+
+. Execute the `build.sh` script, providing the required flags: image path (-i), workflow source directory (-w), and manifests output directory (-m).
+
+[IMPORTANT]
+====
+You must specify the full target image path with a tag as shown in the following example:
+
+[source,yaml]
+----
+./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests
+----
+====
diff --git a/modules/orchestrator/proc-building-the-01-basic-workflow.adoc b/modules/orchestrator/proc-building-the-01-basic-workflow.adoc
@@ -0,0 +1,27 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-building-the-01-basic-workflow.adoc_{context}"]
+= Building the `01_basic` workflow
+
+To run the script from the root directory of the repository, use the `-w` flag to point to the workflow directory, and specify the output directory with `-m`.
+
+.Prerequisites
+
+* You have specified the target image using a tag.
+
+.Procedure
+
+. Run the following command:
++
+[source,bash]
+----
+./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests
+----
+
+This build command produces the following two artifacts:
+
+* A workflow image and Kubernetes manifests: `quay.io/orchestrator/demo-basic:test` and tagged as `latest`.
+* Kubernetes manifests under: `01_basic/manifests/`
+
+. Optional: You can add the `--push` flag to automatically push the image after building. Otherwise, pushing manually is mandatory before deploying.
+
diff --git a/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc b/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc
@@ -0,0 +1,13 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-deploying-workflows-on-a-cluster.adoc_{context}"]
+= Deploying workflows on a cluster
+
+.Prerequisites
+
+* You have an OpenShift Container Platform (OCP) cluster with the following versions of components installed:
+
+*   {product} ({product-very-short}) v1.5
+*   Orchestrator plugins v1.4 or v1.5
+*   OpenShift Serverless v1.35
+*   OpenShift Serverless Logic v1.35
diff --git a/titles/orchestrator/master.adoc b/titles/orchestrator/master.adoc
@@ -8,4 +8,6 @@ include::artifacts/attributes.adoc[]
 
 include::assemblies/assembly-orchestrator-rhdh.adoc[leveloffset=+1]
 
-include::assemblies/assembly-install-rhdh-orchestrator.adoc[leveloffset=+1]
+include::assemblies/assembly-install-rhdh-orchestrator.adoc[leveloffset=+1]
+
+include::assemblies/assembly-building-and-deploying-serverless-workflows.adoc[leveloffset=+1]
