[release-2.1] docs: add migration guide from `backstage` chart (1.y) to `rhdh` chart (2.y) [RHIDP-16514] by rm3l · Pull Request #570 · redhat-developer/rhdh-chart

rm3l · 2026-09-29T18:38:47Z

manual cherrypick of #516

…t (2.y) [RHIDP-16514] (redhat-developer#516) * docs: add migration guide from backstage chart (1.y) to rhdh chart (2.y) Add a values mapping reference under docs/ covering all path changes between the legacy backstage chart and the new redhat-developer-hub chart. Link to it from the README migration section and replace the WIP placeholder with actionable guidance. Ref: RHIDP-16514 * docs: improve migration guide wording and instructions - Use GitHub alert syntax for the important notice - Guide users to locate their existing values file first - Use helm upgrade --install to handle both existing and new releases Ref: RHIDP-16514 * docs: highlight image digest fields and global.imageRegistry in migration guide Ref: RHIDP-16514 * fix: default nameOverride to developer-hub for URL continuity Match the old backstage chart's nameOverride so that resource names (and OpenShift Route URLs) are preserved during migration. Ref: RHIDP-16514 * docs: note that nameOverride preserves resource names during migration Ref: RHIDP-16514 * docs: update migration guide for accuracy after upstream merge - Remove stale ragInit mappings (init container no longer exists) - Fix intelligentAssistant config paths (server removed, only stack/profile) - Add prerequisites section (Kubernetes 1.31+ / OpenShift 4.18+) - Document default-deny NetworkPolicy behavioral change - Add missing value mappings: pod scheduling, serviceAccount, extraAppConfig, extraEnvFrom - List new features with no old-chart equivalent (StatefulSet, HTTPRoute, PodDisruptionBudget, externalDatabase, OKP) * docs: expand migration guide with comprehensive value mappings - Add clarification note: guide covers changed, removed, or semantically different values only; unchanged fields carry over as-is - Add schema validation behavioral note (JSON Schema rejects stale keys) - Add chart-level overrides: nameOverride, fullnameOverride, commonLabels, commonAnnotations - Add image digest and imagePullSecrets mappings - Expand pod scheduling: revisionHistoryLimit, strategy, deploymentAnnotations, topologySpreadConstraints, hostAliases - Add podSecurityContext mapping - Add extraEnvVarsCM → extraEnvFrom mapping - Expand service section with all fields (type, port, nodePort, etc.) - Expand ingress section (className, annotations, path, tls restructuring) - Add autoscaling (HPA), PDB, and HTTPRoute mapping tables - Add network policy mapping (old toggle removed, now always-on) - Expand metrics with interval, labels, annotations - Add removed values section (installDir, containerPorts, lifecycleHooks, etc.) - Remove trivial identical-path entries to reduce bloat * chore(rhdh): bump chart version to 3.4.2 Ref: RHIDP-16514 * docs: fix migration guide inaccuracies found during review - Fix old path names: replicas (not replicaCount), automountServiceAccountToken (not automount) - Add missing mappings: serviceAccount.labels, extraDeploy, extraContainers - Move lifecycleHooks, priorityClassName, terminationGracePeriodSeconds from removed table to mapping table (now supported) - Clarify dropped config.yaml entry in Intelligent Assistant configMaps Ref: RHIDP-16514 * docs: clarify Intelligent Assistant configMaps migration note Ref: RHIDP-16514 * docs: add remaining missing and hardcoded values to migration guide - Add global.imageRegistry to Global parameters mapping - Add lightspeed sidecar.imagePullPolicy mapping - Add lightspeed ragVolume.* as removed - Add hardcoded lightspeed fields (sidecar.name, portName, containerPort, runtimeVolume.name, runtimeVolume.mountPath) - Add lightspeed secret.optional as removed - Add orchestrator dbCreationJob flat-to-nested field mappings Ref: RHIDP-16514 * docs: fix migration guide accuracy against upstream backstage chart - Restore priorityClassName, terminationGracePeriodSeconds, and lifecycleHooks as proper old-to-new mappings (they exist in the upstream backstage chart) - Add Notes column to Container image table for consistency - Fix incomplete helm template command - Unify _(managed by chart)_ to _(hardcoded)_ terminology - Reword extraPorts from "Use X instead" to "Moved to X" Ref: RHIDP-16514 * docs: clarify init container configurability in migration guide The install-dynamic-plugins init container is configurable via dynamicPlugins.initContainer.* — not fully hardcoded. Ref: RHIDP-16514 * docs: add statefulSetPVC guidance for StatefulSet workload Ref: RHIDP-16514 * run pre-commit hooks * run pre-commit hooks * docs: address Qodo review feedback on migration guide - Steer users to extraArgs instead of argsOverride to avoid suppressing system --config flags - Clarify that the new chart does not create a placeholder secret and link to secret.example.yaml - Soften schema validation language — stale top-level keys may pass silently - Add explicit ingress field renames (name→host, TLS entry shape) Ref: RHIDP-16514 * docs: address PR review feedback and improve migration guide - Add link to NetworkPolicies README section - Reframe external database as existing concept with new dedicated block - Add PostgreSQL 15→18 image change warning in mapping table - Remove duplicate extraPorts entry from removed values table - Fix global.imageRegistry: existed via Bitnami but was undocumented - Add namespace flag and pre-upgrade warnings to migration steps - Unwrap paragraph line breaks for readability * docs: fix Intelligent Assistant default description in migration guide Lightspeed was already enabled by default in the old chart, so the new chart's default hasn't changed — only the key name has. * docs: fix NetworkPolicies link anchor in migration guide

sonarqubecloud · 2026-09-29T18:39:11Z

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-09-29T18:39:20Z

PR Summary by Qodo

Document migration from the backstage chart to RHDH 2.y

📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Add migration steps and a values mapping reference for moving from the backstage chart to the RHDH
 chart.
• Explain upgrade prerequisites and behavioral changes that could affect existing deployments.
• Link the guide from both READMEs and bump the chart version to 3.4.2.

Diagram

graph TD
  A["Existing values"] --> B["Translate settings"] --> C{"Cluster ready?"} -- "Yes" --> D["Render manifests"] --> E["Upgrade release"] --> F["Verify deployment"]
  C -- "No" --> G["Upgrade cluster"] --> C

High-Level Assessment

The following are alternative approaches to this PR:

1. Automated values converter

➕ Could reduce manual translation errors across the many renamed and restructured values.
➖ Would need to handle arrays, removed settings, and behavior changes that cannot be converted mechanically.
➖ Would require implementation and testing beyond a documentation-focused release change.

Recommendation: Publish the manual guide now: it gives users a migration path and makes non-mechanical decisions explicit. An automated converter could follow, using the mapping reference as its specification.

Files changed (4) +381 / -7

Documentation (3) +380 / -6

README.mdLink the migration guide from the published README +4/-4

Link the migration guide from the published README

• Replaces the work-in-progress migration notice and fresh-install guidance with instructions to migrate values and upgrade the release in place. Updates the version badge and install example to 3.4.2.

charts/rhdh/README.md

README.md.gotmplKeep the README template's migration guidance in sync +2/-2

Keep the README template's migration guidance in sync
• Updates the generated README's source template to direct legacy-chart users to the new guide and describe an in-place upgrade with migrated values.
charts/rhdh/README.md.gotmpl

migration-from-backstage-chart.mdAdd the backstage-to-RHDH chart migration guide +374/-0

Add the backstage-to-RHDH chart migration guide

• Provides migration steps and an extensive old-to-new values mapping. Calls out cluster prerequisites, changed defaults, network policies, schema-validation limits, removed values, and settings requiring manual attention.

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

Other (1) +1 / -1

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

Bump chart version to 3.4.2
• Increments the chart package version from 3.4.1 to 3.4.2 without changing the application version.
charts/rhdh/Chart.yaml

rhdh-qodo-merge · 2026-09-29T18:51:39Z

Code Review by Qodo

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

1. Existing databases may start with PostgreSQL 18 🐞 Bug ≡ Correctness

Description

The guide tells users to retain the old PostgreSQL image by setting postgresql.image.tag, but the
version change is in postgresql.image.repository: both charts default the tag to latest. For a
release using the old defaults, retaining that tag still selects fedora/postgresql-18 against the
existing PostgreSQL 15 data directory.

Code

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

+   - **PostgreSQL image** defaults to version 18. If you have an existing data directory, keep the old image (`postgresql.image.tag`) until you plan a PostgreSQL major upgrade.

Relevance

●●● Strong
A closely matching accepted precedent requires explicitly warning about PostgreSQL 15-to-18
migration compatibility.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The old parent chart selects fedora/postgresql-15:latest; the new chart selects
fedora/postgresql-18:latest. Copying only the tag cannot retain the old image.
charts/backstage/values.yaml[416-422]
charts/rhdh/values.yaml[463-470]
charts/rhdh/docs/migration-from-backstage-chart.md[290-295]

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 warning identifies the image tag as the way to retain PostgreSQL 15, although the old and new images both use `latest` and have different repositories.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[21-24]
- charts/rhdh/docs/migration-from-backstage-chart.md[290-295]

## Recommended Fix
Tell users with an existing PostgreSQL 15 data directory to preserve the effective old image repository and tag, including `postgresql.image.repository: fedora/postgresql-15` for installations using the old defaults.

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

Dismiss ↗ | View ↗

2. Previously disabled assistants start running 🐞 Bug ≡ Correctness

Description

The migration steps say Intelligent Assistant remains enabled by default and tell users to disable
it only if they explicitly disabled the old feature. The old chart defaults
global.lightspeed.enabled to false, while the new chart defaults intelligentAssistant.enabled
to true, so releases with no old override acquire the assistant and its sidecar on upgrade.

Code

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

+   - **Intelligent Assistant** (formerly Lightspeed) remains enabled by default. If you had explicitly disabled it in your old chart, set `intelligentAssistant.enabled: false`.

Relevance

●●● Strong
The finding identifies a concrete default-behavior change that migration guidance must explicitly
preserve.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The two checked-in defaults establish the change that the migration instruction describes
incorrectly.
charts/backstage/values.yaml[56-65]
charts/rhdh/values.yaml[550-555]

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 old Lightspeed default is disabled, not enabled; the guide consequently misses users who relied on that default.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[21-23]

## Recommended Fix
State that the default changes from disabled to enabled, and instruct users who want to retain the old behavior to set `intelligentAssistant.enabled: false` even if their old values file contains no Lightspeed override.

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

Dismiss ↗ | View ↗

3. Custom assistant stack settings are lost 🐞 Bug ≡ Correctness

Description

The global.lightspeed.configMaps mapping says the separate config.yaml is no longer needed
without explaining where its customized settings go. When an installation supplied that old
ConfigMap, the new chart mounts only stack and profile configuration; the chart README says custom
Llama Stack settings must instead be moved into lightspeed-stack.yaml.

Code

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

+| `global.lightspeed.configMaps` | `intelligentAssistant.config.{stack,profile}.existingConfigMap` | Array of 3 configMaps replaced with 2 structured entries; the separate `config.yaml` is no longer needed because the llama-stack configuration is now inlined in `lightspeed-stack.yaml` |

Relevance

●●● Strong
Accepted precedent supports clarifying how old assistant configuration and ConfigMaps must migrate
to new destinations.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The old chart supports a distinct config.yaml ConfigMap; the new sidecar mounts only stack and
profile files, and its README explicitly gives the required destination for custom settings.
charts/backstage/values.yaml[82-101]
charts/rhdh/templates/_backstage-pod-template.tpl[427-457]
charts/rhdh/README.md[620-624]

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 mapping drops the old separate Llama Stack `config.yaml` without telling users how to preserve custom settings in it.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[339-339]

## Recommended Fix
Distinguish the unneeded default file from customized configurations, and instruct users to move custom Llama Stack settings into a `lightspeed-stack.yaml` ConfigMap referenced by `intelligentAssistant.config.stack.existingConfigMap`.

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

Dismiss ↗ | View ↗

4. Custom assistant app settings are ignored 🐞 Bug ≡ Correctness

Description

The instruction to carry unlisted fields over unchanged overlooks lightspeed: settings inside
upstream.backstage.appConfig; the mapping covers global.lightspeed.* but not this app-config
namespace. After migration, the new chart renders those settings into app config unchanged, while
its Intelligent Assistant plugins use intelligent-assistant: rather than lightspeed:.

Code

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

+> Fields not listed in the tables below keep the same path. Where a table shows a new path, use that. If a field you use is not mentioned at all, carry it over as-is.

Relevance

●●● Strong
Accepted precedents show reviewers correct migration omissions that lose nested or renamed
configuration.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Both charts render the supplied app-config tree, but the new chart documentation identifies a
different namespace for the replacement plugins; no template translates the old namespace.
charts/backstage/vendor/backstage/charts/backstage/templates/app-config-configmap.yaml[1-9]
charts/rhdh/templates/app-config-configmap.yaml[1-15]
charts/rhdh/README.md[618-622]

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 blanket carry-over rule leaves custom `appConfig.lightspeed` settings under a namespace the new assistant plugins do not use.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[8-9]
- charts/rhdh/docs/migration-from-backstage-chart.md[101-108]

## Recommended Fix
Add an explicit exception for custom Lightspeed app configuration: when migrating `upstream.backstage.appConfig`, rename its `lightspeed:` configuration namespace to `intelligent-assistant:` and review the settings for compatibility.

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

Dismiss ↗ | View ↗

View medium (1)

5. Custom assistant plugins fail to install 🔗 Cross-repo conflict ≡ Correctness

Description

The migration guide says to convert global.lightspeed.plugins from OCI references to ref://
entries, but the RHDH installer resolves ref:// only for plugins listed in an includes file.
Migrating a custom Intelligent Assistant plugin that is absent from those files will leave the
plugin unresolved.

Code

charts/rhdh/docs/migration-from-backstage-chart.md[321]
+| `global.lightspeed.plugins` | `intelligentAssistant.plugins` | Plugin format changed from OCI to `ref://` |

Relevance

●●● Strong
The migration mapping changes plugin syntax and should document prerequisites for resolving custom
references.
PR-#516

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The new mapping describes an unconditional format change, while the RHDH installer documentation
limits ref:// lookup to included plugins and documents OCI references separately. The chart passes
Assistant plugin entries into the generated configuration without adding matching include entries.
rhdh-chart -> rhdh
charts/rhdh/docs/migration-from-backstage-chart.md[319-322]
charts/rhdh/templates/dynamic-plugins-configmap.yaml[8-26]
External repo: redhat-developer/rhdh, docs/dynamic-plugins/installing-plugins.md [134-140]
External repo: redhat-developer/rhdh, docs/dynamic-plugins/installing-plugins.md [177-198]

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 presents `ref://` as a general replacement for OCI plugin references, although the RHDH installer requires a matching entry in `includes`.

## Fix Focus Areas
- charts/rhdh/docs/migration-from-backstage-chart.md[320-321]

## Recommended Fix
Explain that users should use `ref://` only when the target plugin is present in an included plugin list. For other compatible plugins, retain an explicit OCI reference or add the plugin to an included list before using `ref://`.

ⓘ 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-must-gather (sha: 4e4ce2fe) — View relationship

Explored: repo: redhat-developer/rhdh-adr (sha: 571bd0f0) — View relationship

Explored: repo: redhat-developer/rhdh (sha: 31979565) — View relationship

Review mode: ⚖️ Balanced: The PR is primarily documentation, but it changes the chart version and migration guidance for a high-impact Helm upgrade path, where mapping and compatibility errors could affect deployments.

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

rhdh-qodo-merge · 2026-09-29T18:51:49Z

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 review from a team as code owners September 29, 2026 18:38

openshift-ci Bot requested review from Fortune-Ndlovu and subhashkhileri September 29, 2026 18:38

rm3l added the lgtm label Sep 29, 2026

rhdh-qodo-merge Bot added the documentation Improvements or additions to documentation label Sep 29, 2026

openshift-merge-bot Bot merged commit 7fd2d70 into redhat-developer:release-2.1 Sep 29, 2026
8 checks passed

rm3l deleted the cherrypick/release-2.1/RHIDP-16514--create-1-y-to-2-y-migration-guide-and-tooling-for-rhdh-helm-chart-users branch September 29, 2026 19:14

Navigation Menu

Repository navigation

[release-2.1] docs: add migration guide from `backstage` chart (1.y) to `rhdh` chart (2.y) [RHIDP-16514] - #570

[release-2.1] docs: add migration guide from `backstage` chart (1.y) to `rhdh` chart (2.y) [RHIDP-16514]#570
openshift-merge-bot[bot] merged 1 commit into
redhat-developer:release-2.1from
rm3l:cherrypick/release-2.1/RHIDP-16514--create-1-y-to-2-y-migration-guide-and-tooling-for-rhdh-helm-chart-users

rm3l commented Sep 29, 2026

Uh oh!

sonarqubecloud Bot commented Sep 29, 2026

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

rm3l commented Sep 29, 2026

Uh oh!

sonarqubecloud Bot commented Sep 29, 2026

Quality Gate passed

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

PR Summary by Qodo

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

Code Review by Qodo

Uh oh!

rhdh-qodo-merge Bot commented Sep 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant