Manual cherry pick 1422 (#1440)

Author: jmagak

assemblies/assembly-orchestrator-rhdh.adoc

@@ -27,16 +27,16 @@ To start using Orchestrator in {product-very-short}, you must:
 * Import the Orchestrator software templates into the {product} catalog
 
 // orchestrator architecture
-include::modules/orchestrator/con-supported-architecture-for-orchestrator.adoc[leveloffset=+1]
+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]
 
 // provisioning plugin dependencies
 include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
 
-// installing the components for the orchestrator plugin
-include::modules/orchestrator/con-orchestrator-plugin-components.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]
@@ -45,5 +45,4 @@ include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.a
 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]
-
+include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2]

modules/orchestrator/con-architecture-overview.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-architecture-overview.adoc_{context}"]
+= Understand Orchestrator architecture
+
+The Orchestrator architecture is composed of several components, each contributing to the running and management of workflows.
+
+{product} ({product-very-short}):: Serves as the primary interface. It contains the following subcomponents:
+
+Orchestrator frontend plugins::: Provide the interface for users to run and monitor workflows within {product-very-short}.
+
+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.
+
+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.
+
+PostgreSQL Server::: Provides a database solution essential for data persistence within the Orchestrator ecosystem. The system uses PostgreSQL Server for storing both Sonataflow information and {product-short} data.
+
+Keycloak:: Provides authentication and security services within applications. Keycloak must be provisioned externally to manage authentication, as the Orchestrator Operator does not install it.
+
+OpenShift AMQ Streams (Strimzi/Kafka):: Provides enhanced reliability of the eventing system. Eventing can work without Kafka by using direct HTTP calls, however, this approach is not reliable.
++
+Optional: The current deployment iteration does not natively integrate or include the AMQ Streams Operator. However, you can add the Operator post-install for enhanced reliability if you require it.

modules/orchestrator/con-orchestrator-plugin-components.adoc

@@ -0,0 +1,89 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-enabling-orchestrator-plugins-components.adoc_{context}"]
+= Enabling Orchestrator plugins components
+
+To use the Orchestrator, enable the Orchestrator plugins for {product}, that are disabled by default:
+
+Orchestrator frontend plugins::
+
+`backstage-plugin-orchestrator`:::
+Provides the interface for users to run and monitor workflows within {product-very-short}. You can run and track the execution status of processes.
+
+`backstage-plugin-orchestrator-form-widgets`:::
+Provides custom widgets for the workflow execution form, allowing you to customize input fields and streamline the process of launching workflows.
+
+`backstage-plugin-orchestrator-form`:::
+Provides the workflow execution form where you can define and submit the necessary input data required to start a new workflow instance.
+
+`backstage-plugin-orchestrator-form-api`:::
+Defines the API for extending the workflow execution form.
+
+Orchestrator backend plugins::
+
+`backstage-plugin-orchestrator-backend`:::
+Gets workflow data into {product-short} making sure {product-very-short} ingests critical workflow metadata and runtime status fulfilling your need for visibility.
+
+`backstage-plugin-orchestrator-common`:::
+Contains the backend OpenAPI specification along with autogenerated API documentation and client libraries.
+
+`scaffolder-backend-module-orchestrator`:::
+Provides callable actions from scaffolder templates, such as `orchestrator:workflow:run` or `orchestrator:workflow:get_params`.
+
+Notification plugins::
+
+`backstage-plugin-notifications`:::
+Provides notification frontend components that allow you to display immediate, visible alerts about key workflow state changes, allowing real-time status tracking.
+
+
+`backstage-plugin-signals`:::
+Provides notification frontend components user experience enhancements so you can process the real-time lifecycle events.
+
+`backstage-plugin-notifications-backend-dynamic`:::
+Provides notification backend components allowing you to manage and store the stream of workflow events, making sure that critical notifications are ready to be served to the front-end user interface.
+
+`backstage-plugin-signals-backend-dynamic`:::
+Provides the backend components for notification user experience enhancements allowing you to establish the necessary communication channels for the event-driven orchestration that is core to Serverless Workflows.
+
+.Prerequisites
+
+* When using the {product} Helm chart, you have installed the necessary OpenShift Serverless Operators.
++
+[NOTE]
+====
+When using the {product} Operator, the Operator installs the necessary OpenShift Serverless Operators automatically. For specific use cases, install the dependencies manually or use helper utilities.
+====
+
+* (Optional) For managing the Orchestrator project, you have an instance of Argo CD or Red Hat OpenShift GitOps in the cluster. It is disabled by default.
+
+* (Optional) To use Tekton tasks and the build pipeline, you have an instance of Tekton or Red Hat OpenShift Pipelines in the cluster. These features are disabled by default.
+
+.Procedure
+* Locate your {product-short} configuration and enable the Orchestrator plugins and the supporting notification plugins.
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+plugins:
+  - package: "@redhat/backstage-plugin-orchestrator@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-orchestrator-form-widgets@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-orchestrator-common@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-orchestrator-form@{product-chart-version}"
+    disabled: false
+  - package: "@redhat/backstage-plugin-orchestrator-form-api@{product-chart-version}"
+    disabled: false
+  - package: "./dynamic-plugins/dist/backstage-plugin-notifications"
+    disabled: false
+  - package: "./dynamic-plugins/dist/backstage-plugin-signals"
+    disabled: false
+  - package: "./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic"
+    disabled: false
+  - package: "./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic"
+    disabled: false
+----