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

[rm3l]

Description

This updates the Orchestrator README file with the workaround mentioned in https://redhat.atlassian.net/browse/RHDHBUGS-2779?focusedCommentId=16458458
This avoids user confusion on this.

Which issue(s) does this PR fix or relate to

ref RHDHBUGS-2779

PR acceptance criteria

• Tests updated and passing
• Documentation updated
• Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

Follow the instructions in the README file to start an Orchestrator-flavored instance of RHDH.

[rm3l]

/cherry-pick release-1.9

[openshift-cherrypick-robot]

@rm3l: once the present PR merges, I will cherry-pick it on top of release-1.9 in a new PR and assign it to you.

Details

In response to this:

/cherry-pick release-1.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[rhdh-qodo-merge]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 RHDHBUGS-2779 - Partially compliant Compliant requirements: Document that RHDH Local 1.9 Orchestrator profile fails to start due to duplicate dynamic plugin configuration when using includes to reference orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml. Provide a clear workaround that allows users to start RHDH Local with Orchestrator enabled (as it worked in 1.8). Ensure the documented steps are actionable and reduce user confusion. Non-compliant requirements: Requires further human verification: Validate the documented workaround by following the README steps in a fresh environment (RHDH image quay.io/rhdh-community/rhdh:1.9) to confirm the Orchestrator profile starts and the duplicate plugin error is avoided.

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

🔒 No security concerns identified

⚡ Recommended focus areas for review Link Consistency The README references the ticket as RHDHBUGS-2779 but links to a redhat.atlassian.net URL; confirm this is the intended canonical link for readers (and accessible to the target audience), or consider linking to the public issue URL to avoid dead/permissioned links. > **Warning:** Do **not** use the `includes` directive to reference `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml`. > Due to a [known issue (RHDHBUGS-2779)](https://redhat.atlassian.net/browse/RHDHBUGS-2779), using `includes` for the orchestrator > dynamic plugins file prevents the Orchestrator profile from starting correctly.

📚 Focus areas based on broader codebase context Missing Config The new README plugin example enables the orchestrator backend plugin but omits the backend dependencies (e.g., ref: sonataflow) and other required configuration notes (like ensuring a BACKEND_SECRET secret is present). This can leave users with a “starts but doesn’t work” setup even if the profile starts successfully. (Ref 6) - 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 shows the backend plugin enabled with an explicit dependencies entry pointing to sonataflow, and additionally calls out adding a BACKEND_SECRET and wiring it via extraEnvs. Aligning the README example with these documented requirements reduces the chance of misconfiguration when users copy/paste the snippet.

📄 References redhat-developer/rhdh-operator/docs/orchestrator.md [16-22] redhat-developer/rhdh-operator/docs/orchestrator.md [46-62] redhat-developer/rhdh-operator/docs/orchestrator.md [42-45] redhat-developer/rhdh-operator/docs/orchestrator.md [66-68] redhat-developer/rhdh-chart/charts/backstage/README.md [337-358] redhat-developer/rhdh-operator/docs/orchestrator.md [69-101] redhat-developer/rhdh-operator/docs/orchestrator.md [3-15] redhat-developer/rhdh-operator/docs/orchestrator.md [23-25]

[rhdh-qodo-merge]

PR Type

Documentation

---

Description

• Updated Orchestrator README with workaround for RHDHBUGS-2779 issue

• Changed from using includes directive to copying plugins directly

• Added complete plugin configuration examples for orchestrator plugins

• Added warning about known issue preventing Orchestrator profile startup

---

File Walkthrough

Relevant files

Documentation

README.md Document orchestrator plugin setup workaround                        orchestrator/README.md Replaced includes directive approach with direct plugin copying method Added complete YAML configuration for four orchestrator plugins with proper URLs Added warning box explaining the known issue (RHDHBUGS-2779) and why includes should not be used Clarified setup instructions to be more explicit about plugin configuration +25/-7

---

---

🔍 To retrieve JIRA tickets as context to your PR description, please register your organization.

[rhdh-qodo-merge]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	✅ Use a relative link for file reference Suggestion Impact: Updated the README to use a relative link to the dynamic-plugins.yaml file instead of a hardcoded GitHub URL (kept the line-range anchor). code diff: -Copy the [plugins](https://github.com/redhat-developer/rhdh-local/blob/main/orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) +Copy the [plugins](./configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) Replace the hardcoded GitHub link to the main branch with a relative link to ensure it points to the correct file version for the user's current checkout. orchestrator/README.md [7-8] -Copy the [plugins](https://github.com/redhat-developer/rhdh-local/blob/main/orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml#L5-L21) +Copy the [plugins](./configs/dynamic-plugins/dynamic-plugins.yaml) from `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml` directly into your override file. [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that a hardcoded link to the main branch can be misleading and proposes using a relative link, which is a best practice that ensures documentation accuracy across different code versions.	Medium
	Replace private link with public information Replace the internal Jira link with a public link or a self-contained explanation of the issue, as the current link is not accessible to the public. orchestrator/README.md [34-36] > **Warning:** Do **not** use the `includes` directive to reference `orchestrator/configs/dynamic-plugins/dynamic-plugins.yaml`. -> Due to a [known issue (RHDHBUGS-2779)](https://redhat.atlassian.net/browse/RHDHBUGS-2779), using `includes` for the orchestrator -> dynamic plugins file prevents the Orchestrator profile from starting correctly. +> Due to a known issue (RHDHBUGS-2779), using `includes` for the orchestrator dynamic plugins file prevents the Orchestrator profile from starting correctly. This is because the paths to `pluginConfig` are not correctly resolved when using `includes` from a different directory. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the Jira link is internal and not publicly accessible, which is a valid concern for public-facing documentation, thus improving its usability.	Low
Update

[rm3l]

Merging as this was already validated, as discussed on https://redhat-internal.slack.com/archives/C059YMMB664/p1773762159523889?thread_ts=1773732035.728609&cid=C059YMMB664

[openshift-cherrypick-robot]

@rm3l: new pull request created: #184

Details

In response to this:

/cherry-pick release-1.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.