Add Shadowing docs for Kubernetes deployments #1514
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for Kubernetes Shadow Link disaster recovery functionality. It introduces a new navigation section for Kubernetes shadowing management, updates release notes from version 25.2.x to 25.3.x, and creates multiple new documentation pages and modular content partials covering shadow link setup, monitoring, failover procedures, and troubleshooting. Environment-specific conditionals are used to differentiate Kubernetes-specific guidance from general cloud content. The Kubernetes compatibility matrix is also updated to reflect version 25.3.x support. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
modules/manage/examples/kubernetes/shadow-links.feature (1)
29-51: Indent the tag marker lines to match the embedded manifest indentation.
# tag::basic-shadowlink-example[]/# end::...[]are currently unindented while the rest of the YAML in the docstring is indented. To reduce risk of the harness treating the manifest string differently, align indentation with the snippet:-# tag::basic-shadowlink-example[] + # tag::basic-shadowlink-example[] ... -# end::basic-shadowlink-example[] + # end::basic-shadowlink-example[]
🧹 Nitpick comments (8)
modules/manage/partials/shadowing/replication-lag-guidelines.adoc (1)
1-3: Consider a small qualifier that these are topic-dependent examples (throughput/partitions/RPO).This helps prevent readers from treating the message counts as hard limits across workloads.
modules/manage/partials/shadowing/failover-behavior.adoc (1)
1-11: Content LGTM; consider promoting the split-brain note to an[IMPORTANT]block.That warning is easy to miss as an inline NOTE.
modules/manage/pages/disaster-recovery/shadowing/monitor.adoc (1)
52-53: Include section levels may break page structure.shadow-link-metrics.adocdefines== Metrics; when included mid-page, it can unexpectedly reset hierarchy (or create duplicate==peers). Consider making the partial start at===(or usingleveloffset) so the parent page controls heading depth.Also applies to: 69-70
modules/manage/partials/shadowing/shadow-link-metrics.adoc (1)
1-3: Avoid hardcoding==in a widely-included partial. This partial defines a top-level section; if it’s included from multiple parent pages, prefer===(or include it withleveloffset) to prevent heading collisions/odd TOC structure.modules/manage/pages/kubernetes/shadowing/k-monitor-shadowing.adoc (1)
169-170: Same partial heading-level concern for included Metrics section. Including a== Metricssection here may create unexpected TOC/structure; preferleveloffseton include or demote headings in the partial.modules/manage/pages/disaster-recovery/shadowing/failover.adoc (1)
21-24: Kubernetes note looks good; ensure naming is consistent (“Shadow Link” vs “ShadowLink” vs “shadow link”). This page mixes product feature terminology and CRD kind naming; consider standardizing (feature = “shadow link”, CRD kind =ShadowLink).modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc (1)
22-23: Convert the “verify command output examples” TODO into a tracked issue (and/or link it). This is an emergency runbook; inaccurate output blocks are especially risky.modules/troubleshoot/partials/errors-and-solutions.adoc (1)
658-666: Connectivity test command may not work in minimal containers.curl -v telnet://...often isn’t available / supported; consider switching to a more reliable check (for examplerpk cluster info -X brokers=...with appropriate TLS/SASL flags) or note prerequisites for the tooling inside the container.
📜 Review details
Configuration used: CodeRabbit 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.
📒 Files selected for processing (24)
modules/ROOT/nav.adoc(1 hunks)modules/get-started/pages/release-notes/helm-charts.adoc(1 hunks)modules/get-started/pages/release-notes/operator.adoc(1 hunks)modules/manage/examples/kubernetes/shadow-links.feature(2 hunks)modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc(4 hunks)modules/manage/pages/disaster-recovery/shadowing/failover.adoc(3 hunks)modules/manage/pages/disaster-recovery/shadowing/monitor.adoc(3 hunks)modules/manage/pages/disaster-recovery/shadowing/setup.adoc(1 hunks)modules/manage/pages/kubernetes/monitoring/k-monitor-redpanda.adoc(1 hunks)modules/manage/pages/kubernetes/shadowing/index.adoc(1 hunks)modules/manage/pages/kubernetes/shadowing/k-failover-runbook.adoc(1 hunks)modules/manage/pages/kubernetes/shadowing/k-monitor-shadowing.adoc(1 hunks)modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc(1 hunks)modules/manage/partials/shadowing/failover-behavior.adoc(1 hunks)modules/manage/partials/shadowing/failover-decision-examples.adoc(1 hunks)modules/manage/partials/shadowing/failover-next-steps.adoc(1 hunks)modules/manage/partials/shadowing/failover-states.adoc(1 hunks)modules/manage/partials/shadowing/replication-lag-guidelines.adoc(1 hunks)modules/manage/partials/shadowing/shadow-link-alerts.adoc(1 hunks)modules/manage/partials/shadowing/shadow-link-metrics.adoc(1 hunks)modules/manage/partials/shadowing/shadow-link-prerequisites.adoc(1 hunks)modules/shared/partials/emergency-shadowing-callout.adoc(1 hunks)modules/troubleshoot/partials/errors-and-solutions.adoc(1 hunks)modules/upgrade/pages/k-compatibility.adoc(2 hunks)
🧰 Additional context used
🧠 Learnings (4)
📚 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/kubernetes/monitoring/k-monitor-redpanda.adocmodules/manage/pages/disaster-recovery/shadowing/monitor.adocmodules/manage/partials/shadowing/replication-lag-guidelines.adoc
📚 Learning: 2025-07-14T19:28:43.296Z
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Applied to files:
modules/get-started/pages/release-notes/helm-charts.adocmodules/get-started/pages/release-notes/operator.adocmodules/upgrade/pages/k-compatibility.adoc
📚 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 : Prefix self-managed-only links with `self-managed-only:` in related_topics to handle documentation pages that only exist in self-managed deployments
Applied to files:
modules/manage/partials/shadowing/shadow-link-prerequisites.adoc
📚 Learning: 2025-08-25T21:00:26.626Z
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1334
File: modules/manage/partials/rbac-dp.adoc:93-98
Timestamp: 2025-08-25T21:00:26.626Z
Learning: In cloud documentation (env-cloud), Security is at the top level navigation, so ACL references should use `security:authorization/rbac/acl.adoc`. In self-managed documentation, Security is nested under Manage, so ACL references use `manage:security/authorization/acl.adoc`. The different xref paths in conditional blocks reflect these different navigation structures.
Applied to files:
modules/ROOT/nav.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 (17)
modules/manage/pages/disaster-recovery/shadowing/setup.adoc (1)
21-24: Good targeted Kubernetes callout; please verify the xref resolves in Antora build.The
ifndef::env-cloud[]gating is consistent, and the link is the right kind of “escape hatch” for K8s readers. Please confirmxref:manage:kubernetes/shadowing/k-shadow-linking.adoc[]resolves (no broken link / correct module).modules/get-started/pages/release-notes/operator.adoc (1)
13-25: Release note update is clear and well-linked to the new ShadowLink docs.modules/manage/partials/shadowing/shadow-link-prerequisites.adoc (1)
57-115: Looks good; please verify SCRAM mechanism token spelling per interface (SCRAM-SHA-512vsSCRAM_SHA_512).Helm values commonly use
SCRAM-SHA-512, while other examples in the docs useSCRAM_SHA_512. If both are correct in their respective contexts, consider a brief note to avoid reader copy/paste failures.modules/manage/partials/shadowing/failover-decision-examples.adoc (1)
1-13: Failover decision examples are clear and well-structured.The scenarios are practical and help operators distinguish cases requiring full failover from those that can be managed without it. The content is ready for inclusion in failover runbooks and documentation.
modules/manage/pages/kubernetes/shadowing/index.adoc (1)
1-16: Kubernetes shadowing index page is well-structured and appropriately positioned.The page correctly establishes context for Kubernetes-specific shadowing guidance, includes the enterprise license note, and references the general overview. The use of environment flags and reusable partials follows documentation best practices.
modules/manage/partials/shadowing/failover-next-steps.adoc (1)
1-17: Failover next steps are comprehensive and operationally sound.The post-failover guidance balances immediate recovery actions with longer-term process improvements. The inclusion of "fail forward" strategies and incident documentation is particularly valuable for DR maturity.
modules/shared/partials/emergency-shadowing-callout.adoc (1)
4-9: Verify both conditional runbook paths resolve correctly.Lines 4–9 use environment-based conditionals to branch between Kubernetes and disaster-recovery failover runbooks. Ensure both target files exist:
modules/manage/pages/kubernetes/shadowing/k-failover-runbook.adocmodules/manage/pages/disaster-recovery/shadowing/failover-runbook.adocmodules/ROOT/nav.adoc (1)
139-142: All three new Kubernetes shadowing pages referenced in lines 139–142 exist atmodules/manage/pages/kubernetes/shadowing/. No action needed.modules/get-started/pages/release-notes/helm-charts.adoc (1)
15-17: No action required. The v25.3.x version is properly reflected across release notes and compatibility documentation with appropriate notation conventions: 'v25.3.x' in release notes headers and git references, and '25.3.x' in the compatibility matrix table. Version alignment is consistent.modules/manage/pages/disaster-recovery/shadowing/monitor.adoc (1)
14-17: Verify the Kubernetes xref target + page title consistency. The note points toxref:manage:kubernetes/shadowing/k-monitor-shadowing.adoc[]—please confirm the page exists, is published, and the rendered link text is what you want (empty[]uses the target’s title).modules/manage/partials/shadowing/shadow-link-metrics.adoc (1)
6-37: Confirm metric types/labels match the canonical metrics reference. “Count” vs “Counter”/“counter” naming and the label sets should align with the actualpublic_metricsoutput; otherwise this becomes a trust-breaker for monitoring users.modules/manage/pages/kubernetes/shadowing/k-monitor-shadowing.adoc (1)
29-37: Examplekubectl get/describe shadowlinkoutput likely version-dependent—call that out. The columns/condition types (SYNCED,Synced) can differ based on CRD printer columns and operator version; consider adding a short note that output may vary and users should rely on thestatus.conditionsentries.Also applies to: 45-79
modules/manage/pages/disaster-recovery/shadowing/failover.adoc (1)
28-30: Please verify the Cloud support/version claim (25.3+ on BYOC/Dedicated). This will go stale quickly and needs to match the authoritative Cloud release/support source.modules/upgrade/pages/k-compatibility.adoc (1)
40-53: Verify the stated supported version ranges (Core/Operator/Helm, Helm CLI 3.12+, Kubernetes 1.30–1.33, Console v3/v2 mappings). These are high-churn and should match the tested/support policy for the release.Also applies to: 56-60, 113-120
modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc (1)
18-21: Good environment routing to Kubernetes runbook. This reduces ambiguity for K8s users and keeps the non-cloud path clean.modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc (2)
21-26: Please verify all version prerequisites (Core 25.3+, Operator/Chart 25.3.1+, Console v3.30+). These should match the actual release/support policy and will otherwise become stale quickly.
142-147: AlignpatternType/filterTypecasing and enums across Operator vs Helm examples. This page uses lowercase (literal,include) for the CRD but uppercase in the Helm/rpk config (and troubleshooting stresses uppercase). Please confirm what the CRD actually accepts (case-sensitive enums vs normalization) and adjust examples to be consistent.Also applies to: 278-287, 328-345
modules/manage/pages/kubernetes/monitoring/k-monitor-redpanda.adoc
Outdated
Show resolved
Hide resolved
andrewstucki
left a comment
andrewstucki
left a comment
There was a problem hiding this comment.
Some initial comments
andrewstucki
left a comment
andrewstucki
left a comment
There was a problem hiding this comment.
From the sounds of it, a number of my earlier feedback comments were oriented towards the operator whereas some of the troubleshooting stuff was for helm. Things generally look fine to me now.
|
Throughout prefer to use Shadowing instead of Shadow links. |
ShadowLink is the name of the CRD. I have updated some places like the nav. |
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-1533
Review deadline: December 15
Page previews
Checks