Add Stretch Clusters deployment documentation#1681
Open
JakeSCahill wants to merge 9 commits intomainfrom
Open
Conversation
Add comprehensive documentation for deploying Redpanda Stretch Clusters across multiple Kubernetes clusters. Includes prerequisites, networking mode selection guidance, deployment steps using rpk k8s multicluster bootstrap, and troubleshooting. Follows docs-team-standards with proper topic type, personas, and learning objectives. Uses Antora attributes for version-independent documentation. Resolves: DOC-1775 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis pull request adds documentation for deploying Redpanda Stretch Clusters on Kubernetes. The change includes a navigation update to the documentation structure and a new comprehensive guide page. The guide covers prerequisites (operator version, enterprise license, networking setup, TLS certificates), a selection guide for different networking options (flat, mesh, MCS), installation instructions for multicluster operators across clusters, deployment procedures for StretchCluster and NodePool resources, verification commands, and troubleshooting steps using diagnostic tools. The documentation is marked as beta and includes next-step references and additional reading resources. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
modules/ROOT/nav.adoc (1)
82-82: Prefer auto-title xref in nav entry.Use
xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]to keep nav text aligned with the page title automatically.Based on learnings: AsciiDoc linking should use
xref:...[]so the target document title is rendered automatically.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/ROOT/nav.adoc` at line 82, The nav entry currently hardcodes the link text using xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Deploy Stretch Clusters]; change it to use an auto-title xref by replacing the bracketed text with empty brackets—xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]—so the navigation displays the target document's title automatically (update the line referencing k-stretch-clusters.adoc accordingly).modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc (2)
533-537: Use empty-bracketxrefstyle instead of hard-coded link text.These links should prefer
xref:...[]so rendered text tracks target page titles automatically.Based on learnings: AsciiDoc linking should prefer
xref:section/target.adoc[]and avoid hard-coded link text in.adocfiles.Also applies to: 540-541
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc` around lines 533 - 537, Replace the hard-coded link text on the four xref entries in the k-stretch-clusters.adoc snippet so they use empty-bracket style (e.g., change xref:manage:kubernetes/k-rack-awareness.adoc[Configure rack awareness] to xref:manage:kubernetes/k-rack-awareness.adoc[]), ensuring rendered text tracks target page titles automatically; apply the same change to the other xref occurrences mentioned (the links currently labeled "Set up monitoring", "Configure leader pinning", and "Configure cluster balancing") so all xref:...[] use empty brackets.
118-153: Make per-cluster execution explicit for “on all clusters” steps.Lines 118-153 currently run against only the active kube-context unless the reader manually switches contexts. For multi-cluster setup, this is easy to miss.
Suggested doc tweak
-. Install cert-manager on all clusters if not already installed: +. Install cert-manager on all clusters if not already installed (repeat per context): ... -kubectl create namespace cert-manager +kubectl create namespace cert-manager --context=<cluster-1-context> +kubectl create namespace cert-manager --context=<cluster-2-context> +kubectl create namespace cert-manager --context=<cluster-3-context> ... -helm install cert-manager jetstack/cert-manager \ +helm install cert-manager jetstack/cert-manager \ + --kube-context <cluster-1-context> \ --namespace cert-manager \ --set crds.enabled=true🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc` around lines 118 - 153, The steps that say "on all clusters" currently run against the active kube-context only; update the doc text around the kubectl/helm commands (notably the kubectl create namespace cert-manager, helm install cert-manager, kubectl create namespace redpanda-system, and kubectl create secret generic redpanda-license) to explicitly instruct readers to execute them for each cluster by either switching kube-contexts or using per-command context flags (e.g., mention --context) and include a short example sentence showing the per-cluster workflow so it's clear these commands must be repeated for every target cluster.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc`:
- Around line 489-490: The JSONPath used in the kubectl command incorrectly
targets `.spec.clusterName` on the top-level object; update the kubectl
invocation that currently uses kubectl get nodepool -n redpanda -o
jsonpath='{.spec.clusterName}' to iterate items and use the path
`{.items[*].spec.clusterName}` so the command extracts clusterName from each
returned NodePool item.
---
Nitpick comments:
In `@modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc`:
- Around line 533-537: Replace the hard-coded link text on the four xref entries
in the k-stretch-clusters.adoc snippet so they use empty-bracket style (e.g.,
change xref:manage:kubernetes/k-rack-awareness.adoc[Configure rack awareness] to
xref:manage:kubernetes/k-rack-awareness.adoc[]), ensuring rendered text tracks
target page titles automatically; apply the same change to the other xref
occurrences mentioned (the links currently labeled "Set up monitoring",
"Configure leader pinning", and "Configure cluster balancing") so all xref:...[]
use empty brackets.
- Around line 118-153: The steps that say "on all clusters" currently run
against the active kube-context only; update the doc text around the
kubectl/helm commands (notably the kubectl create namespace cert-manager, helm
install cert-manager, kubectl create namespace redpanda-system, and kubectl
create secret generic redpanda-license) to explicitly instruct readers to
execute them for each cluster by either switching kube-contexts or using
per-command context flags (e.g., mention --context) and include a short example
sentence showing the per-cluster workflow so it's clear these commands must be
repeated for every target cluster.
In `@modules/ROOT/nav.adoc`:
- Line 82: The nav entry currently hardcodes the link text using
xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Deploy Stretch
Clusters]; change it to use an auto-title xref by replacing the bracketed text
with empty brackets—xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]—so
the navigation displays the target document's title automatically (update the
line referencing k-stretch-clusters.adoc accordingly).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e5ba29cf-72ed-49d4-92f3-befa4f14a3a5
📒 Files selected for processing (2)
modules/ROOT/nav.adocmodules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc
- Fix JSONPath to use .items[*].spec.clusterName for nodepool query - Use auto-title xref (empty brackets) in nav.adoc - Use auto-title xref for all internal links in Next Steps - Add explicit per-cluster context instructions for installation commands Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Change rpk k8s multicluster check → status The correct diagnostics command is `rpk k8s multicluster status`, not `check`. The `check` command doesn't exist in the operator codebase. Implementation: operator/cmd/rpk-k8s/k8s/multicluster/status.go Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Remove incorrect organization=redpanda requirement from TLS prerequisites (the bootstrap command uses "Redpanda" as default, and this detail is unnecessary for users since the command handles it automatically) - Update status command validation list to match actual implementation: pod health, TLS validity, Raft state, unique cluster names, peer consistency, and CA consistency Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Major updates based on the official multicluster operator lab guide: StretchCluster spec: - Change spec.clusterSpec.network.mode to spec.networking.crossClusterMode - Add tls, auth.sasl, storage, resources, enterprise, listeners sections - Add cluster config tuning for WAN latency (node_status_interval, raft_heartbeat_timeout_ms, replicate_append_timeout_ms, etc.) NodePool spec: - Change spec.clusterName to spec.clusterRef with group/kind/name - Add image section with repository and tag - Add services.perPod for Cilium global service annotations - Add podTemplate.spec.nodeSelector for topology awareness Bootstrap command: - Add --loadbalancer flag for automatic LoadBalancer Service provisioning - Add --service-name and --create-namespace flags - Add flags reference table - Remove manual kubeconfig merge step (bootstrap handles this) Authentication: - Add SASL credential Secret creation step before StretchCluster - Use SCRAM-SHA-512 mechanism Other improvements: - Consolidate to single 'redpanda' namespace for operator and workloads - Update license secret key to 'license.key' for consistency - Fix troubleshooting section to reference clusterRef instead of clusterName - Note that CRDs are installed via crds.experimental=true Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Style guide compliance improvements:
- Fix passive voice in opening paragraph ("This topic describes" -> direct)
- Replace weak verb "uses" with "includes" in component list
- Make list items parallel (all noun phrases describing components)
- Add cert-manager link in prerequisites section
- Remove future tense ("You'll use" -> "Use")
- Refine learning objectives to be more specific to procedures
- Move conditional phrase to sentence beginning for clarity
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The bootstrap command creates services named '<context>-multicluster-peer', not with a generic label. Updated the command to get services by their explicit name instead of using a label selector that may not exist. This matches the approach used in the official multicluster lab guide. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
JakeSCahill
commented
Apr 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds comprehensive documentation for deploying Redpanda Stretch Clusters across multiple Kubernetes clusters.
Changes
modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adocmodules/ROOT/nav.adoc(added entry after High Availability)Documentation includes
rpk k8s multicluster bootstraprpk k8s multicluster checkStandards compliance
{operator-beta-tag},{latest-redpanda-tag})Jira
Resolves: https://redpandadata.atlassian.net/browse/DOC-1775
🤖 Generated with Claude Code