Add Stretch Cluster deployment guide for Kubernetes (26.2)#1681
Add Stretch Cluster deployment guide for Kubernetes (26.2)#1681JakeSCahill wants to merge 17 commits into
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 ⚙️ 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)
✨ 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}
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
Rewritten for the 26.2 GA line and validated end-to-end on three local kind clusters (Kubernetes 1.28, flat networking, operator 26.2.1-beta.3): bootstrap, operator install, Raft formation, StretchCluster and RedpandaBrokerPool deployment, User creation, and multicluster status. Key corrections against the operator source (main @ 8b034ee69): - Broker pools use the RedpandaBrokerPool CRD, not NodePool - tls, listeners, and rackAwareness are pool-level fields - fullnameOverride and multicluster.name must match the bootstrap cluster name (Secret names derive from it) - SASL is optional; SCRAM credentials are created with a User resource - Corrected bootstrap flag semantics; added --name-override and GitOps output modes - New prerequisite: Kubernetes 1.28+ (pod-index label) - New troubleshooting entry: bootstrap-user password mismatch recovery Sets operator-beta-version/operator-beta-tag antora.yml fallbacks to the current operator release so version attributes resolve at build time.
56a3d02 to
22f6759
Compare
JakeSCahill
changed the title
- High Availability partial (multi-region and multi-cluster sections): point to Stretch Clusters for a single cluster spanning Kubernetes clusters, and distinguish it from async multi-cluster replication - Shadowing overview: contrast async DR with a synchronous Stretch Cluster (self-managed builds only, inside the existing env-cloud guard) - Operator release notes: add v26.2.x section announcing Stretch Clusters and the rpk k8s multicluster plugin - Stretch Clusters page: link back to the HA overview and Shadowing
|
Did a brief review of the docs, it looks well updated. A couple of points of feeback.
|
- Add enterprise license note at the top (shared partial) - Add cross-cloud deployment prerequisites: site-to-site VPN mesh, non-overlapping CIDRs, sub-100ms latency, cross-cluster CNI, and double-encryption and egress-cost notes - Add 'Optimize for region failures' section: rack awareness wiring, leader pinning with default_leaders_preference, and automatic ghost broker ejection via continuous partition balancing Facts verified against redpanda-operator main (rack values come from the node label configured in rackAwareness.nodeAnnotation, default topology.kubernetes.io/zone; ghost ejection is native continuous balancing behavior, no operator involvement) and the cluster property reference.
|
Thanks for the review @david-yu. Addressed in 35d1c14: 1. Spaces in code blocks This is just the CSS in our code blocks. theres a gap for the toolbar you get on hover. 2. Cross-cloud prerequisites Added a "Cross-cloud deployments" subsection under the networking modes. Should the docs link your scaffold repo directly, or would you rather move it under 3. Leader pinning + ghost node ejection New "Optimize for region failures" section with three parts: rack awareness wiring on each RedpandaBrokerPool, leader pinning via 4. Enterprise license The shared enterprise-license note is now at the top of the page, right after the intro. 5. Node Pools page refactor: before refactoring we checked operator
Refactoring the Node Pools page to RedpandaBrokerPool today would document something that doesn't work against the current operator. If the unification/rename is landing before the 26.2 GA cut, point me at the PR or ticket and I'll refactor |
Validated live on kind: after automatic ghost ejection, a returning region's broker cannot rejoin with its old identity; wiping the PVC lets it join as a new broker and continuous balancing restores replicas.
New concept page compares deployment topologies (multi-AZ single cluster, Stretch Cluster, async multi-cluster with Shadowing) with a decision table, quick picks, and a Stretch-vs-Shadowing compatibility statement (shadow-target only in this release, verified against operator source). High Availability, Deploy Redpanda, and Deploy a Stretch Cluster now nest under it in the nav; URLs are unchanged so no aliases are needed. The HA partial's failure-mitigation table is now a tagged region transcluded by the chooser, and the partial gains a Kubernetes-only TIP to the chooser (Linux render unchanged). Also fixes two stale alias-path xrefs (k-decommission-brokers, shadowing overview) and adds a scope note to Deploy Redpanda.
The chooser's children are the selectable deployment options; High Availability is the concept page that informs the choice, serves both options, and is a common direct destination. It stays a sibling, linked from the chooser's next steps.
Flagged by the attribute-validation extension in the full-site build; sibling deploy pages use 'Deployment, High Availability'.
…ders a version
The prerequisite uses {operator-beta-version}; without the antora.yml
fallback it renders empty when the build-time version fetch is
unavailable. Same fallback values as PR #1681 (identical lines, so the
eventual merge is clean).
…ch page Matches the Gateway API page: readers should know the install steps pin a prerelease operator until the 26.2 GA ships. Remove this note at GA along with the version-attribute swap.
|
We should remove documentation for our NodePool since its just internally used for our BYOC cloud deployments, although we actively maintain it. A couple more things:
|
Makes the region-failure row of the deployment strategies table route directly to the Kubernetes implementation of geo-stretching. Renders on both HA pages and the deployment chooser via the shared table.
|
Thanks @david-yu. All four addressed. |
Comms for any self-managed adopters of the beta NodePool CRD: the CRD keeps working and stays maintained, the docs are removed because it is internal to Redpanda Cloud (BYOC); adopters should contact their account team. Pairs with the removal in #1799.
- Replace em-dash bullet in release notes with a prose sentence - Convert double-asterisk bold to house-style single asterisk - Transpose the Compare topologies table (7 columns to 4) so cells have room to render
rpk plugin install k8s does not resolve; the correct command is rpk k8s install, which during the beta must pin --plugin-version because no plugin release is marked latest.
|
Heads-up on merge order: the prerequisites now link to the new |
Generated with doc-tools from rpk v26.2.1-rc3 with the k8s plugin 26.2.1-beta.3 installed. Flags for the plugin-provided multicluster commands are injected from the plugin's cobra help because the rpk plugin protocol does not expose flag data. Includes a beta note on the install page: no plugin release is marked latest during the beta, so installs must pin --plugin-version.
|
Folded #1801 in: this PR now also adds the 9 |
…8s commands The rpk k8s multicluster reference pages now state that a multicluster deployment is the operator plane behind a Stretch Cluster, and prose mentions of the rpk k8s commands link to their reference pages.
|
Re-validated the full documented rpk workflow with the published plugin artifact (the original validation used a source-built binary because the pinned-install path wasn't known yet). Setup: |
The multicluster operator plane exists solely to run Stretch Clusters (verified in operator/cmd/multicluster/multicluster.go: the layered CR controllers reconcile resources whose clusterRef targets a StretchCluster). Reword the bootstrap, bundle, and status descriptions so users know what these commands are for.
|
Actually before you merge could you recommend using a 2/2/1 setup for clusters and RF=5 as described here: https://github.com/david-yu/redpanda-operator-stretch-cross-cloud-beta |
Per David Yu's review: five brokers distributed 2/2/1 across the three Kubernetes clusters with default_topic_replications: 5 keep a Raft majority through the loss of any one location, with the single-broker location acting as a tiebreaker.
|
Done in latest commit: the guide now recommends five brokers in a 2/2/1 layout with |
2 participants
Summary
Adds documentation for deploying Redpanda Stretch Clusters across multiple Kubernetes clusters, targeting the 26.2 line (base branch:
beta). Written as GA documentation for the Stretch Cluster GA release (ENG-1089, fix version Q2/26.2).Changes
modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adocmodules/ROOT/nav.adoc(after High Availability)antora.yml: setoperator-beta-version/operator-beta-tagfallbacks to the current operator release (26.2.1-beta.3)Cross-links into existing content:
deploy/partials/high-availability.adoc, rendered on the Kubernetes and Linux HA pages): multi-region section now points to Stretch Clusters, and the multi-cluster section distinguishes async replication between independent clusters from a synchronous Stretch Clusterifndef::env-cloudblock)get-started/release-notes/operator.adoc): new v26.2.x section announcing Stretch Clusters and therpk k8s multiclusterpluginFact-checking and validation
All resource specs, commands, and flags verified against
redpanda-operatormain (8b034ee69, release cutoperator/v26.2.1-beta.3), and the full procedure was executed end-to-end on three local kind clusters (flat networking, MetalLB, Kubernetes 1.28): bootstrap, operator install, Raft formation, StretchCluster + RedpandaBrokerPool deployment, andrpk k8s multicluster status.Notable corrections against the previous draft:
RedpandaBrokerPoolCRD, notNodePool(NodePoolbinds to the single-clusterRedpandaCR)tls,listeners, andrackAwarenessare pool-level fields, not StretchCluster fields; rack awareness also requiresrbac.createAdditionalControllerCRs=truefullnameOverrideandmulticluster.namemust match the bootstrap cluster name (Secret names derive from it)rpk k8s multicluster bootstrapflag semantics (--service-name,--name-override,--dns-override,--output=yamlfor GitOps)apps.kubernetes.io/pod-indexlabel; found during kind validation on 1.27, where brokers crash-loop)users.txtSecret only setssuperusers; SCRAM credentials are created with aUsercustom resource (new step added). Examples use SCRAM-SHA-256 because the operator's internal Kafka client hardcodes SHA-256 for its bootstrap user — with SHA-512 configured, User/Topic/ACL resources fail to sync (operator bug, reported separately)Release-day tasks (26.2 GA)
{operator-beta-version}/{operator-beta-tag}usages to the GA operator version attributes onceoperator/v26.2.1ships, and remove the "beta release of the operator" NOTE from the prerequisitescrds.experimentalrpk plugin install k8sresolves for end users on GA rpk (currently the plugin manifest exists but rpk 26.1.9 does not find it)Jira
Choose Your Deployment chooser (added after review)
This PR now also adds
deploy:redpanda/kubernetes/k-choose-deployment.adoc, a chooser page that becomes the nav parent of Deploy Redpanda and Deploy a Stretch Cluster (High Availability stays a sibling concept page). It compares the deployment topologies (multi-AZ single cluster / Stretch Cluster / async multi-cluster with Shadowing) with a decision table and quick picks, and transcludes the HA partial's failure-mitigation table via a new tagged region (both existing HA renders unchanged; the Linux page must stay identical). No URLs change, so no aliases are needed. Also fixes two stale alias-path xrefs and adds a scope note to Deploy Redpanda.Stretch × Shadowing compatibility statement (needs eng sanity-check) — verified against operator main (
8b034ee69): a StretchCluster resolves as the shadow (target) cluster of a ShadowLink (wired + unit-tested, no e2e), but there is no remote resolver for a StretchCluster source — it passes admission and fails at reconcile. The chooser states: shadow-target supported, source not supported, in this release. @david-yu could you confirm this matches the intended 26.2 support matrix? If target-side shouldn't be advertised yet, we'll soften the wording.