redhat-developer · jmagak · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc
@@ -29,6 +29,7 @@
 :ocp-version: 4.19
 :osd-version: 4
 :rhoserverless-version: 1.36
+:orchestrator-plugin-version: 1.8.2
 
 // Product recurrent configuration items (in alphabetical order)
 :my-app-config-config-map: my-rhdh-app-config

diff --git a/assemblies/assembly-building-and-deploying-serverless-workflows.adoc b/assemblies/assembly-building-and-deploying-serverless-workflows.adoc
@@ -42,4 +42,7 @@ include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffs
 include::modules/orchestrator/con-generated-workflow-manifests.adoc[leveloffset=+1]
 
 // deploy workflows on a cluster
-include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]
+include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1]
+
+// best practices when creating workflows
+include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator-helm.adoc b/assemblies/assembly-install-rhdh-orchestrator-helm.adoc
@@ -0,0 +1,21 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="install-rhdh-orchestrator-helm"]
+endif::[]
+ifdef::context[]
+[id="assembly-install-rhdh-orchestrator-helm"]
+endif::[]
+:context: install-rhdh-orchestrator
+= Installing {product} with Orchestrator by using the {product} Helm chart
+
+You can install {product} with Orchestrator by using the {product} Helm chart.
+
+include::modules/orchestrator/proc-install-rhdh-with-orchestrator-helm-cli.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-install-rhdh-with-orchestrator-helm-webui.adoc[leveloffset=+1]
+
+include::modules/orchestrator/ref-orchestrator-resource-limits.adoc[leveloffset=+1]
+
+// manual installation
+include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator-operator.adoc b/assemblies/assembly-install-rhdh-orchestrator-operator.adoc
@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="install-rhdh-orchestrator-operator"]
+endif::[]
+ifdef::context[]
+[id="assembly-install-rhdh-orchestrator-operator"]
+endif::[]
+:context: install-rhdh-orchestrator
+= Installing {product} with Orchestrator by using the {product} Operator
+
+You can install {product} with Orchestrator by using the {product} Operator.
+
+include::modules/orchestrator/proc-enable-orchestrator-plugin.adoc[leveloffset=+1]
+
+include::modules/orchestrator/proc-upgrading-the-orchestrator-plugin.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-install-rhdh-orchestrator.adoc b/assemblies/assembly-install-rhdh-orchestrator.adoc
diff --git a/assemblies/assembly-orchestrator-plugins-components.adoc b/assemblies/assembly-orchestrator-plugins-components.adoc
@@ -0,0 +1,8 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-orchestrator-plugins-components_{context}"]
+
+= Enabling Orchestrator plugins components
+
+// enabling orchestrator plugins components
+include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-orchestrator-plugins-technical-appendixes.adoc b/assemblies/assembly-orchestrator-plugins-technical-appendixes.adoc
@@ -0,0 +1,10 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly-orchestrator-plugins-technical-appendixes_{context}"]
+
+= Technical appendix
+
+The following appendix provides technical information, and details on non-production tools, such as the {product-very-short} helper script, which might be helpful for understanding setup options or quick testing.
+
+// {product-very-short} helper script
+include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-orchestrator-rhdh.adoc → ...ies/assembly-rhdh-about-orchestrator.adoc b/assemblies/assembly-orchestrator-rhdh.adoc → ...ies/assembly-rhdh-about-orchestrator.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 
 ifndef::context[]
-[id="assembly-orchestrator-rhdh.adoc"]
+[id="assembly-orchestrator-rhdh"]
 endif::[]
 ifdef::context[]
 [id="assembly-orchestrator-rhdh"]
@@ -20,31 +20,14 @@ You can streamline and automate your work by using the Orchestrator in {product}
 Orchestrator currently supports only {ocp-brand-name} ({ocp-short}); it is not available on {aks-brand-name} ({aks-short}), {eks-brand-name} ({eks-short}), or {gke-brand-name} ({gke-short}).
 ====
 
-To start using Orchestrator in {product-very-short}, you must:
-
-* Install the required infrastructure components, such as Red Hat OpenShift Serverless Operator, Knative Serving, Knative Eventing, and OpenShift Serverless Logic Operator
-* Configure your {product-custom-resource-type} custom resource (CR) or Helm values file for Orchestrator
+// compatibility guide for {product} Orchestrator
+include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1]
 
 // orchestrator architecture
 include::modules/orchestrator/con-architecture-overview.adoc[leveloffset=+1]
 
-// compatibility guide for {product} Orchestrator
-include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1]
+// getting started
+include::modules/orchestrator/con-getting-started.adoc[leveloffset=+1]
 
 // provisioning plugin dependencies
