tidy instructions for shadowing

[paulohtb6]

Description

Resolves https://redpandadata.atlassian.net/browse/DOC-1915
Review deadline:

Page previews

Linux
Kubernetes

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	6c50797
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6967b72865c165000864e88d
😎 Deploy Preview	https://deploy-preview-1549--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.

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

📝 Walkthrough

Walkthrough

This pull request updates the Redpanda shadowing documentation to reflect corrected requirements and improved guidance. The primary change clarifies that only the shadow cluster (not both source and shadow clusters) requires the enable_shadow_linking cluster property. The documentation is restructured by moving cluster property prerequisites from the setup page into a shared partial for reuse. Additionally, Kubernetes shadow-linking documentation is expanded with detailed examples for both Operator and Helm deployment methods, including TLS/SASL configuration handling and concrete commands for shadow link creation and management. Changes span a shared prerequisites partial and two main documentation pages.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Shadow tasks #1467: Both PRs directly modify shadowing documentation including setup.adoc and the shadow-link-prerequisites partial.
• DOC-1667 Document Shadow Link in Cloud #1491: Both PRs modify setup and prerequisites content, with this PR moving cluster-property instructions into a shared partial while the related PR adds cloud-specific conditional notes to that same partial.
• Add Shadowing docs for Kubernetes deployments #1514: Both PRs edit the same shadowing pages and partials, directly updating shadow-linking prerequisites and setup guidance.

Suggested reviewers

• JakeSCahill
• micheleRP
• Feediver1

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	Changes to k-shadow-linking.adoc extend beyond the DOC-1915 scope by adding extensive TLS/SASL handling, concrete examples, and workflow restructuring not mentioned in the linked issue requirements.	Clarify whether the extensive k-shadow-linking.adoc updates (TLS examples, workflow restructuring) are part of DOC-1915 or a separate scope, and split if needed.
Title check	❓ Inconclusive	The title 'tidy instructions for shadowing' vaguely describes the changeset as cleaning up instructions, but lacks specificity about the core technical change—clarifying that only the shadow cluster requires enable_shadow_linking set to true.	Consider a more specific title like 'Clarify shadowing prerequisite: only shadow cluster requires enable_shadow_linking' or 'Update shadowing documentation to reflect single-cluster enable_shadow_linking requirement' to clearly convey the main technical change.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The code changes fully implement the requirement from DOC-1915: the shadow-link-prerequisites partial now specifies only the shadow cluster requires enable_shadow_linking, eliminating the previous requirement for both clusters.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description includes the required Jira ticket reference (DOC-1915), page previews for both modified pages, and uses the standard template structure with all expected sections.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @modules/manage/partials/shadowing/shadow-link-prerequisites.adoc:
- Line 7: The xref reference
xref:manage:cluster-maintenance/config-cluster.adoc[] is missing link text;
update the brackets to include descriptive text (for example
xref:manage:cluster-maintenance/config-cluster.adoc[Cluster configuration] or
similar) so the cross-reference renders with readable link text in the sentence
about Redpanda v25.3 default settings.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 298284e and 5af52e8.

📒 Files selected for processing (3)

• modules/manage/pages/disaster-recovery/shadowing/setup.adoc
• modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc
• modules/manage/partials/shadowing/shadow-link-prerequisites.adoc

💤 Files with no reviewable changes (1)

• modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: andrewstucki
Repo: redpanda-data/docs PR: 1514
File: modules/troubleshoot/partials/errors-and-solutions.adoc:618-632
Timestamp: 2025-12-12T16:18:35.857Z
Learning: When using the Redpanda Operator with ShadowLink CRDs, CA certificates for shadow linking should not be copied directly into pods using `kubectl cp` because they won't persist across pod restarts. Instead, CA certificates should be stored in Kubernetes Secrets and referenced in the ShadowLink's `staticConfiguration` block, or inlined directly in that configuration block.

Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.

📚 Learning: 2025-11-25T09:42:15.235Z

Learnt from: CR
Repo: redpanda-data/docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T09:42:15.235Z
Learning: Applies to docs-data/property-overrides.json : Always use full Antora resource IDs with module prefixes in xref links within property descriptions (e.g., `reference:properties/cluster-properties.adoc`, never `./cluster-properties.adoc`)

Applied to files:

• modules/manage/pages/disaster-recovery/shadowing/setup.adoc

📚 Learning: 2025-07-16T19:33:20.420Z

Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.

Applied to files:

• modules/manage/pages/disaster-recovery/shadowing/setup.adoc

📚 Learning: 2025-12-12T16:18:28.126Z

Learnt from: andrewstucki
Repo: redpanda-data/docs PR: 1514
File: modules/troubleshoot/partials/errors-and-solutions.adoc:618-632
Timestamp: 2025-12-12T16:18:28.126Z
Learning: In Redpanda ShadowLink CRD usage, do not copy CA certificates into pods via kubectl cp because they won't persist across pod restarts. Store CA certs in Kubernetes Secrets and reference them in the ShadowLink's staticConfiguration block (or inline the cert data in that block) to ensure persistence and proper secret management.

Applied to files:

• modules/manage/pages/disaster-recovery/shadowing/setup.adoc
• modules/manage/partials/shadowing/shadow-link-prerequisites.adoc

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Redirect rules - redpanda-docs-preview
• GitHub Check: Header rules - redpanda-docs-preview
• GitHub Check: Pages changed - redpanda-docs-preview

🔇 Additional comments (2)

modules/manage/partials/shadowing/shadow-link-prerequisites.adoc (1)

2-3: Requirement correctly updated to reflect shadow cluster only.

The updated requirement accurately reflects the clarification that only the shadow cluster needs enable_shadow_linking set to true, aligning with the PR objective from DOC-1915.

modules/manage/pages/disaster-recovery/shadowing/setup.adoc (1)

49-49: Good refactoring to use shared partial.

The include directive correctly references the shared prerequisites partial with the appropriate tag, improving maintainability by centralizing cluster property documentation.

[kbatuigas]

Request to double check conditional for Cloud docs

[kbatuigas]

I think this looks all right in Self-managed (including Kubernetes) but not really in Cloud? Unless I'm looking at the wrong preview. Could you please double check?

[paulohtb6]

missed one if for cloud. Should be fine now. Thanks for spotting that!