diff --git a/assemblies/assembly-orchestrator-rhdh.adoc b/assemblies/assembly-orchestrator-rhdh.adoc index a1612f9678..9d22c3875a 100644 --- a/assemblies/assembly-orchestrator-rhdh.adoc +++ b/assemblies/assembly-orchestrator-rhdh.adoc @@ -27,7 +27,7 @@ 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] @@ -35,8 +35,8 @@ include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leve // 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] \ No newline at end of file diff --git a/modules/orchestrator/con-architecture-overview.adoc b/modules/orchestrator/con-architecture-overview.adoc new file mode 100644 index 0000000000..1990dfb9f1 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/modules/orchestrator/con-orchestrator-plugin-components.adoc b/modules/orchestrator/con-orchestrator-plugin-components.adoc deleted file mode 100644 index 5f578163d4..0000000000 --- a/modules/orchestrator/con-orchestrator-plugin-components.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_mod-docs-content-type: CONCEPT -[id="con-orchestrator-plugin-components.adoc_{context}"] -= Orchestrator plugin components on {ocp-short} - -To run the Orchestrator plugin successfully on {ocp-short}, you must first install the following required components: - -** {product} ({product-very-short}) {product-custom-resource-type} -** OpenShift Serverless Logic Operator -** OpenShift Serverless Operator -*** Knative Serving -*** Knative Eventing -** (Optional) For managing the Orchestrator project, you need a preinstalled instance of Argo CD or {company-name} OpenShift GitOps in the cluster. It is disabled by default. -** (Optional) To use Tekton tasks and the build pipeline, you need a preinstalled instance of Tekton or {company-name} OpenShift Pipelines in the cluster. These features are disabled by default. - -The most recommended approach to install the dependencies for the Orchestrator plugin is by enabling the dependencies for the Orchestrator plugin directly during your {product-very-short} installation. When you configure {product-very-short} to include the Orchestrator plugin, the {product-very-short} Operator installs the necessary OpenShift Serverless operators, eliminating the need for separate scripts or Helm charts. - -For specific use cases, you can choose to install the dependencies manually or use helper utilities. \ No newline at end of file diff --git a/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc b/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc deleted file mode 100644 index 3bcedcabd4..0000000000 --- a/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc +++ /dev/null @@ -1,14 +0,0 @@ -:_mod-docs-content-type: CONCEPT -[id="con-supported-architecture-for-orchestrator_{context}"] -= Supported architecture for Orchestrator - -You can use Orchestrator to design, run, and monitor workflows that automate key tasks. It builds on components like SonataFlow and OpenShift Serverless, which provide the runtime environment and event-driven capabilities needed to power your workflows. - -To help you get started quickly, the following Orchestrator plugin components are included but disabled by default in the `dynamic-plugins.default.yaml` file: - -* `"backstage-plugin-orchestrator"` -* `"backstage-plugin-orchestrator-backend-dynamic"` -* `"backstage-plugin-scaffolder-backend-module-orchestrator-dynamic"` -* `"backstage-plugin-orchestrator-form-widgets"` - -To enable these plugins, set the `plugins.disabled` parameter to `false`. \ No newline at end of file diff --git a/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc b/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc new file mode 100644 index 0000000000..7fce154dcb --- /dev/null +++ b/modules/orchestrator/proc-enabling-orchestrator-plugins-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 +---- \ No newline at end of file