-include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
-
-// enabling orchestrator plugins components
-include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1]
-
-// Orchestrator Infrastructure for {product} Helm chart
-include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2]
-
-// manual installation
-include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2]
-
-// {product-very-short} helper script
-include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]
-
-// best practices when creating workflows
-include::modules/orchestrator/ref-best-practices-for-creating-workflows.adoc[leveloffset=+1]
+include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
diff --git a/modules/orchestrator/con-architecture-overview.adoc b/modules/orchestrator/con-architecture-overview.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-architecture-overview.adoc_{context}"]
+[id="con-architecture-overview_{context}"]
 = Understand Orchestrator architecture
 
 The Orchestrator architecture is composed of several components, each contributing to the running and management of workflows.
@@ -13,16 +13,12 @@ Orchestrator backend plugins::: Get workflow data into {product-short}.
 
 Notifications plugins::: Inform users about workflow events.
 
-Sonataflow::
-
-The Sonataflow orchestrator and its subcomponents handle the workflows.
-The {product} Orchestrator and the {product} Helm chart manage the following subcomponents lifecycle:
-
-OpenShift Serverless Logic Operator::: Manages the Sonataflow custom resource (CR), where each CR represents a deployed workflow.
+Openshift Serverless Logic Operator:: Serves as the workflow engine, and its subcomponents handle running, executing and providing persistence for the workflows. The {product} Operator and the {product} Helm chart manage the following lifecycle of these subcomponents:
 
 Sonataflow Runtime/Workflow Application::: Functions as a deployed workflow. Operates as an HTTP server, handling requests for running workflow instances. It is managed as a Kubernetes (K8s) deployment by the Openshift Serverless Logic Operator.
 
 Data Index Service::: Serves as a repository for workflow definitions, instances, and associated jobs. It exposes a GraphQL API used by the Orchestrator backend plugin to retrieve workflow definitions and instances.
+
 Job Service::: Orchestrates scheduled tasks for workflows.
 
 OpenShift Serverless::: Provides serverless capabilities essential for workflow communication. It employs Knative eventing to interface with the Data Index service and uses Knative functions to introduce more complex logic to workflows.

diff --git a/modules/orchestrator/con-benefits-of-workflow-images.adoc b/modules/orchestrator/con-benefits-of-workflow-images.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-benefits-of-workflow-images.adoc_{context}"]
+[id="con-benefits-of-workflow-images_{context}"]
 = Benefits of workflow images
 
 While the OpenShift Serverless Logic Operator supports the building of workflows dynamically, this approach is primarily for experimentation.

diff --git a/modules/orchestrator/con-build-sh-script-and-its-uses.adoc b/modules/orchestrator/con-build-sh-script-and-its-uses.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-build-sh-script-and-its-uses.adoc_{context}"]
+[id="con-build-sh-script-and-its-uses_{context}"]
 = The `build-sh` script functionality and important flags
 
 The `build-sh` script does the following tasks in order:

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
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-environment-variables-supported-by-the-build-script.adoc_{context}"]
+[id="con-environment-variables-supported-by-the-build-script_{context}"]
 = 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:

diff --git a/modules/orchestrator/con-generated-workflow-manifests.adoc b/modules/orchestrator/con-generated-workflow-manifests.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-generated-workflow-manifests.adoc_{context}"]
+[id="con-generated-workflow-manifests_{context}"]
 = Generated workflow manifests
 
 The following example is an illustration of what is generated under the `01_basic/manifests`:

diff --git a/modules/orchestrator/con-getting-started.adoc b/modules/orchestrator/con-getting-started.adoc
@@ -0,0 +1,17 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-getting-started_{context}"]
+= Getting started with Orchestrator
+
+To start using Orchestrator in {product-very-short}, you must:
+
+* Install the required infrastructure components, such as OpenShift Serverless Operator, and OpenShift Serverless Logic Operator
+
+* Configure your {product-custom-resource-type} custom resource (CR) or Helm values file for Orchestrator
+
+[NOTE]
+====
+When using the {product-very-short} Operator, you must first install the required infrastructure components. The Operator then provisions the dependent SonataFlow resources once the Orchestrator plugins are enabled in the {product-custom-resource-type} CR.
+
+When using the {product-very-short} Helm chart, the required infrastructure components are installed automatically using the dedicated `redhat-developer-hub-orchestrator-infra` Helm chart prior to enabling the Orchestrator plugins in the main {product-very-short} chart.
+====
diff --git a/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc b/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-orchestrator-plugin-dependencies-operator.adoc_{context}"]
+[id="con-orchestrator-plugin-dependencies-operator_{context}"]
 = Orchestrator plugin dependencies for Operator installation
 
 When you enable the Orchestrator plugin in your {product-custom-resource-type} custom resource (CR), the Operator automatically provisions the following required dependencies:
@@ -44,4 +44,4 @@ The Operator automatically creates the required Role and _RoleBinding_ resource
 ====
 
 .Additional resources
