docs(rhdh): add migration guide warnings, defaults inventory, and examples

[rm3l]

Description of the change

Adds practical guidance to the 1.y→2.y migration guide that was missing and surfaced during work on the AI-assisted migration skill (RHIDP-17323):

• Image digest/tag interaction warning — when a user sets a custom tag, the chart's default digest is merged by Helm, producing an unresolvable tag@digest image reference. Documents the workaround (digest: "" or set the correct digest).
• Air-gapped / disconnected environments — global.imageRegistry and global.imagePullSecrets do not apply to dynamic plugin oci:// / ref:// references. Plugin images must be mirrored and referenced individually.
• Chart-managed defaults inventory — lists which extra* entries (volumes, volume mounts, env vars, init containers) can be safely removed after migration, split into unconditional (always chart-managed) vs conditional (keep only if customized).
• Before/after YAML examples for the three most complex structural transformations: ingress (host/path → hosts[] array), extraEnvFrom (name strings → secretRef/configMapRef), and orchestrator (flat fields → nested objects with image decomposition).

All additions are in the "Important behavioral changes" and "Values mapping reference" sections. No chart code or schema changes.

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

• RHIDP-17323

How to test changes / Special notes to the reviewer

Documentation-only change. Review the rendered markdown for accuracy and readability.

The content was derived from building the AI-assisted migration script and testing it against real customer values files — these were the gaps that caused confusion or migration failures during testing.

Checklist

• N/A — documentation-only change, no Chart version or schema changes.

Assisted-by: Claude

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

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]

PR Summary by Qodo

Clarify RHDH 1.y-to-2.y migration pitfalls and value mappings

📝 Documentation 🕐 20-40 Minutes

AI Description

• Warn about default image digests and the need to mirror dynamic plugins separately in disconnected
 environments.
• Identify chart-managed defaults that can be removed from migrated values.
• Add before-and-after YAML for environment sources, ingress, and orchestrator settings.

Diagram

graph TD
  A["1.y values"] --> B["Migration guide"] --> C["2.y values"] --> D(["RHDH chart"]) --> E["Managed images"]
  C --> F["Plugin references"]

Loading

High-Level Assessment

Adding warnings and collapsible examples beside the existing migration mappings is appropriate for a documentation-only change. A separate guide would make users switch between references while converting values.

Files changed (1) +138 / -0

Documentation (1) +138 / -0

migration-from-backstage-chart.mdAdd migration warnings, defaults inventory, and YAML examples +138/-0

Add migration warnings, defaults inventory, and YAML examples

• Explains how default digests interact with custom image tags and why disconnected deployments must mirror dynamic plugin references separately. Lists removable chart-managed entries and conditionally managed defaults, then illustrates the extraEnvFrom, ingress, and orchestrator value conversions with before-and-after YAML.

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

[rhdh-qodo-merge]

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]

/cherrypick release-2.1

[openshift-cherrypick-robot]

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

Details

In response to this:

/cherrypick release-2.1

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.

[sonarqubecloud]

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

[rm3l]

Merging - docs only.

[openshift-cherrypick-robot]

@rm3l: #603 failed to apply on top of branch "release-2.1":

Applying: docs(rhdh): add migration guide warnings, defaults inventory, and examples
Applying: docs(rhdh): add Go template .Values.* reference guidance to migration guide
Applying: chore: bump chart version
Using index info to reconstruct a base tree...
M	charts/rhdh/Chart.yaml
M	charts/rhdh/README.md
Falling back to patching base and 3-way merge...
Auto-merging charts/rhdh/Chart.yaml
CONFLICT (content): Merge conflict in charts/rhdh/Chart.yaml
Auto-merging charts/rhdh/README.md
CONFLICT (content): Merge conflict in charts/rhdh/README.md
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0003 chore: bump chart version

Details

In response to this:

/cherrypick release-2.1

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.