Building and Deploying Serverless Workflows

Author: GitHub Actions

assemblies/assembly-building-and-deploying-serverless-workflows.adoc

@@ -7,11 +7,11 @@ ifdef::context[]
 [id="assembly-building-and-deploying-serverless-workflows"]
 endif::[]
 :context: orchestrator-rhdh
-= Building and deploying serverless workflows
+= Build and deploy 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 Orchestrator provides a way to run workflows directly from {product-custom-resource-type} and {product}. This guide details the full workflow lifecycle: moving a workflow from your local machine to deployment on a cluster, where it becomes available in the Orchestrator plugin.
 
-The overall process involves the following main steps, which can often be accomplished from a single script:
+The overall process involves the following main steps, all of which can often be run using a single script:
 
 * Building workflow images
 * Generating workflow manifests
@@ -23,6 +23,9 @@ include::modules/orchestrator/con-why-build-workflow-images.adoc[leveloffset=+1]
 // project structure
 include::modules/orchestrator/con-project-structure-overview.adoc[leveloffset=+2]
 
+// creating and running workflows locally
+include::modules/orchestrator/proc-getting-started.adoc[leveloffset=+1]
+
 // building locally and generating artifacts
 include::modules/orchestrator/proc-building-locally.adoc[leveloffset=+1]
 
@@ -32,6 +35,9 @@ include::modules/orchestrator/con-build-sh-script-and-its-uses.adoc[leveloffset=
 // environment Variables supported by the script
 include::modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc[leveloffset=+2]
 
+// required tools
+include::modules/orchestrator/con-required-tools.adoc[leveloffset=+2]
+
 // building the 01_basic workflow
 include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffset=+2]
 

modules/orchestrator/con-build-sh-script-and-its-uses.adoc

@@ -1,17 +1,16 @@
 :_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 `build-sh` script functionality and important flags
 
-The script does the following in the order provided here:
+The `build-sh` script does the following in order:
 
 * 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:
+By reviewing the script help menu, you can see the available flags and their functions:
 
-.Script usage
 [source,bash]
 ----
 ./scripts/build.sh [flags]
@@ -22,13 +21,15 @@ 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
+|`-i`, `--image` (required) |Full image path, for example, `quay.io/orchestrator/demo:latest`.
+|`-w`, `--workflow-directory` |Workflow source directory (default is the current directory).
+|`-m`, `--manifests-directory` |Where to save generated manifests.
+|`--push` |Push the image to the registry.
+|`--deploy` |Deploy the workflow.
+|`-h`, `--help` |Show the help message.
 |===
 
 [TIP]
-The script also supports builder and runtime image overrides, namespace targeting, and persistence flags.
+====
+The script also supports builder and runtime image overrides, namespace targeting, and persistence flags.
+====

modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc

@@ -1,7 +1,7 @@
-:_mod-docs-content-type: PROCEDURE
+:_mod-docs-content-type: CONCEPT
 
 [id="con-environment-variables-supported-by-the-build-script.adoc_{context}"]
-= Environment variables supported by the build script and required tools
+= Environment variables supported by the build script
 
 The `build-sh` script supports the following environment variables to customize the workflow build process without modifying the script itself.
 
@@ -10,7 +10,7 @@ The `build-sh` script supports the following environment variables to customize
 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"
@@ -22,19 +22,8 @@ Add Kafka messaging support or other integrations at build time.
 
 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
-|===
+----

modules/orchestrator/con-generated-workflow-manifests.adoc

@@ -1,4 +1,4 @@
-:_mod-docs-content-type: PROCEDURE
+:_mod-docs-content-type: CONCEPT
 
 [id="con-generated-workflow-manifests.adoc_{context}"]
 = Generated workflow manifests
@@ -18,7 +18,7 @@ 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).
+Values are not required at this stage as you can set them later after applying CRs or when using GitOps.
 
 [Important]
 ====
@@ -31,7 +31,11 @@ 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.
++
+[NOTE]
+====
+You do not need to deploy certain configuration resources when using the GitOps profile.
+====
 
 `03-sonataflow_basic.yaml`::
 The SonataFlow custom resource (CR) that defines the workflow.
@@ -65,7 +69,6 @@ persistence:
       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.
+If you must connect to an external database, replace `serviceRef` with a `jdbcUrl`. See the 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.
 
-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].
+By default, the script generates all the manifests without a namespace. You can specify a namespace to the script by using the `--namespace` flag if you know the target namespace in advance. Otherwise, you must provide the namespace when applying the manifests to the cluster. See link:https://sonataflow.org/serverlessworkflow/latest/cloud/operator/configuring-workflows.html[Configuring workflow services].

modules/orchestrator/con-project-structure-overview.adoc

@@ -29,4 +29,4 @@ We focus on a *Quarkus project layout* (Maven project structure), specifically t
 
 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].
+The `kn-workflow CLI` generated this project structure. You can try generating the structure yourself by following the _Getting Started guide_. For more information on the Quarkus project, see link:https://quarkus.io/guides/getting-started[Creating your first application].

modules/orchestrator/con-required-tools.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-required-tools.adoc_{context}"]
+= Required tools
+
+To run the `build-sh` script locally and manage the workflow lifecycle, you must install the following command-line tools:
+
+[cols="1,3", options="header"]
+|===
+|Tool |Conceptual Purpose.
+|podman or docker |Container runtime required for building the workflow images.
+|`kubectl` |Kubernetes CLI.
+|`yq` |YAML processor.
+|`jq` |JSON  processor.
+|`curl`, `git`, `find`, `which`| Shell utilities.
+|`kn-workflow` |CLI for generating workflow manifests.
+|===

modules/orchestrator/con-why-build-workflow-images.adoc

@@ -3,7 +3,7 @@
 [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:
+While the OpenShift Serverless Logic Operator supports the building of workflows dynamically, this approach is primarily for experimentation. For production deployments, building images is the 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.

modules/orchestrator/proc-building-locally.adoc

@@ -17,15 +17,15 @@ cd orchestrator-demo
 
 .Procedure
 
-. You have cloned the project.
+. Clone 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).
+. Run the `build.sh` script, providing the required flags, for instance, the image path (`-i`), workflow source directory (`-w`), and manifests output directory (`-m`).
 
 [IMPORTANT]
 ====

modules/orchestrator/proc-building-the-01-basic-workflow.adoc

@@ -3,7 +3,7 @@
 [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`.
+To run the script from the root directory of the repository, you must use the `-w` flag to point to the workflow directory. Additionally, specify the output directory with the `-m` flag.
 
 .Prerequisites
 

modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc

@@ -3,7 +3,7 @@
 [id="proc-deploying-workflows-on-a-cluster.adoc_{context}"]
 = Deploying workflows on a cluster
 
-You can now deploy the workflow on a cluster, since the image has been pushed to the image registry and the deployment manifests are available.
+You can now deploy the workflow on a cluster, since the image has been pushed to the image registry and the deployment manifests have been made available.
 
 .Prerequisites
 
@@ -14,7 +14,7 @@ You can now deploy the workflow on a cluster, since the image has been pushed to
 *   OpenShift Serverless `v1.35`
 *   OpenShift Serverless Logic `v1.35`
 
-For further instructions on installing these components, see {orchestrator-book-link}#con-orchestrator-plugin-components[Orchestrator plugin components on {ocp-short}].
+For further instructions on installing these components, see the {orchestrator-book-link}#con-orchestrator-plugin-components[Orchestrator plugin components on {ocp-short}].
 
 * You must apply the workflow manifests in a namespace that contains a `SonataflowPlatform` custom resource (CR), which manages the link:https://sonataflow.org/serverlessworkflow/latest/cloud/operator/supporting-services.html[supporting services]. By default, OpenShift Serverless Logic services are installed in the `sonataflow-infra` namespace.
 
@@ -55,9 +55,7 @@ Caused by: io.quarkus.runtime.configuration.ConfigurationException: Failed to re
 +
 The error indicates a missing property: `quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token`.
 
-. In such a case where the logs show the `ConfigurationException: Failed to read configuration properties` error or indicate a missing value, complete the following tasks:
-+
-* Retrieve the ConfigMap as shown in the following example:
+. In such a case where the logs show the `ConfigurationException: Failed to read configuration properties` error or indicate a missing value, retrieve the ConfigMap as shown in the following example:
 +
 [source,yaml]
 ----
@@ -71,13 +69,13 @@ The sample output looks as in the following example:
 apiVersion: v1
 data:
   application.properties: |
-    # Backstage Notifications service
+    # Backstage notifications service
     quarkus.rest-client.notifications.url=${BACKSTAGE_NOTIFICATIONS_URL}
     quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token=${NOTIFICATIONS_BEARER_TOKEN}
 ...
 ----
 +
-The placeholders must be resolved using values provided using a Secret.
+Resolve the placeholders using values provided using a Secret.
 
 . You must edit the corresponding Secret and provide appropriate base64-encoded values to resolve the placeholders in `application.properties` as shown in the following example:
 +
@@ -104,7 +102,7 @@ NAME                    READY   STATUS    RESTARTS   AGE
 basic-f7c6ff455-grkxd   1/1     Running   0          47s
 ----
 
-. Once the pod is in the `Running` state, the workflow now appears in the Orchestrator plugin inside {product}.
+. Once the pod is in the `Running` state, the workflow now appears in the Orchestrator plugin inside the {product}.
 
 .Next steps
 * Inspect the provided build script to extract the actual steps and implement them in your preferred CI/CD tool for example GitHub Actions, GitLab CI, Jenkins and Tekton.