[release-2.1] docs(rhdh): add migration guide warnings, defaults inventory, and examples by rm3l · Pull Request #606 · redhat-developer/rhdh-chart

rm3l · 2026-10-09T15:37:19Z

manual cherrypick of #603

…mples (redhat-developer#603) * docs(rhdh): add migration guide warnings, defaults inventory, and examples Add practical guidance that was missing from the migration guide: - Image digest/tag interaction warning: custom tag + chart's default digest can produce an unresolvable image reference - Air-gapped plugin limitation: global.imageRegistry does not apply to dynamic plugin oci:// references - Chart-managed defaults inventory: which extra* entries (volumes, mounts, env vars, init containers) can be safely removed, split into unconditional vs conditional - Before/after YAML examples for ingress, extraEnvFrom, and orchestrator structural transformations Assisted-by: Claude * docs(rhdh): add Go template .Values.* reference guidance to migration guide Users migrating manually also need to update Go template expressions in string values (e.g., {{ .Values.global.host }} → {{ .Values.host }}). Add a table of common reference updates and a note about decomposed fields that cannot be find-and-replaced. Assisted-by: Claude * chore: bump chart version * docs(rhdh): add version scope note and clarify PG 15 support in migration guide - Add note that mapping tables reflect chart version 2.1 specifically - Clarify that PostgreSQL 15 is still supported, just no longer the default Assisted-by: Claude

sonarqubecloud · 2026-10-09T15:37:44Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

rhdh-qodo-merge · 2026-10-09T15:37:49Z

PR Summary by Qodo

Expand the RHDH 2.1 migration guide and bump chart version

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Warn about image digests, disconnected plugin images, and PostgreSQL defaults during migration.
• Inventory chart-managed values and add reference mappings and before-and-after YAML examples.
• Bump the chart to 3.4.6 and update the README install command.

Diagram

graph TD
  A["Old values"] --> B["Migration guide"] --> C["Migrated values"] --> D["Helm template"] --> E["Helm upgrade"] --> F["RHDH deployment"]

High-Level Assessment

Expanding the existing migration guide is appropriate: users need these warnings and examples while converting values manually. A conversion tool is planned separately and would not replace the need to explain behavioral differences.

Files changed (3) +160 / -5

Documentation (2) +159 / -4

README.mdAlign README version references with 3.4.6 +2/-2

Align README version references with 3.4.6
• Updates the chart badge and example install command to use version 3.4.6.
charts/rhdh/README.md

migration-from-backstage-chart.mdAdd migration warnings, defaults inventory, and worked examples +157/-2

Add migration warnings, defaults inventory, and worked examples

• Documents image tag–digest conflicts, disconnected plugin-image handling, chart-managed defaults, Go template reference updates, and PostgreSQL 15 support. Adds before-and-after values examples for environment sources, Ingress, and Orchestrator, and scopes the mappings to RHDH 2.1.

charts/rhdh/docs/migration-from-backstage-chart.md

Other (1) +1 / -1

Chart.yamlBump chart version to 3.4.6 +1/-1

Bump chart version to 3.4.6
• Increments the Helm chart version from 3.4.5 to 3.4.6 without changing the application version.
charts/rhdh/Chart.yaml

rhdh-qodo-merge · 2026-10-09T15:40:26Z

Code Review by Qodo

🐞 Bugs (6) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Orchestrator examples silently leave it disabled 🐞 Bug ≡ Correctness

Description

The new Orchestrator example omits orchestrator.enabled, whose chart default is false. A user
who copies the documented example therefore gets no SonataFlowPlatform resources because the
orchestrator template is gated on that setting.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[R487-489]
+orchestrator:
+  sonataflowPlatform:
+    externalDB:

Relevance

●●● Strong
The example omits a required activation setting, making the documented feature unusable when copied.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The chart defaults Orchestrator to disabled, and the SonataFlow template only renders when that flag
is true. The example starts directly with sonataflowPlatform, so it does not activate the feature
it documents.
charts/rhdh/values.yaml[708-710]
charts/rhdh/templates/orchestrator/sonataflows.yaml[1-1]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new Orchestrator migration example does not set the required `orchestrator.enabled` value, while the chart defaults it to false.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[487-489]
- charts/rhdh/values.yaml[708-710]
- charts/rhdh/templates/orchestrator/sonataflows.yaml[1-1]

## Recommended Fix
Add `enabled: true` under `orchestrator` in the new example, before `sonataflowPlatform`, so copying the example actually enables the documented resources.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

2. External database example targets the wrong database 🐞 Bug ≡ Correctness

Description

The new Orchestrator example sets externalDB.name to sonataflow, even though this field
identifies the existing administrative database used by the creation Job. The Job then connects to
that database and attempts to create the separate sonataflow database, so the copied example
cannot represent the documented external-database setup.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[R489-493]

+    externalDB:
+      existingSecret: my-db-secret
+      name: sonataflow
+      host: postgres.example.com
+      port: "5432"

Relevance

●●● Strong
The example contradicts documented database-creation semantics and would mislead users configuring
external Orchestrator databases.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The README explicitly distinguishes externalDB.name as the existing user-configured database from
the sonataflow database created by the Job. The template passes externalDB.name to psql -d and
then executes CREATE DATABASE sonataflow.

charts/rhdh/README.md[704-714]
charts/rhdh/templates/orchestrator/sonataflows.yaml[214-215]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Orchestrator example assigns `sonataflow` to `externalDB.name`, but that value must be the pre-existing database where the chart can issue the creation command.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[489-493]
- charts/rhdh/templates/orchestrator/sonataflows.yaml[214-215]
- charts/rhdh/README.md[704-714]

## Recommended Fix
Replace `name: sonataflow` with a clearly labeled existing administrative database such as `postgres`, and add a comment explaining that the chart creates the separate `sonataflow` database.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

3. Ingress examples render invalid paths 🐞 Bug ≡ Correctness

Description

The new Ingress example supplies path but omits pathType for both paths. The template
conditionally emits pathType, so copying this example produces a Kubernetes v1 Ingress path
without the required field.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[R375-378]

+        - path: /
+    - host: alt.example.com
+      paths:
+        - path: /rhdh

Relevance

●●● Strong
Recent reviewers accepted ingress documentation corrections addressing required host and path
structure.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Ingress template only emits pathType when it exists in the values, while the chart's own
default path includes ImplementationSpecific. Therefore the documented YAML renders paths without
the required property.

charts/rhdh/templates/ingress.yaml[31-39]
charts/rhdh/values.yaml[423-428]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new Ingress example omits `pathType` from both path entries, although the Kubernetes v1 Ingress API requires it.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[372-378]
- charts/rhdh/templates/ingress.yaml[31-39]
- charts/rhdh/values.yaml[423-428]

## Recommended Fix
Add `pathType: ImplementationSpecific` (or another supported path type appropriate to the example) under both `/` and `/rhdh` path entries.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

View high (1)

4. Air-gap guidance overstates pull-secret coverage 🐞 Bug ⛨ Security

Description

The air-gapped guidance says global.imagePullSecrets applies to all chart-managed images. The
chart-managed Orchestrator database-creation Job renders images without an imagePullSecrets field,
so the documented global setting cannot authenticate that Job against a private mirror.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[68]

+`global.imageRegistry` and `global.imagePullSecrets` apply to all container images managed by the chart (RHDH, PostgreSQL, catalog index, Intelligent Assistant, etc.), making them useful for mirroring to an internal registry. However, they do **not** apply to dynamic plugin references (`oci://` or `ref://` in `dynamicPlugins.plugins[].package`). Plugin OCI images must be mirrored separately and their references updated individually in the dynamic plugins configuration.

Relevance

●●● Strong
This is a concrete air-gap authentication gap, consistent with accepted reviews expanding
disconnected-environment guidance.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The main RHDH Pod renders merged pull secrets, but the Orchestrator Job still renders chart-managed
images without an imagePullSecrets stanza. A private mirrored registry therefore leaves that Job
unable to pull its image using only global.imagePullSecrets.
charts/rhdh/templates/_backstage-pod-template.tpl[17-20]
charts/rhdh/templates/orchestrator/sonataflows.yaml[108-126]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The migration guide claims global image pull secrets cover every chart-managed image, but the Orchestrator database-creation Job does not render image pull secrets.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[66-68]
- charts/rhdh/templates/orchestrator/sonataflows.yaml[108-126]
- charts/rhdh/templates/_backstage-pod-template.tpl[17-20]

## Recommended Fix
Either qualify the documentation to exclude workloads that do not consume the global setting, or update the affected Orchestrator Job and related operator-managed workload configuration to propagate the required pull secrets before claiming complete coverage.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

5. Migration guidance warns about nonexistent default digests 🐞 Bug ≡ Correctness

Description

The new image guidance claims the chart defaults every image to an explicit digest and combines a
custom tag with that digest. The referenced chart image defaults use tags with empty digests, so
following this warning would lead users to perform unnecessary overrides and misrepresent the actual
pull behavior.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[64]

+The downstream chart ships all container images with explicit digests by default (not tags). When both `tag` and `digest` are set, the chart renders the image reference as `tag@digest` (e.g., `registry.redhat.io/rhdh/rhdh-hub-rhel9:1.10@sha256:abc...`). This can fail to resolve at pull time if you set a custom `tag` while the chart's default `digest` still points to the original image (Helm merges the default digest into your values). When overriding with a custom tag, either set `digest: ""` to clear the default, or set `digest` to the correct digest for your tag. This applies to every `image.*` block: `image`, `catalogIndex.image`, `intelligentAssistant.core.image`, `postgresql.image`, etc.

Relevance

●●● Strong
The claim contradicts chart defaults; recent reviewers accepted corrections to image-related
migration documentation.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The chart's main, catalog-index, PostgreSQL, and Intelligent Assistant image defaults all set a tag
while leaving digest empty. Image rendering is delegated to the Bitnami common image helper rather
than constructing the documented tag@digest form in chart templates.
charts/rhdh/values.yaml[31-37]
charts/rhdh/values.yaml[191-196]
charts/rhdh/values.yaml[471-476]
charts/rhdh/values.yaml[600-605]
charts/rhdh/templates/_helpers.tpl[78-90]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The migration guide says all images have default digests and that setting a tag produces a `tag@digest` reference, but the chart defaults use empty digests for the referenced image blocks.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[62-64]
- charts/rhdh/values.yaml[31-37]
- charts/rhdh/values.yaml[191-196]
- charts/rhdh/values.yaml[471-476]
- charts/rhdh/values.yaml[600-605]

## Recommended Fix
Rewrite the warning to describe the actual helper behavior and current defaults. If digest-based overrides are supported, explain that users must explicitly set the correct digest for the selected image rather than claiming that the chart supplies a default digest for every image.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

6. The guide names the application version as chart version 🐞 Bug ⚙ Maintainability

Description

The new scope note calls 2.1 the redhat-developer-hub chart version. This repository identifies
3.4.6 as the chart version and 2.1.0 as the application version, so readers may select or apply the
migration guide against the wrong Helm chart release.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[9]

+> The mapping tables below reflect the `redhat-developer-hub` chart version **2.1**. Future chart versions may introduce additional changes.

Relevance

●●● Strong
Recent migration-guide reviews accepted corrections preventing version and migration guidance
confusion.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Chart metadata explicitly separates version: 3.4.6 from appVersion: 2.1.0, while the new note
describes 2.1 as the chart version.
charts/rhdh/Chart.yaml[3-5]
charts/rhdh/docs/migration-from-backstage-chart.md[1-1]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The migration guide's scope note labels 2.1 as the chart version, but the chart metadata labels 3.4.6 as the chart version and 2.1.0 as the application version.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[8-10]
- charts/rhdh/Chart.yaml[3-5]

## Recommended Fix
Change the note to say that the mapping tables reflect the RHDH application version 2.1, and state the applicable chart version separately if the guide is intended for chart version 3.4.x.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

Context sources

✅ Cross-repo context — repo relationships

Explored: repo: redhat-developer/rhdh (branch: release-2.1, sha: 62dff458) — View relationship

Explored: repo: redhat-developer/rhdh-operator (branch: release-2.1, sha: 7c71e18e) — View relationship

Review mode: Auto: 🚀 Fast: Localized documentation update with minor chart metadata changes and no runtime logic.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

rhdh-qodo-merge · 2026-10-09T15:40:38Z

Important

The /generate_labels command by Qodo is sunsetting on the 1st of October 2026 and will no longer be available. We recommend switching to the latest Qodo review capabilities. Learn more

rm3l requested a review from a team as a code owner October 9, 2026 15:37

openshift-ci Bot requested review from OpinionatedHeron and zdrapela October 9, 2026 15:37

rm3l merged commit f8453a7 into redhat-developer:release-2.1 Oct 9, 2026
5 of 6 checks passed

rm3l deleted the cherry-pick/release-2.1/docs/improve-migration-guide-warnings-and-examples branch October 9, 2026 15:39

rhdh-qodo-merge Bot added the documentation Improvements or additions to documentation label Oct 9, 2026

Navigation Menu

Repository navigation

[release-2.1] docs(rhdh): add migration guide warnings, defaults inventory, and examples - #606

[release-2.1] docs(rhdh): add migration guide warnings, defaults inventory, and examples#606
rm3l merged 1 commit into
redhat-developer:release-2.1from
rm3l:cherry-pick/release-2.1/docs/improve-migration-guide-warnings-and-examples

rm3l commented Oct 9, 2026

Uh oh!

sonarqubecloud Bot commented Oct 9, 2026

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

Uh oh!

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

rm3l commented Oct 9, 2026

Uh oh!

sonarqubecloud Bot commented Oct 9, 2026

Quality Gate passed

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

PR Summary by Qodo

Uh oh!

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

Code Review by Qodo

Uh oh!

rhdh-qodo-merge Bot commented Oct 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant