[release-1.9] docs(orchestrator): document workaround used for starting the Orchestrator in 1.9 [RHDHBUGS-2779]

[openshift-cherrypick-robot]

This is an automated cherry-pick of #183

/assign rm3l

[rhdh-qodo-merge]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🔒 No security concerns identified

⚡ Recommended focus areas for review Doc Accuracy The instruction to “Copy the plugins … directly into your override file” should be validated to ensure it matches how the override is merged (e.g., that duplicating plugins: is the intended approach and won’t conflict with any existing plugins: entries users may already have in their override). Consider explicitly stating whether users should merge into an existing plugins: list vs replacing it. Before you begin, ensure to add the orchestrator plugins to your `configs/dynamic-plugins/dynamic-plugins.override.yaml` to enable them within RHDH. Copy the [plugins](./configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) from `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml` directly into your override file. Example: ```yaml includes: - dynamic-plugins.default.yaml # Add the Orchestrator plugins directly, and add any other plugins you want to install, including local ones. plugins: - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator:{{inherit}}' disabled: false - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend:{{inherit}}' disabled: false pluginConfig: orchestrator: dataIndexService: url: http://sonataflow:8899 - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator:{{inherit}}' disabled: false pluginConfig: orchestrator: dataIndexService: url: http://sonataflow:8899 - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets:{{inherit}}' disabled: false </details> <details><summary><a href='https://github.com/redhat-developer/rhdh-local/pull/184/files#diff-ea8fd782400b3844725e6452541b7b5366630c010e22356379d8ea6f7bbf6596R7-R8'><strong>Link Robustness</strong></a> The README links to a specific line range in `dynamic-plugins.yaml`; line-number anchors can become stale as the file evolves. Consider linking to the file without line anchors or to a stable section/heading if available, to reduce future documentation drift. </summary> ```markdown Copy the [plugins](./configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) from `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml` directly into your override file. Example:

📚 Focus areas based on broader codebase context Missing Config The new Orchestrator enablement example adds plugin packages (and some pluginConfig) but omits other required configuration called out elsewhere, such as ensuring a secret containing BACKEND_SECRET is created and wired via the Backstage CR extraEnvs. Also, the backend package example in other docs includes explicit dependency handling for sonataflow, which is not reflected here—validate the Orchestrator starts without that dependency configuration in this setup. (Ref 1) Before you begin, ensure to add the orchestrator plugins to your `configs/dynamic-plugins/dynamic-plugins.override.yaml` to enable them within RHDH. Copy the [plugins](./configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) from `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml` directly into your override file. Example: ```yaml includes: - dynamic-plugins.default.yaml # Add the Orchestrator plugins directly, and add any other plugins you want to install, including local ones. plugins: - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator:{{inherit}}' disabled: false - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend:{{inherit}}' disabled: false pluginConfig: orchestrator: dataIndexService: url: http://sonataflow:8899 - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator:{{inherit}}' disabled: false pluginConfig: orchestrator: dataIndexService: url: http://sonataflow:8899 - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets:{{inherit}}' disabled: false Reference reasoning: The existing orchestrator documentation describes enabling the same set of dynamic plugins while also requiring a BACKEND_SECRET secret to be provided via extraEnvs, and it shows dependency configuration for the orchestrator backend. Aligning this README with those documented requirements reduces the risk of users enabling plugins but ending up with a non-working Orchestrator runtime due to missing prerequisites.

📄 References redhat-developer/rhdh-operator/docs/orchestrator.md [69-101] redhat-developer/rhdh-operator/docs/orchestrator.md [26-28] redhat-developer/rhdh-operator/docs/orchestrator.md [42-45] redhat-developer/rhdh-operator/docs/orchestrator.md [23-25] redhat-developer/rhdh-operator/docs/orchestrator.md [150-163] redhat-developer/rhdh-operator/docs/orchestrator.md [16-22] redhat-developer/rhdh-operator/docs/orchestrator.md [63-65] redhat-developer/rhdh-operator/docs/orchestrator.md [66-68]

[rhdh-qodo-merge]

PR Type

Documentation

---

Description

• Document workaround for Orchestrator plugin configuration issue

• Replace includes directive with direct plugin definitions in override file

• Add warning about known issue RHDHBUGS-2779 preventing Orchestrator startup

• Provide complete example configuration with all required orchestrator plugins

---

File Walkthrough

Relevant files

Documentation

README.md Document orchestrator plugin configuration workaround        orchestrator/README.md Clarified plugin configuration approach by replacing includes directive with direct plugin definitions Added complete example showing all four orchestrator plugins with proper configuration Included warning about known issue RHDHBUGS-2779 that prevents Orchestrator startup when using includes Improved documentation clarity with better explanation of setup requirements +25/-7

---

[rhdh-qodo-merge]

PR Code Suggestions ✨

No code suggestions found for the PR.