docs: upgrade guidance for shadow-linked clusters (DOC-2217)

[Feediver1]

Resolves https://redpandadata.atlassian.net/browse/DOC-2217

Adds upgrade guidance for shadow-linked clusters, including the bidirectional topology that motivated the ticket (Slack thread, May 2026; CORE-16390 is Backlogged, so documentation is the plan of record).

Stacked on #1818 (DOC-2013): this PR's base is the DOC-2013-deferred-finalization branch because the new page xrefs upgrade:deferred-finalization.adoc throughout. Merge #1818 first; GitHub will retarget this PR to beta automatically. (If #1818 is squash-merged, I'll merge beta into this branch to clear the ghost diff before review.)

Changes

• New page modules/manage/pages/disaster-recovery/shadowing/upgrade.adoc:
  • The general ordering rule: upgrade the shadow cluster before the source cluster, with the SME-confirmed rationale (an upgraded source can use topic property values the not-yet-upgraded shadow doesn't support, breaking topic metadata replication).
  • The bidirectional procedure: same starting version → features_auto_finalization false on both → roll cluster A, verify both link directions, roll cluster B, re-verify → soak → finalize both promptly together → restore auto-finalization → adopt new features only after both finalize.
  • What to expect while unfinalized (existing links keep replicating; role sync / SR API-mode sync configuration is gated with FAILED_PRECONDITION errors by design) and limitations (an unfinalized cluster blocks the next feature-release upgrade).
• Nav: entry after Monitor Shadowing.
• setup.adoc: a TIP in the license/cluster requirements pointing to the new page, placed inside the existing ifndef::env-cloud[] block so the cloud-docs consuming build is unaffected.

Sources (no invented facts)

• Gellért Peresztegi-Nagy's answers on DOC-2217 (2026-07-17): "finalize both clusters promptly together"; shadow-before-source ordering confirmed with rationale.
• The DOC-2217 Slack thread (Patrick Angeles' endorsed procedure outline; bidirectional = non-overlapping topic sets; Nicolae Vartolomei's risk scoping — danger comes from new-feature use before finalization).
• The unfinalized-upgrades TOI (gate error messages, ShadowLinkUnfinalizedUpgradeTest CI coverage of replication across unfinalized upgrade + rollback, one-series-back rule, async finalize).

Review notes

• The Kubernetes shadowing section (manage:kubernetes/shadowing/) has no parallel entry; the page covers Kubernetes via xrefs to k-rolling-upgrade.adoc. Can add a K8s-side pointer in a follow-up if wanted.
• Nicolae's property-sync sharp edges (Iceberg + bidirectional property sync, independent of upgrades) are deliberately not documented here — flagged on the ticket as a future troubleshooting candidate.

🤖 Generated with Claude Code

Preview pages

Netlify does not build deploy previews for PRs based on a non-default branch, so no preview exists while this PR is stacked on DOC-2013-deferred-finalization. Once #1818 merges and this PR retargets to beta, the deploy preview will build and links will be added here for:

• manage/disaster-recovery/shadowing/upgrade/ (new)
• manage/disaster-recovery/shadowing/setup/ (updated)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 55787c59-1684-435d-85d5-04c1a49d1c91

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-2217-shadowing-upgrade

---

_{Comment @coderabbitai help to get the list of available commands.}