docs: fix misleading shadow linking troubleshooting check (DOC-2231)

[JakeSCahill]

The troubleshooting section on k-shadow-linking told users to verify enable_shadow_linking on both clusters, but only the shadow (target) cluster requires it — the prerequisites partial on the same page already says so. The mismatch misleads readers and LLM assistants using the Docs MCP treat it as a debugging gotcha even when irrelevant (DOC-2231).

Now the check targets the shadow cluster only, with a sentence explaining that the source cluster needs the property only when it also acts as the shadow cluster of another link (bi-directional topologies).

Beta counterpart PR follows. Fixes DOC-2231.

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	7c37bac
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a68cb0737ed8d00087ade91
😎 Deploy Preview	https://deploy-preview-1802--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

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 Plus

Run ID: 68de1f24-d314-4684-8d09-c1b20c2e8b64

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

📝 Walkthrough

Walkthrough

Updates Helm troubleshooting guidance for shadow linking. The documentation now states that enable_shadow_linking must be enabled on the shadow (target) cluster, while the source cluster generally does not require it unless it also functions as a shadow cluster in a bidirectional topology.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• redpanda-data/docs#1794: Updates related shadow-linking Helm and operator configuration guidance.

Suggested reviewers: david-yu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description lacks the required template sections, including the Jira link, review deadline, page previews, and checkboxes.	Rewrite the description using the repository template and add the Jira URL, review deadline, page preview link, and one checked item under Checks.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the doc fix for shadow linking troubleshooting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc-2231-shadow-troubleshooting

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Feediver1]

Review: fix misleading shadow linking troubleshooting check (DOC-2231)

Overview

One-file fix: the Kubernetes shadow-linking troubleshooting section told users to verify enable_shadow_linking on both clusters; it now checks only the shadow cluster, with a sentence explaining when the source cluster would also need the property (when it's itself a shadow in another link, as in bidirectional topologies).

Verified — the fix is factually right

• Consistent with the same page's prerequisites. The shared partial shadow-link-prerequisites.adoc says exactly what the fix now says: "The shadow cluster must have the enable_shadow_linking cluster property set to true" — shadow only. The troubleshooting section was the outlier, and this brings it in line.
• The Operator tab needs no matching fix — it checks operator-level things (the enable-shadowlinks deployment flag, the ShadowLink resource status) and never made the both-clusters claim. Only the Helm tab was wrong.
• No stragglers. The remaining "both clusters" mentions on the page are correct (Enterprise licenses on both; the link referencing both by name) — none concern this property.
• The added caveat about bidirectional topologies is logically sound: the property gates shadow-side functionality, so a source cluster needs it exactly when it also plays the shadow role on another link.

One suggestion

• "bi-directional" → "bidirectional". The beta shadowing-upgrade page (DOC-2217) consistently uses the unhyphenated form ("bidirectional topology", "Upgrade a bidirectional topology"). Since a beta counterpart of this fix follows — which will sit right alongside that content — matching the established spelling now avoids a terminology fork. Worth fixing in both this PR and the counterpart.

Risks

Minimal — a three-line docs correction that removes wrong guidance rather than adding new claims. The one process item is making sure the beta counterpart actually lands, since beta's copy of this page carries the same wrong instruction; the PR body already commits to that.

Verdict: correct, well-scoped, and it fixes the DOC-2231 complaint at its root (the misleading check was being surfaced verbatim by the Docs MCP). Good to merge with the one-word spelling tweak.

🤖 Generated with Claude Code

[Feediver1]

one minor suggestion/nit

[JakeSCahill]

Applied in 7c37bac: "bi-directional" is now "bidirectional", matching the DOC-2217 shadowing-upgrade spelling. Same fix applied to the beta twin #1803.

🤖 Generated with Claude Code