-* link:https://github.com/redhat-developer/rhdh-operator/blob/release-1.7/docs/dynamic-plugins.md#dynamic-plugins-dependency-management[Dynamic plugins dependency management]
+* link:https://github.com/redhat-developer/rhdh-operator/blob/release-{product-version}/docs/dynamic-plugins.md#dynamic-plugins-dependency-management[Dynamic plugins dependency management]
diff --git a/modules/orchestrator/con-project-structure-overview.adoc b/modules/orchestrator/con-project-structure-overview.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-project-structure-overview.adoc_{context}"]
+[id="con-project-structure-overview_{context}"]
 = Project structure overview
 
 The project utilizes *Quarkus project layout* (Maven project structure). This structure is illustrated by the following `01_basic` workflow example:

diff --git a/modules/orchestrator/con-required-tools.adoc b/modules/orchestrator/con-required-tools.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="con-required-tools.adoc_{context}"]
+[id="con-required-tools_{context}"]
 = Required tools
 
 To run the `build-sh` script locally and manage the workflow lifecycle, you must install the following command-line tools:

diff --git a/modules/orchestrator/proc-building-locally.adoc b/modules/orchestrator/proc-building-locally.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-building-locally.adoc_{context}"]
+[id="proc-building-locally_{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.

diff --git a/modules/orchestrator/proc-building-the-01-basic-workflow.adoc b/modules/orchestrator/proc-building-the-01-basic-workflow.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-building-the-01-basic-workflow.adoc_{context}"]
+[id="proc-building-the-01-basic-workflow_{context}"]
 = Building the `01_basic` workflow
 
 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.

diff --git a/modules/orchestrator/proc-creating-and-running-workflows.adoc b/modules/orchestrator/proc-creating-and-running-workflows.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-creating-and-running-workflows.adoc_{context}"]
+[id="proc-creating-and-running-workflows_{context}"]
 = Creating and running your serverless workflow project locally
 
 The `kn-workflow` CLI is an essential tool that generates workflow manifests and project structures. To ensure successful development and immediate testing, begin developing a new serverless workflow locally by completing the following steps:

diff --git a/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc b/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="proc-deploying-workflows-on-a-cluster.adoc_{context}"]
+[id="proc-deploying-workflows-on-a-cluster_{context}"]
 = Deploying workflows on a cluster
 
 You can deploy the workflow on a cluster, since the image is pushed to the image registry and the deployment manifests are available.

diff --git a/modules/orchestrator/proc-enable-orchestrator-plugin.adoc b/modules/orchestrator/proc-enable-orchestrator-plugin.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="proc-enable-orchestrator-plugin_{context}"]
-= Enabling the Orchestrator plugin using Operator
+= Enabling the Orchestrator plugin using the Operator
 
 You can enable the Orchestrator plugin in {product-very-short} by configuring dynamic plugins in your {product-custom-resource-type} custom resource (CR).
 
@@ -19,8 +19,14 @@ You can enable the Orchestrator plugin in {product-very-short} by configuring dy
   disabled: false
 ----
 +
+[NOTE]
+====
+When you enable the plugins, the pre-loaded plugin configuration are used.
+Additionally, the `ref: sonataflow` field installs the Openshift Serverless and Openshift Serverless Logic resources. This happens automatically when you are using the Operator.
+====
++
 .Example: Complete configuration of the Orchestrator plugin
-[source,yaml]
+[source,subs="+attributes,+quotes"]
 ----
 apiVersion: v1
 kind: ConfigMap
@@ -31,7 +37,7 @@ data:
       includes:
         - dynamic-plugins.default.yaml
       plugins:
-        - package: "@redhat/backstage-plugin-orchestrator@1.7.1"
+        - package: "@redhat/backstage-plugin-orchestrator@{orchestrator-plugin-version}"
           disabled: false
           pluginConfig:
             dynamicPlugins:
@@ -59,21 +65,21 @@ data:
                           if:
                             anyOf:
                               - IsOrchestratorCatalogTabAvailable
-        - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@1.7.1"
+        - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@{orchestrator-plugin-version}"
           disabled: false
           pluginConfig:
             orchestrator:
               dataIndexService:
                 url: http://sonataflow-platform-data-index-service
           dependencies:
             - ref: sonataflow
-        - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@1.7.1"
+        - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@{orchestrator-plugin-version}"
           disabled: false
           pluginConfig:
             orchestrator:
               dataIndexService:
                 url: http://sonataflow-platform-data-index-service
-        - package: "@redhat/backstage-plugin-orchestrator-form-widgets@1.7.1"
+        - package: "@redhat/backstage-plugin-orchestrator-form-widgets@{orchestrator-plugin-version}"
           disabled: false
           pluginConfig:
             dynamicPlugins: