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: a4937722-db18-41a4-b2c5-020fcbdd24a5

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.}

[micheleRP]

not sure, but wondering if this upgrade info should come after failover pages?

[micheleRP]

PR Review (docs-team-standards)

Overall: Clean, well-written how-to that complies with docs-team-standards. One merge-order dependency to gate on; everything else is minor.

Critical (gate the merge)

1. This page depends on upgrade:deferred-finalization.adoc, which doesn't exist on beta yet — it's created by the stacked, still-open docs: defer upgrade finalization (DOC-2013) #1818. This page references it 6 times (intro link, #prerequisites, #roll-back-to-the-previous-release, #finalize-the-upgrade, #what-is-unavailable-while-unfinalized, and Suggested reading). If docs: upgrade guidance for shadow-linked clusters (DOC-2217) #1819 merges to beta before docs: defer upgrade finalization (DOC-2013) #1818, all six become broken xrefs and the build fails. Merge docs: defer upgrade finalization (DOC-2013) #1818 first (as the PR description already notes). Since the non-default base means there's no deploy preview, this can't be caught visually.

All other xrefs and the four anchors resolve correctly, with correct module prefixes and no relative paths.

Suggestions (minor)

1. Nav label "Upgrade Shadow-Linked Clusters" differs from the page H1 "Upgrade Clusters in a Shadowing Topology". Both are fine; consider aligning them (and the :description:, which says "shadow-linked clusters") for consistency.
2. No :page-topic-type: attribute. Optional in this repo since :page-categories: is present — skip if that's the house pattern for manage pages.

Accuracy note

The technical claims (features_auto_finalization, the rpk cluster upgrade command set, version floors v26.1.9 / v25.3.15 / v26.2, the FAILED_PRECONDITION gate behavior) were not independently verified against shipped source in this review. They read consistently and the PR description cites named SMEs and the TOI.

Impact on other files

• Consider a reciprocal "Suggested reading" link from upgrade:deferred-finalization.adoc back to this page. Optional.
• No stale xrefs elsewhere; setup.adoc already adds the back-link to the new page.

What works well

• Active voice, second person, present tense; no em dashes; [,bash] code fences; sentence-case section headings.
• Correct single-source hygiene: the setup.adoc TIP and enterprise-license bullet sit inside ifndef::env-cloud[], so the cloud build never renders a link to a page it doesn't have.
• Version references consistently v-prefixed.
• Strong "What to expect while unfinalized" and "Limitations" framing.

[micheleRP]

left some suggestions but looks good!