RHIDP-7556: Update-Orchestrator-documentation-1.7

assemblies/assembly-orchestrator-rhdh.adoc

@@ -33,4 +33,17 @@ include::modules/orchestrator/con-supported-architecture-for-orchestrator.adoc[l
 include::modules/orchestrator/con-understanding-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
 
 // installing the components for the orchestrator plugin
-include::modules/orchestrator/proc-install-components-for-orchestrator-plugin.adoc[leveloffset=+1]
+include::modules/orchestrator/con-install-components-orchestrator-plugin.adoc[leveloffset=+1]
+
+// manual installation
+include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2]
+
+// {product-very-short} helper script
+include::modules/orchestrator/con-helper-scripts-overview.adoc[leveloffset=+2]
+
+include::modules/orchestrator/proc-setup-sh-init-script.adoc[leveloffset=+3]
+
+include::modules/orchestrator/proc-plugin-infra-install.adoc[leveloffset=+3]
+
+// Orchestrator Infrastructure for {product} Helm chart
+include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2]

modules/orchestrator/con-helper-scripts-overview.adoc

@@ -0,0 +1,15 @@
+:mod-docs-content-type: CONCEPT
+[id="con-helper-scripts-overview_{context}"]
+= Helper scripts overview for the Orchestrator on {ocp-short}
+
+You can install the OpenShift Serverless infrastructure for the Orchestrator plugin using the {product-very-short} helper script. The following helper scripts are available to streamline non-production setup:
+
+* `setup.sh`: Initializes the {product-very-short} environment by creating the required authentication secret and labeling GitOps namespaces based on cluster configuration. It can use defaults or prompt for values.
+* `plugin-infra.sh`: Installs the OpenShift Serverless infrastructure required by the Orchestrator plugin.
+
+[NOTE]
+====
+These scripts are intended for quick-start scenarios and are **not recommended for production**.
+====
+
+For more information on controlling the installation of the Operators, see link:https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/[Install your Operator with OLM].

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

@@ -0,0 +1,28 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-install-components-orchestrator-plugin_{context}"]
+= Installing components for the Orchestrator plugin on {ocp-short}
+
+To run the Orchestrator plugin successfully on {ocp-short}, you must install components that provide the runtime environment and the dependencies that the plugin requires.
+
+.Required components
+
+* The Orchestrator plugin depends on the following components:
+
+** OpenShift Serverless Logic Operator
+** OpenShift Serverless Operator
+*** Knative Serving
+*** Knative Eventing
+** {product} ({product-very-short}) {product-custom-resource-type}
+** (Optional) An ArgoCD project named orchestrator requires a pre-installed ArgoCD or {company-name} OpenShift GitOps instance in the cluster. It is disabled by default.
+** (Optional) Tekton tasks and build pipeline. These require a pre-installed Tekton or {company-name} OpenShift Pipelines instance in the cluster, and are disabled by default.
++
+[NOTE]
+====
+You must preinstall the components, or install them by using one of the supported methods.
+====
+
+You can install the components (Operators) that provide the dependencies required by the Orchestrator plugin on {ocp-short} using the following methods:
+
+* Manual installation
+* {product-very-short} helper script
+* Orchestrator Infrastructure for {product} Helm chart

modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc

@@ -0,0 +1,16 @@
+:mod-docs-content-type: PROCEDURE
+[id="proc-helm-install-components-orchestrator-plugin_{context}"]
+= Installing the Orchestrator plugin components using the Orchestrator Infrastructure for {product} Helm chart
+
+You can use Orchestrator Infrastructure for {product} to install components for the Orchestrator plugins.
+
+[IMPORTANT]
+====
+By default, Orchestrator Infrastructure for {product} Helm chart does *not* auto-install or auto-upgrade the required Serverless Operators. You must approve the install plans.
+====
+
+.Procedure
+
+. Add or update the Helm repository for Orchestrator Infrastructure for {product}.
+. Install the chart with the required configuration for your environment.
+. Approve the install plans for the Serverless Operators when prompted.

