From 51a7191f5325bf357902ef3d0ed94a5c39bba606 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 21 May 2026 20:45:47 +0200 Subject: [PATCH] Add Operator configuration flavours to RHDH documentation --- ...th-predefined-operator-configurations.adoc | 25 +++ ...c-deploy-rhdh-for-workflow-automation.adoc | 106 +++++++++++++ ...figured-settings-for-common-use-cases.adoc | 143 ++++++++++++++++++ titles/configure_configuring-rhdh/master.adoc | 2 + 4 files changed, 276 insertions(+) create mode 100644 assemblies/configure_configuring-rhdh/assembly-automate-environment-provisioning-with-predefined-operator-configurations.adoc create mode 100644 modules/configure_configuring-rhdh/proc-deploy-rhdh-for-workflow-automation.adoc create mode 100644 modules/configure_configuring-rhdh/ref-pre-configured-settings-for-common-use-cases.adoc diff --git a/assemblies/configure_configuring-rhdh/assembly-automate-environment-provisioning-with-predefined-operator-configurations.adoc b/assemblies/configure_configuring-rhdh/assembly-automate-environment-provisioning-with-predefined-operator-configurations.adoc new file mode 100644 index 00000000000..32f8609619c --- /dev/null +++ b/assemblies/configure_configuring-rhdh/assembly-automate-environment-provisioning-with-predefined-operator-configurations.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +ifdef::context[:parent-context: {context}] + +[id="automate-environment-provisioning-with-predefined-operator-configurations_{context}"] += Automate environment provisioning with predefined Operator configurations + +:context: automate-environment-provisioning-with-predefined-operator-configurations + +[role="_abstract"] +To reduce manual plugin configuration, you can deploy {product} with predefined settings for workflow orchestration or AI assistance. + +include::../modules/configure_configuring-rhdh/ref-pre-configured-settings-for-common-use-cases.adoc[leveloffset=+1] + +include::../modules/configure_configuring-rhdh/proc-deploy-rhdh-for-workflow-automation.adoc[leveloffset=+1] + +// TODO: Uncomment after PR #2210 is merged (Lightspeed configuration docs by pabel-rh) +// See: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/pull/2210 +// Preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-2210/integrate_interacting-with-developer-lightspeed-for-rhdh/ +// include::../modules/shared/proc-configure-by-using-the-operator.adoc[leveloffset=+1] + +// TODO: Section 4.3 removed per Gennady's feedback - will revisit later when users can inspect default configurations +// include::../modules/configure_configuring-rhdh/con-combine-default-configurations-with-custom-resource-overrides-to-fine-tune-deployments.adoc[leveloffset=+1] + +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/modules/configure_configuring-rhdh/proc-deploy-rhdh-for-workflow-automation.adoc b/modules/configure_configuring-rhdh/proc-deploy-rhdh-for-workflow-automation.adoc new file mode 100644 index 00000000000..260e73c9b59 --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-deploy-rhdh-for-workflow-automation.adoc @@ -0,0 +1,106 @@ +:_mod-docs-content-type: PROCEDURE + +[id="deploy-rhdh-for-workflow-automation_{context}"] += Deploy {product} for workflow automation + +[role="_abstract"] +To automate CI/CD pipeline setup, deploy {product} with workflow orchestration by using predefined Operator configurations. + +.Prerequisites + +* You have installed the {product} Operator in your OpenShift cluster. +* You have installed required infrastructure components: +** OpenShift Serverless Operator +** Knative Serving +** Knative Eventing +** OpenShift Serverless Logic Operator +* Optional: For production deployments, you have {configuring-book-link}#configure-external-postgresql-databases_configuring-rhdh[configured an external PostgreSQL database] and created a Secret with connection credentials. +* Optional: You have AMQ Streams (`Kafka`) installed for event-driven workflow processing. + +.Procedure + +. Create a namespace for your {product} instance or use an existing namespace: ++ +[source,terminal,subs="+attributes"] +---- +$ oc new-project {my-product-namespace} +---- + +. Create a {product-custom-resource-type} CR with the Orchestrator deployment configuration: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ cat < +spec: + flavours: + - name: orchestrator + enabled: true +EOF +---- ++ +Where: ++ +``:: A name for your {product} instance, for example `developer-hub-orchestrator`. +`spec.flavours`:: The pre-configured settings array. Set `name: orchestrator` with `enabled: true` to automatically configure workflow orchestration capabilities. + ++ +[NOTE] +==== +This example uses the default local PostgreSQL database. +For production deployments, Red Hat recommends using an external PostgreSQL database. +If you configured an external database in the prerequisites, add the database configuration to the CR as shown in {configuring-book-link}#configure-external-postgresql-databases_configuring-rhdh[Configure external PostgreSQL databases]. +==== + +. Wait for the Operator to reconcile the {product-custom-resource-type} CR: ++ +[source,terminal,subs="+attributes"] +---- +$ oc get backstage -n {my-product-namespace} -w +---- ++ +The deployment is ready when the `PHASE` column shows `Deployed`. + +.Verification + +. Verify that the Data Index service pod is running: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc get pods -n {my-product-namespace} | grep sonataflow +---- ++ +You should see the Data Index service pod. The Orchestrator backend plugin runs within the main {product} pod. + +. Access the {product} UI: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc get route backstage- -n {my-product-namespace} -o jsonpath='{.spec.host}' +---- ++ +Go to the URL in your browser. + +. Verify the Orchestrator plugin is displayed in the {product} navigation menu. +Look for the *Orchestrator* option in the left navigation panel. + +. Optional: Test workflow deployment by creating a sample workflow. For detailed workflow examples, see {product-docs-link}/html/orchestrator_in_red_hat_developer_hub/index[Orchestrator in {product}]. + +.Troubleshooting + +If workflow pods fail to start:: +Verify the PostgreSQL connection by checking the Operator logs: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc logs -n openshift-operators deployment/rhdh-operator -c manager +---- ++ +Ensure the database credentials in the Secret are correct and the database is accessible from the cluster. + +If the Data Index service fails:: +Verify that the PostgreSQL user has permissions to create schemas and tables. +The Orchestrator deployment configuration automatically initializes required database schemas. diff --git a/modules/configure_configuring-rhdh/ref-pre-configured-settings-for-common-use-cases.adoc b/modules/configure_configuring-rhdh/ref-pre-configured-settings-for-common-use-cases.adoc new file mode 100644 index 00000000000..a4cffc8d5b0 --- /dev/null +++ b/modules/configure_configuring-rhdh/ref-pre-configured-settings-for-common-use-cases.adoc @@ -0,0 +1,143 @@ +:_mod-docs-content-type: REFERENCE + +[id="pre-configured-settings-for-common-use-cases_{context}"] += Pre-configured settings for common use cases + +[role="_abstract"] +To choose the appropriate configuration for your use case, review the available predefined settings, their infrastructure prerequisites, and minimal Custom Resource examples. + +{product} Operator 1.10.0 and later includes pre-configured settings for common use cases. +Each configuration automatically applies required plugins, dependencies, and app-config settings. + +[cols="1,2,2,2", options="header"] +|=== +| Name +| Purpose +| Infrastructure prerequisites +| Default status + +| `orchestrator` +| Workflow automation for CI/CD pipelines +| OpenShift Serverless Operator, Knative Serving, Knative Eventing, OpenShift Serverless Logic Operator, PostgreSQL database, optional AMQ Streams +| Disabled by default - enable explicitly + +| `lightspeed` +| AI chat assistance for developers +| External LLM provider (OpenAI-compatible API) +| Enabled by default - disable to turn off +|=== + +== Orchestrator + +Enable workflow automation with automatic plugin configuration. + +*Automatically configured components:* + +* Orchestrator front-end plugin (`red-hat-developer-hub-backstage-plugin-orchestrator`) +* Orchestrator backend plugin (`red-hat-developer-hub-backstage-plugin-orchestrator-backend`) +* Orchestrator backend module for Scaffolder (`red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator`) +* Orchestrator form widgets plugin (`red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets`) +* `SonataFlow` Operator integration +* Data Index service +* Job service + +*Minimal CR example:* + +[source,yaml,subs="+attributes"] +---- +apiVersion: rhdh.redhat.com/v1alpha5 +kind: {product-custom-resource-type} +metadata: + name: developer-hub-orchestrator +spec: + flavours: + - name: orchestrator + enabled: true +---- + +[NOTE] +==== +This example uses the default local PostgreSQL database. +For production deployments, Red Hat recommends using an external PostgreSQL database. +For configuration details, see {configuring-book-link}#configure-external-postgresql-databases_configuring-rhdh[Configure external PostgreSQL databases]. +==== + +*Prerequisites:* + +* OpenShift Serverless Operator, Knative Serving, Knative Eventing, and OpenShift Serverless Logic Operator +* PostgreSQL database (external database recommended for production) +* Optional: AMQ Streams (Kafka) for event-driven workflows ++ +For detailed steps, see xref:deploy-rhdh-for-workflow-automation_{context}[Deploy {product} for workflow automation]. + +== {ls-short} + +{ls-short} is enabled by default in {product} 1.10.0 and later. Connect your LLM provider to use AI chat assistance. + +*Automatically configured components:* + +* {ls-short} front-end plugin +* {ls-short} backend plugin +* {lcs-name} sidecar + +*Minimal CR example:* + +[source,yaml,subs="+attributes"] +---- +apiVersion: rhdh.redhat.com/v1alpha5 +kind: {product-custom-resource-type} +metadata: + name: developer-hub +spec: + application: + extraEnvs: + secrets: + - name: lightspeed-secrets + containers: + - lightspeed-core +---- + +[NOTE] +==== +{ls-short} is enabled by default. +You do not need to set `spec.flavours` to enable AI assistance. +To disable, set `spec.flavours: [{name: lightspeed, enabled: false}]`. +==== + +*Prerequisites:* + +* External LLM provider endpoint (OpenAI, {azure-short} OpenAI, or compatible API) +* LLM API credentials ++ +For complete configuration details, provider-specific guidance, and troubleshooting, see {developer-lightspeed-book-link}#install-and-configure_interacting-with-developer-lightspeed-for-rhdh[Install and configure {ls-brand-name}]. + +== Multiple pre-configured settings + +Enable both Orchestrator and {ls-short} in a single deployment: + +[source,yaml,subs="+attributes"] +---- +apiVersion: rhdh.redhat.com/v1alpha5 +kind: {product-custom-resource-type} +metadata: + name: developer-hub-full +spec: + flavours: + - name: orchestrator + enabled: true + application: + extraEnvs: + secrets: + - name: lightspeed-secrets + containers: + - lightspeed-core +---- + +[NOTE] +==== +{ls-short} is enabled by default, so you only need to explicitly enable Orchestrator. +Settings from both configurations merge automatically. +For production deployments with external PostgreSQL database, add the database configuration as shown in {configuring-book-link}#configure-external-postgresql-databases_configuring-rhdh[Configure external PostgreSQL databases]. +==== + +You must meet prerequisites for both: OpenShift Serverless components for Orchestrator and external LLM provider for {ls-short}. diff --git a/titles/configure_configuring-rhdh/master.adoc b/titles/configure_configuring-rhdh/master.adoc index 03467d927de..f2483696e75 100644 --- a/titles/configure_configuring-rhdh/master.adoc +++ b/titles/configure_configuring-rhdh/master.adoc @@ -30,6 +30,8 @@ include::assemblies/configure_configuring-rhdh/assembly-rhdh-default-configurati include::assemblies/configure_configuring-rhdh/assembly-migrate-to-the-front-end-system-to-use-blueprint-based-dynamic-routing.adoc[leveloffset=+1] +include::assemblies/configure_configuring-rhdh/assembly-automate-environment-provisioning-with-predefined-operator-configurations.adoc[leveloffset=+1] + include::assemblies/configure_configuring-rhdh/assembly-configure-external-postgresql-databases.adoc[leveloffset=+1] include::assemblies/configure_configuring-rhdh/assembly-configure-high-availability-in-rhdh.adoc[leveloffset=+1]