modules/orchestrator/proc-install-rhdh-with-orchestrator-helm-webui.adoc

@@ -12,22 +12,20 @@ You can install {product} ({product-very-short}) with the Orchestrator by using
 
 .Procedure
 
-. In the {ocp-short} web console, go to menu:Helm[Helm Charts].
+. In the {ocp-short} web console, go to the Helm Charts and verify that the {product} Helm chart repository is available.
 
-. Click btn:[Repository] and confirm that the {product} Helm chart repository is available.
-
-. Search for the Orchestrator infrastructure for {product} and click btn:[Install].
+. Search for the Orchestrator infrastructure for {product} and select *Install*.
 +
 [IMPORTANT]
 ====
-You must be an administrator to install the Orchestrator Infrastructure for {product} Helm chart because it deploys cluster-scoped resources. As an administrator, you need to manually approve the install plans for OpenShift Serverless and Serverless Logic Operators.
+You must be an administrator to install the Orchestrator Infrastructure for {product} Helm chart because it deploys cluster-scoped resources. As an administrator, you must manually approve the install plans for OpenShift Serverless and Serverless Logic Operators.
 ====
 +
 As a regular user, search for the {product} chart and install it by setting the value of `orchestrator.enabled` to `true`. Otherwise, the Orchestrator will not be deployed.
 
 . Wait until they are successfully deployed.
 
-. Monitor the deployment status by navigating to menu:Workloads[Pods] or menu:Helm[Releases].
+. Monitor the deployment status by navigating to *Pods* or releases.
 
 .Verification
 

modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc

@@ -0,0 +1,65 @@
+:mod-docs-content-type: PROCEDURE
+[id="proc-manual-install-orchestrator-plugin_{context}"]
+= Manually installing the Orchestrator plugin components on {ocp-short}
+
+Use manual installation when you want full control of the setup process and component versions.
+
+.Procedure
+
+. Deploy the PostgreSQL reference implementation for persistence support in SonataFlow.
+
+. Create a namespace for the Orchestrator solution as shown in the following example:
++
+[subs="quotes+"]
+----
+oc new-project ${orchestrator}
+----
+
+. Run the setup script.
+Follow the steps in the _Installing the Orchestrator plugin components using the {product-very-short} helper script_ section to download and execute the `setup.sh` script, which initializes the {product-very-short} environment.
+
+. Install the Orchestrator Operator in the {ocp-short} cluster by applying the following manifest:
++
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: orchestrator-operator
+  namespace: openshift-operators
+spec:
+  channel: stable
+  installPlanApproval: Automatic
+  name: orchestrator-operator
+  source: redhat-operators
+  sourceNamespace: openshift-marketplace
+----
+
+. Verify installation by running the following command:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+wget https://raw.githubusercontent.com/rhdhorchestrator/orchestrator-go-operator/release-${PRODUCT_VERSION}/hack/wait_for_operator_installed.sh -O /tmp/wait_for_operator_installed.sh \ && chmod u+x /tmp/wait_for_operator_installed.sh \ && /tmp/wait_for_operator_installed.sh # Specify the {product} version in the URL
+----
+
+During installation, the Orchestrator Operator creates the following sub-components:
+
+* {product-very-short} Operator
+* OpenShift Serverless Operator
+* OpenShift Serverless Logic Operator
+
+It also creates the necessary custom resources (CRs) for Orchestrator to function properly.
+
+. Apply the Orchestrator custom resource (CR) to the cluster to create an instance of {product-very-short} and resources for OpenShift Serverless and OpenShift Serverless Logic:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+oc apply -n orchestrator -f https://raw.githubusercontent.com/rhdhorchestrator/orchestrator-go-operator/refs/heads/release-${PRODUCT_VERSION}/config/samples/_v1alpha3_orchestrator.yaml # Specify the {product} version in the URL
+----
+
+[NOTE]
+====
+After the first reconciliation of the Orchestrator CR, changes to some fields might not propagate to the intended resources. For example, updating the `platform.resources.requests` field in the Orchestrator CR has no effect on the running SonataFlowPlatform (SFP) resource.
+====
+
+For more information on preparing the required infrastructure, see link:https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.36[Red Hat OpenShift Serverless].

modules/orchestrator/proc-plugin-infra-install.adoc

@@ -0,0 +1,26 @@
+:mod-docs-content-type: PROCEDURE
+[id="proc-plugin-infra-install_{context}"]
+= Installing dependencies with `plugin-infra.sh`
+
+You can use the `{product-very-short}` helper script `plugin-infra.sh` to install the OpenShift Serverless infrastructure required by the Orchestrator plugin.
+
+[WARNING]
+====
+Do not use `plugin-infra.sh` in production.
+====
+
+.Procedure
+
+. Download the `plugin-infra.sh` script as shown in the following example:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-${PRODUCT_VERSION}/config/profile/rhdh/plugin-infra/plugin-infra.sh # Specify the {product} version in the URL or use main
+----
+
+. Run the script:
++
+[source,terminal]
+----
+$ ./plugin-infra.sh
+----

modules/orchestrator/proc-setup-sh-init-script.adoc

@@ -0,0 +1,69 @@
+:mod-docs-content-type: PROCEDURE
+[id="proc-setup-sh-init-script_{context}"]
+= Installing the Orchestrator plugin components using the `setup.sh` script
+
+The `setup.sh` script simplifies the initialization of the {product-very-short} environment by:
+
+* Creating the required authentication secret.
+* Labeling GitOps namespaces based on the cluster configuration.
+
+.Procedure
+
+. Create a namespace for the {product-very-short} instance. This namespace is predefined as the default in both the `setup.sh` script and the Orchestrator CR, but you can override it as shown in the following example:
++
+[subs="quotes+"]
+----
+oc new-project ${product-very-short}
+----
+
+. Download the setup script from the GitHub repository:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+wget https://raw.githubusercontent.com/rhdhorchestrator/orchestrator-go-operator/release-${PRODUCT_VERSION}/hack/setup.sh -O /tmp/setup.sh \ && chmod u+x /tmp/setup.sh # Specify the {product} version in the URL
+----
+
+. Run the setup script:
++
+[source,terminal]
+----
+/tmp/setup.sh --use-default
+----
++
+[NOTE]
+====
+To specify custom values, omit the `--use-default` option. The script will then prompt you for input.
+====
+
+The contents of the secret vary depending on cluster configuration and can include the following keys:
+
+* `BACKEND_SECRET`: Randomly generated. This is mandatory for the {product-very-short} Operator to start.
+* `K8S_CLUSTER_URL`: Dynamically obtained with `oc whoami --show-server`.
+* `K8S_CLUSTER_TOKEN`: Dynamically obtained from the service account and namespace.
+* `GITHUB_TOKEN`: Prompted from the user.
+* `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`: Used to authenticate against GitHub.
+* `GITLAB_HOST` and `GITLAB_TOKEN`: Used to authenticate against GitLab.
+* `ARGOCD_URL`: Obtained from the first ArgoCD instance available.
+* `ARGOCD_USERNAME`: Defaults to `admin`.
+* `ARGOCD_PASSWORD`: Obtained dynamically from the ArgoCD instance.
+
+Keys without values are omitted. For example, if no GitOps operator is installed, the ArgoCD-related keys are excluded.
+
+.Sample secret in a GitOps environment:
+[source,yaml]
+----
+apiVersion: v1
+data:
+  ARGOCD_PASSWORD: ...
+  ARGOCD_URL: ...
+  ARGOCD_USERNAME: ...
+  BACKEND_SECRET: ...
+  GITHUB_TOKEN: ...
+  K8S_CLUSTER_TOKEN: ...
+  K8S_CLUSTER_URL: ...
+kind: Secret
+metadata:
+  name: backstage-backend-auth-secret
+  namespace: rhdh
+type: Opaque
+----