From 22f6759a4f736bfb83d5adf5c8bd7c866da0fc76 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 13 Jul 2026 13:02:13 +0100 Subject: [PATCH 1/6] docs: add Stretch Cluster deployment guide for Kubernetes (26.2) 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. --- antora.yml | 3 +- modules/ROOT/nav.adoc | 1 + .../kubernetes/k-stretch-clusters.adoc | 583 ++++++++++++++++++ 3 files changed, 586 insertions(+), 1 deletion(-) create mode 100644 modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc diff --git a/antora.yml b/antora.yml index 4e2c794239..e854317b0d 100644 --- a/antora.yml +++ b/antora.yml @@ -38,7 +38,8 @@ asciidoc: latest-console-tag: 'v3.3.1' latest-release-commit: 'ebee215fdb2b8004735c6f800e532564cdcc05e1' latest-operator-version: 'v2.3.8-24.3.6' - operator-beta-tag: '' + operator-beta-version: '26.2.1-beta.3' + operator-beta-tag: 'v26.2.1-beta.3' helm-beta-tag: '' latest-redpanda-helm-chart-version: '' redpanda-beta-version: '' diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 089097e22c..18e2ffa57f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -81,6 +81,7 @@ **** xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Deploy Redpanda] **** xref:deploy:redpanda/kubernetes/k-production-readiness.adoc[] **** xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] +**** xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] *** xref:deploy:redpanda/manual/index.adoc[Linux] **** xref:deploy:redpanda/manual/production/requirements.adoc[Hardware and Software Requirements] **** xref:deploy:redpanda/manual/production/index.adoc[Deployment Options] diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc new file mode 100644 index 0000000000..bd7c796632 --- /dev/null +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -0,0 +1,583 @@ += Deploy a Stretch Cluster on Kubernetes +:description: Deploy a Redpanda Stretch Cluster across multiple Kubernetes clusters for multi-region high availability. +:env-kubernetes: true +:page-categories: Deployment, Kubernetes, High Availability +:page-toclevels: 1 +:page-topic-type: how-to +:personas: platform_operator, platform_engineer +:learning-objective-1: Install multicluster operators with bootstrapped TLS certificates across Kubernetes clusters +:learning-objective-2: Deploy StretchCluster and RedpandaBrokerPool resources to form a single Redpanda cluster +:learning-objective-3: Diagnose and resolve common Stretch Cluster deployment issues + +Get high availability across regions or data centers by running a single logical Redpanda cluster, called a Stretch Cluster, across multiple Kubernetes clusters. A Stretch Cluster fails over automatically through Raft consensus and is managed as a single unit. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +A Stretch Cluster deployment includes: + +* **StretchCluster resource**: Cluster-wide configuration, including the Redpanda version, listeners, and networking mode. +* **RedpandaBrokerPool resources**: Groups of brokers in each Kubernetes cluster, with per-pool replica counts, resources, and storage. +* **Multicluster operators**: One Redpanda Operator in each Kubernetes cluster. The operators coordinate through Raft consensus to manage the Stretch Cluster as a single unit. +* **Cross-cluster networking**: Direct broker-to-broker communication across Kubernetes clusters for Raft replication. + +== Prerequisites + +Before deploying a Stretch Cluster, ensure you have: + +* **Redpanda Operator {operator-beta-version} or later** on each Kubernetes cluster, installed with experimental CRDs enabled. See <>. + +* **Redpanda Enterprise Edition license**: The multicluster operator requires a valid license to start. Contact your Redpanda account team or https://redpanda.com/try-redpanda[request a trial license]. + +* **rpk with the `k8s` plugin**: The xref:reference:rpk/index.adoc[rpk CLI] with the `k8s` plugin installed: ++ +[,bash] +---- +rpk plugin install k8s +---- + +* **At least three Kubernetes clusters, running Kubernetes 1.28 or later**: The operators form a Raft group that needs a quorum of `⌊n/2⌋ + 1` members to elect a leader. With three clusters, the deployment tolerates the loss of one cluster. With only two clusters, the loss of either cluster stops the operator control plane, so two-cluster deployments are not recommended. ++ +NOTE: Brokers derive their advertised addresses from the `apps.kubernetes.io/pod-index` label, which Kubernetes adds in version 1.28. On older versions, brokers fail to start with an `invalid host` error. + +* **Cross-cluster networking**: One of the networking modes described in <>. + +* **Network requirements**: +** Pod-to-pod connectivity between all clusters. +** Inter-cluster network latency under 50 ms for optimal performance. +** Sufficient bandwidth for cross-cluster replication traffic. + +* **Kubernetes API access**: Each operator must be able to reach the Kubernetes API servers of all peer clusters, and you need a kubeconfig with contexts for all participating clusters to run the bootstrap command. + +* **cert-manager**: https://cert-manager.io/docs/installation/[cert-manager^] installed on all clusters. The operator uses cert-manager to issue TLS certificates for the Redpanda listeners. + +NOTE: You do not need to create TLS certificates for inter-operator communication yourself. The `rpk k8s multicluster bootstrap` command generates an ECDSA P-256 certificate authority (CA) and per-operator certificates automatically. + +== Choose a networking mode + +Brokers in a Stretch Cluster replicate data and maintain Raft consensus across Kubernetes clusters, so every broker must be reachable from every other cluster. Set the mode in the StretchCluster's `spec.networking.crossClusterMode` field: + +[cols="1,2,2"] +|=== +|Mode |How it works |Requirements + +|`mesh` (default) +|Per-pod Services use selectors, and a service mesh such as Cilium Cluster Mesh or Istio mirrors the Service endpoints across clusters. +|Service mesh installed on all clusters with multi-cluster federation configured. + +|`flat` +|The operator renders per-pod Services headless, without selectors, and manages their endpoints with pod IPs directly. Brokers communicate over routable pod IPs. +|CNI configuration that routes pod IPs across clusters, non-overlapping pod CIDR ranges, and firewall rules that allow traffic on the Redpanda ports (9092, 9093, 9644, 33145). + +|`mcs` +|The operator exports per-pod Services through the Kubernetes https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api[Multi-Cluster Services (MCS) API^], and brokers advertise addresses in the `clusterset.local` DNS domain. +|An MCS API implementation installed on all clusters, such as GKE multi-cluster Services or Submariner. +|=== + +Choose `flat` for the best performance when you control the network infrastructure, `mesh` when you already run a service mesh with multi-cluster federation, or `mcs` for a Kubernetes-native approach on platforms that support the MCS API. + +== Install multicluster operators + +Install the Redpanda Operator in multicluster mode on each Kubernetes cluster. + +. Install cert-manager on each cluster, if it's not already installed: ++ +[,bash] +---- +helm repo add jetstack https://charts.jetstack.io +helm repo update + +for ctx in ; do + helm install cert-manager jetstack/cert-manager \ + --kube-context "$ctx" \ + --namespace cert-manager \ + --create-namespace \ + --set crds.enabled=true +done +---- ++ +Replace ``, ``, and `` with the kubeconfig context names of your clusters. To list your contexts, run `kubectl config get-contexts`. + +. Create a Secret containing your Enterprise Edition license on each cluster: ++ +[,bash] +---- +for ctx in ; do + kubectl create namespace redpanda --context "$ctx" --dry-run=client -o yaml \ + | kubectl apply --context "$ctx" -f - + + kubectl create secret generic redpanda-license \ + --namespace redpanda \ + --context "$ctx" \ + --from-file=license.key= +done +---- + +. Bootstrap TLS certificates and peer configuration: ++ +[,bash] +---- +rpk k8s multicluster bootstrap \ + --context \ + --context \ + --context \ + --namespace redpanda \ + --loadbalancer +---- ++ +This command: ++ +* Generates an ECDSA P-256 CA, valid for 10 years, and an individual certificate for each operator, valid for one year. +* Provisions a LoadBalancer Service named `-multicluster-peer` in each cluster for operator peer communication on port 9443, and includes the resolved LoadBalancer addresses in the certificate Subject Alternative Names (SANs). +* Creates the TLS and kubeconfig Secrets that the operators read at startup, in the given namespace on each cluster. ++ +When the command completes, it prints a `multicluster.peers` block with each cluster's name and peer address. Use these values in the Helm installation. ++ +NOTE: The bootstrap command uses your kubeconfig context names as the cluster names, which also become the prefixes of the generated Secrets and Services. To use different names, such as `us-east`, pass `--name-override =` for each cluster. ++ +.Bootstrap command flags +[%collapsible] +==== +[cols="1,3"] +|=== +|Flag |Description + +|`--context` +|Kubeconfig context of a participating cluster. Repeat for each cluster. + +|`--kubeconfig` +|Path to a kubeconfig file. If you omit `--context`, all contexts in the file are used. + +|`--namespace` +|Namespace for the generated Secrets and Services. Default: `redpanda`. + +|`--loadbalancer` +|Provision a LoadBalancer Service per cluster for peer communication and include its external address in the certificate SANs. Without this flag, use `--dns-override` to provide the peer addresses. + +|`--loadbalancer-timeout` +|How long to wait per cluster for a LoadBalancer address. Default: `10m`. + +|`--dns-override` +|Override or add a peer address for a cluster, in `context=address` format. Repeat for each override. + +|`--name-override` +|Override the cluster name for a context, in `context=name` format. Defaults to the context name. Repeat for each override. + +|`--create-namespace` +|Create the namespace if it doesn't exist. Default: `true`. + +|`--organization` +|Organization field for the generated certificates. Default: `Redpanda`. + +|`--output=yaml` +|Emit the generated resources as YAML instead of applying them, for GitOps workflows. Use with `--output-dir` to write one file per cluster, which is required when emitting TLS Secrets because each cluster's private key must not be applied to any other cluster. +|=== +==== + +. Get the addresses required for the Helm installation. ++ +The bootstrap command already printed the peer addresses. To retrieve them again later, read them from the LoadBalancer Services: ++ +[,bash] +---- +for ctx in ; do + kubectl get service "-multicluster-peer" \ + --namespace redpanda \ + --context "$ctx" \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}{.status.loadBalancer.ingress[0].hostname}{"\n"}' +done +---- ++ +You also need the Kubernetes API server address of each cluster: ++ +[,bash] +---- +kubectl cluster-info --context +---- + +. Install the Redpanda Operator with multicluster mode enabled on the first cluster: ++ +[,bash,subs="attributes+"] +---- +helm repo add redpanda https://charts.redpanda.com +helm repo update + +helm install redpanda/operator \ + --kube-context \ + --namespace redpanda \ + --version {operator-beta-version} \ + --set fullnameOverride= \ + --set crds.enabled=true \ + --set crds.experimental=true \ + --set multicluster.enabled=true \ + --set multicluster.name= \ + --set multicluster.apiServerExternalAddress= \ + --set-json 'multicluster.peers=[{"name":"","address":""},{"name":"","address":""},{"name":"","address":""}]' \ + --set enterprise.licenseSecretRef.name=redpanda-license \ + --set enterprise.licenseSecretRef.key=license.key +---- ++ +Replace the placeholders: ++ +-- +* ``: The cluster's name from the bootstrap output. This is the kubeconfig context name unless you passed `--name-override`. +* ``: The API server address from `kubectl cluster-info`. It must be reachable from the other clusters. +* ``: The peer addresses from the bootstrap output. +-- ++ +IMPORTANT: The `fullnameOverride` and `multicluster.name` values must match the cluster's name from the bootstrap output. The operator reads the Secrets that the bootstrap command created, and their names are derived from the cluster name. The `multicluster.peers` list must contain all clusters, including the one you're installing on, and must be identical in every installation. The peer addresses are the LoadBalancer addresses from the bootstrap command, not the API server addresses. + +. Repeat the installation for the other clusters, changing only the release name, `--kube-context`, `fullnameOverride`, `multicluster.name`, and `multicluster.apiServerExternalAddress`. + +. Verify that the operators are running: ++ +[,bash] +---- +for ctx in ; do + kubectl get pods --namespace redpanda --context "$ctx" +done +---- ++ +Each operator Pod shows `1/1` in the `READY` column after the operators form a Raft group. If a Pod does not become ready, see <>. + +== Create the StretchCluster and broker pools + +After the operators are running, deploy a StretchCluster resource and one RedpandaBrokerPool for each Kubernetes cluster. + +. (Recommended) Create a Secret containing SASL superuser credentials on each cluster: ++ +[,bash] +---- +ADMIN_PASSWORD=$(openssl rand -base64 24) +echo "Save this password: ${ADMIN_PASSWORD}" + +for ctx in ; do + kubectl create secret generic redpanda-users \ + --namespace redpanda \ + --context "$ctx" \ + --from-literal=users.txt="admin:${ADMIN_PASSWORD}:SCRAM-SHA-256" \ + --from-literal=password="${ADMIN_PASSWORD}" +done +---- ++ +The `users.txt` key defines the cluster's superusers in `username:password:mechanism` format, with one user per line. The `password` key holds the same password on its own, so that the User resource in a later step can reference it. + +. Create a StretchCluster resource. ++ +Save the following to `stretchcluster.yaml`. The spec must be identical on every cluster, so that the operators' consistency check passes. ++ +[,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: StretchCluster +metadata: + name: cluster + namespace: redpanda +spec: + networking: + crossClusterMode: mesh # <1> + auth: # <2> + sasl: + enabled: true + mechanism: SCRAM-SHA-256 + secretRef: redpanda-users + storage: + persistentVolume: + enabled: true + size: 100Gi + resources: + cpu: + cores: "4" + memory: + container: + max: 8Gi + enterprise: + licenseSecretRef: + name: redpanda-license + key: license.key + config: + cluster: + default_topic_replications: 3 + # Wait 10 min before relocating replicas off an unavailable broker + # to avoid cross-region rebalancing on brief network blips. + partition_autobalancing_node_availability_timeout_sec: 600 + # Increase the liveness probe interval to accommodate WAN latency. + node_status_interval: 1000 + # Increase Raft timeouts for WAN latency. + raft_heartbeat_timeout_ms: 5000 + replicate_append_timeout_ms: 5000 + # Cache health metadata longer to reduce cross-cluster API calls. + health_monitor_max_metadata_age: 60000 +---- +<1> `mesh` is the default. Set `flat` for direct pod routing or `mcs` for the Multi-Cluster Services API. See <>. +<2> Omit the `auth` block to deploy without SASL authentication. `secretRef` references the Secret created in the previous step. ++ +Apply the manifest to every cluster: ++ +[,bash] +---- +for ctx in ; do + kubectl apply -f stretchcluster.yaml --context "$ctx" +done +---- + +. Create one RedpandaBrokerPool for each Kubernetes cluster. ++ +Each RedpandaBrokerPool defines a group of brokers in one Kubernetes cluster and binds to the StretchCluster through `spec.clusterRef`. Save the following to `brokerpool-cluster1.yaml`: ++ +[,yaml,subs="attributes+"] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: RedpandaBrokerPool +metadata: + name: pool- + namespace: redpanda +spec: + clusterRef: # <1> + group: cluster.redpanda.com + kind: StretchCluster + name: cluster + replicas: 3 + image: # <2> + repository: docker.redpanda.com/redpandadata/redpanda + tag: {latest-redpanda-tag} + tls: # <3> + enabled: true + certs: + default: + caEnabled: true + services: + perPod: # <4> + local: + annotations: + service.cilium.io/global: "true" + remote: + annotations: + service.cilium.io/global: "true" +---- +<1> References the StretchCluster. The `group` must be the bare API group (`cluster.redpanda.com`), without a version suffix. +<2> The Redpanda image. Use the same image in every pool. +<3> TLS for the Redpanda listeners, issued through cert-manager. Use the same TLS configuration in every pool. +<4> Annotations for the per-pod Services. This example enables cross-cluster service discovery for Cilium Cluster Mesh (`mesh` mode). Adjust or omit the annotations for your networking mode. ++ +Apply each pool to its own cluster, changing `metadata.name` for each one: ++ +[,bash] +---- +kubectl apply -f brokerpool-cluster1.yaml --context +---- ++ +TIP: To spread partition replicas across failure domains within each Kubernetes cluster, set `spec.rackAwareness.enabled: true` on the pool. Rack awareness requires the operator Helm chart to be installed with `rbac.createAdditionalControllerCRs=true`. See xref:manage:kubernetes/k-rack-awareness.adoc[]. + +. Verify that the StretchCluster is ready and the pools are bound: ++ +[,bash] +---- +kubectl get stretchcluster --namespace redpanda --context +kubectl get redpandabrokerpool --namespace redpanda --context +---- ++ +The StretchCluster's `READY` column shows `True` when the cluster is fully operational. Each cluster creates a StatefulSet and Pods for its local pool. + +. If you enabled SASL, create the superuser's credentials with a User resource. ++ +The `users.txt` Secret defines which users are superusers, but does not create their login credentials. Save the following to `user-admin.yaml` and apply it to one cluster: ++ +[,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: User +metadata: + name: admin + namespace: redpanda +spec: + cluster: + clusterRef: + group: cluster.redpanda.com + kind: StretchCluster + name: cluster + authentication: + type: scram-sha-256 + password: + valueFrom: + secretKeyRef: + name: redpanda-users + key: password +---- ++ +[,bash] +---- +kubectl apply -f user-admin.yaml --context + +kubectl get user --namespace redpanda --context +---- ++ +The `SYNCED` column shows `True` when the user is created. For more details about the User resource, see xref:manage:kubernetes/security/authentication/k-user-controller.adoc[]. + +. After all brokers are running, verify that they form a single cluster: ++ +[,bash] +---- +kubectl exec --namespace redpanda --context -it -- \ + rpk cluster info -X user=admin -X pass= -X sasl.mechanism=SCRAM-SHA-256 +---- ++ +The output lists the brokers from all pools across all Kubernetes clusters. If you deployed without SASL, omit the `-X` flags. + +== Upgrade the operators + +Upgrade the multicluster operators one Kubernetes cluster at a time. The operator Raft group needs a quorum of `⌊n/2⌋ + 1` members, so upgrading two operators at once in a three-cluster deployment drops quorum and stalls reconciliation until the operators rejoin. + +. Before you start, verify that the Raft group is healthy on every cluster: ++ +[,bash] +---- +rpk k8s multicluster status \ + --context \ + --context \ + --context \ + --namespace redpanda +---- + +. Run `helm upgrade` on the first cluster, then wait for that cluster's operator Deployment to roll and for the Raft group to report healthy again. + +. Repeat for each remaining cluster, one at a time. + +The operators are not on the data path. While an operator restarts, the brokers continue to serve traffic; only reconciliation of new changes pauses. + +== Troubleshooting + +Run the diagnostic command to check the health of a multicluster deployment: + +[,bash] +---- +rpk k8s multicluster status \ + --context \ + --context \ + --context \ + --namespace redpanda +---- + +This command validates: + +* Operator Pod health and Deployment configuration +* TLS certificate validity and SANs +* Raft consensus state and leader agreement +* Unique cluster names across all peers +* Peer configuration consistency +* CA certificate consistency across clusters + +To collect a diagnostics bundle for Redpanda Support, run `rpk k8s multicluster bundle` with the same connection flags. + +=== Operators not forming a Raft group + +If operator Pods remain in the `0/1 READY` state and logs show `unreachable` peer messages: + +. Check the operator logs for TLS or peer connection errors: ++ +[,bash] +---- +kubectl logs --namespace redpanda --context -l app.kubernetes.io/name=operator --tail=100 +---- + +. Verify that the bootstrap-created Secrets exist on each cluster: ++ +[,bash] +---- +kubectl get secrets --namespace redpanda --context | grep multicluster +---- + +. Check the certificate contents and SANs: ++ +[,bash] +---- +kubectl get secret --namespace redpanda --context \ + -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout +---- ++ +The SANs must include the peer addresses configured in `multicluster.peers`. If the LoadBalancer addresses changed after bootstrap, rerun the bootstrap command to regenerate the certificates. + +. Verify network connectivity to the peer Services on port 9443 from inside each cluster. + +=== RedpandaBrokerPools not binding to the StretchCluster + +If RedpandaBrokerPool resources don't report `Bound`: + +. Check the StretchCluster's conditions for error messages: ++ +[,bash] +---- +kubectl get stretchcluster --namespace redpanda -o yaml +---- + +. Verify that each pool's `clusterRef` matches the StretchCluster's name: ++ +[,bash] +---- +kubectl get redpandabrokerpool --namespace redpanda \ + -o jsonpath='{range .items[*]}{.metadata.name}{": "}{.spec.clusterRef.name}{"\n"}{end}' +---- + +. Check the operator logs for role-based access control (RBAC) errors: ++ +[,bash] +---- +kubectl logs --namespace redpanda -l app.kubernetes.io/name=operator | grep -i "forbidden\|unauthorized" +---- + +=== Bootstrap user password mismatch + +If the StretchCluster doesn't deploy brokers and the operator logs show `bootstrap user password mismatch`, the operators created the internal `-bootstrap-user` Secret independently with different passwords. This can happen when the StretchCluster manifest is applied to all clusters at nearly the same time. + +Find the Raft leader with `rpk k8s multicluster status`, compare the Secret across clusters, then delete the copies that differ from the leader's cluster and let the operator recreate them: + +[,bash] +---- +for ctx in ; do + printf '%s: ' "$ctx" + kubectl get secret cluster-bootstrap-user --namespace redpanda --context "$ctx" \ + -o jsonpath='{.data.password}' | sha256sum +done + +kubectl delete secret cluster-bootstrap-user --namespace redpanda --context +---- + +=== Brokers cannot communicate across clusters + +If brokers in different Kubernetes clusters cannot reach each other: + +. Get a broker Pod IP from another cluster and test connectivity from the local cluster: ++ +[,bash] +---- +kubectl get pods --namespace redpanda --context -o wide + +kubectl run -it --rm debug --image=busybox --restart=Never -- \ + nc -zv 33145 +---- + +. Check for NetworkPolicies that block cross-cluster traffic: ++ +[,bash] +---- +kubectl get networkpolicy --namespace redpanda +---- + +. For `flat` mode, verify that routes to the remote pod CIDRs exist. For `mesh` mode, verify that the per-pod Services are mirrored to the remote clusters. For `mcs` mode, verify that `ServiceExport` and `ServiceImport` resources exist for the per-pod Services. + +. Review the broker logs for connection errors: ++ +[,bash] +---- +kubectl logs --namespace redpanda | grep -i "connection\|error" +---- + +== Next steps + +* xref:manage:kubernetes/k-rack-awareness.adoc[Enable rack awareness] to optimize replica placement across failure domains within each Kubernetes cluster. +* xref:manage:kubernetes/monitoring/k-monitor-redpanda.adoc[Set up monitoring] for your Stretch Cluster deployment. +* xref:develop:produce-data/leader-pinning.adoc[Configure leader pinning] to keep partition leaders in specific regions for latency optimization. +* xref:manage:cluster-maintenance/cluster-balancing.adoc[Configure cluster balancing] for automatic partition rebalancing across brokers. From 843d98422b4f26d9c7dc9030b5bc8027efde1289 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 13 Jul 2026 13:13:03 +0100 Subject: [PATCH 2/6] docs: cross-link Stretch Clusters from HA, DR, and release notes - 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 --- .../redpanda/kubernetes/k-stretch-clusters.adoc | 2 ++ modules/deploy/partials/high-availability.adoc | 4 ++++ .../get-started/pages/release-notes/operator.adoc | 12 ++++++++++++ .../pages/disaster-recovery/shadowing/overview.adoc | 2 +- 4 files changed, 19 insertions(+), 1 deletion(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index bd7c796632..5e83065661 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -11,6 +11,8 @@ Get high availability across regions or data centers by running a single logical Redpanda cluster, called a Stretch Cluster, across multiple Kubernetes clusters. A Stretch Cluster fails over automatically through Raft consensus and is managed as a single unit. +TIP: For an overview of all high-availability deployment patterns, see xref:deploy:redpanda/kubernetes/k-high-availability.adoc[]. For asynchronous disaster recovery between two independent clusters, see xref:manage:disaster-recovery/shadowing/overview.adoc[]. + After reading this page, you will be able to: * [ ] {learning-objective-1} diff --git a/modules/deploy/partials/high-availability.adoc b/modules/deploy/partials/high-availability.adoc index 3e0b843de6..e023b01634 100644 --- a/modules/deploy/partials/high-availability.adoc +++ b/modules/deploy/partials/high-availability.adoc @@ -114,6 +114,8 @@ A multi-region deployment is similar to a multi-AZ deployment, in that it needs * Configure xref:develop:produce-data/leader-pinning.adoc[Leader Pinning] to ensure that topic partition leaders are geographically closer to clients. This can help lower network costs and latency by routing produce requests to brokers located in specific AZs. * If your produce latency exceeds your requirements, you can configure producers to have `acks=1` instead of `acks=all`. This reduces latency by only waiting for the leader to acknowledge, rather than waiting for all brokers to respond. However, using this configuration can decrease message durability. If the partition leader goes offline, you may lose any messages that are acknowledged but not yet replicated. +TIP: If you run Redpanda on Kubernetes, you can deploy one Redpanda cluster across multiple Kubernetes clusters in different regions. See xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. + === Multi-cluster deployment In a multi-cluster deployment, each cluster is configured using one of the other HA deployments, along with standby clusters or xref:{remote-read-replicas}[Remote Read Replica] clusters in one or more remote locations. A standby cluster is a fully functional cluster that can handle producers and consumers. A remote read replica is a read-only cluster that can act as a backup for topics. To replicate data across clusters in a multi-cluster deployment, use one of the following options: @@ -124,6 +126,8 @@ In a multi-cluster deployment, each cluster is configured using one of the other Alternatively, you could dual-feed clusters in multiple regions. Dual feeding is the process of having producers connect to your cluster across multiple regions. However, this introduces additional complexity onto the producing application. It also requires consumers that have sufficient deduplication logic built in to handle offsets, since they won't be the same across each cluster. +NOTE: A multi-cluster deployment replicates data asynchronously between independent clusters, each with its own offsets. To run a single logical cluster whose brokers span multiple Kubernetes clusters, with synchronous replication and one set of offsets, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. + ifdef::env-kubernetes[] == HA features in Kubernetes diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index e6c7be8ddd..da35c929d5 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -10,6 +10,18 @@ See also: * xref:upgrade:k-rolling-upgrade.adoc[] +== Redpanda Operator v26.2.x + +link:https://github.com/redpanda-data/redpanda-operator/blob/release/v26.2.x/operator/CHANGELOG.md[Changelog^] + +=== Stretch Clusters + +The Redpanda Operator supports Stretch Clusters: a single logical Redpanda cluster distributed across multiple Kubernetes clusters for multi-region high availability. Operators in each Kubernetes cluster coordinate through Raft consensus, and the new StretchCluster and RedpandaBrokerPool custom resources define the cluster and its per-cluster broker groups. + +The release also adds the `rpk k8s multicluster` plugin, with commands to bootstrap TLS certificates and peer configuration (`bootstrap`), check deployment health (`status`), and collect diagnostics bundles (`bundle`). + +* xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] -- Deploy a Stretch Cluster across multiple Kubernetes clusters. + == Redpanda Operator v26.1.x link:https://github.com/redpanda-data/redpanda-operator/blob/release/v26.1.x/operator/CHANGELOG.md[Changelog^] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 66f6178920..abce0a949a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -44,7 +44,7 @@ Shadowing complements Redpanda's existing availability and recovery capabilities endif::[] ifndef::env-cloud[] -Shadowing complements Redpanda's existing availability and recovery capabilities. xref:deploy:redpanda/manual/high-availability.adoc[High availability] actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While xref:deploy:redpanda/manual/disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] provides point-in-time recovery from xref:manage:tiered-storage.adoc[Tiered Storage], Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. +Shadowing complements Redpanda's existing availability and recovery capabilities. xref:deploy:redpanda/manual/high-availability.adoc[High availability] actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While xref:deploy:redpanda/manual/disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] provides point-in-time recovery from xref:manage:tiered-storage.adoc[Tiered Storage], Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. If you run Redpanda on Kubernetes and need multi-region availability without a separate standby cluster, you can instead deploy a single cluster across multiple Kubernetes clusters with synchronous replication. See xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. endif::[] // TODO: insert diagram. Possibly with a .gif animation showing cluster Cluster A being written and cluster B being replicated with a data flow arrow and geo-separation. Diagram must show Icons or labels for topics, configurations, offsets, ACLs, schemas that are being copied From 35d1c14712dbe1ce64461dad995036e37b60cd50 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 09:02:30 +0100 Subject: [PATCH 3/6] docs: address review feedback on Stretch Clusters page - 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. --- .../kubernetes/k-stretch-clusters.adoc | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 5e83065661..e6fcfc2291 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -11,6 +11,11 @@ Get high availability across regions or data centers by running a single logical Redpanda cluster, called a Stretch Cluster, across multiple Kubernetes clusters. A Stretch Cluster fails over automatically through Raft consensus and is managed as a single unit. +[NOTE] +==== +include::shared:partial$enterprise-license.adoc[] +==== + TIP: For an overview of all high-availability deployment patterns, see xref:deploy:redpanda/kubernetes/k-high-availability.adoc[]. For asynchronous disaster recovery between two independent clusters, see xref:manage:disaster-recovery/shadowing/overview.adoc[]. After reading this page, you will be able to: @@ -81,6 +86,19 @@ Brokers in a Stretch Cluster replicate data and maintain Raft consensus across K Choose `flat` for the best performance when you control the network infrastructure, `mesh` when you already run a service mesh with multi-cluster federation, or `mcs` for a Kubernetes-native approach on platforms that support the MCS API. +=== Cross-cloud deployments + +You can stretch a cluster across Kubernetes clusters in different cloud providers, but you must first make the clouds' networks mutually routable. In addition to the general network requirements, cross-cloud deployments need: + +* **Site-to-site VPN connectivity between all clouds**: A full mesh of IPsec VPN tunnels between the provider networks, for example AWS VPN Gateway, Google Cloud HA VPN, and Azure VPN Gateway, with BGP or static routes advertising each cloud's CIDR ranges. Node IPs in every cloud must be routable from the others. +* **Non-overlapping CIDR ranges** for the VPC or VNet networks and for the pod networks in every cloud. +* **Pairwise latency under 100 ms** between all regions. Broker liveness checks fail at higher latencies, even with the WAN tuning shown in this page's StretchCluster example. +* **A CNI that supports cross-cluster networking**, such as Cilium with Cluster Mesh (`mesh` mode), installed in place of each cloud's default CNI. + +Avoid double encryption: if the VPN layer already encrypts all cross-cloud traffic, don't also enable CNI-level node encryption, such as WireGuard, on the same path. + +NOTE: Cross-cloud egress is billed at each provider's internet egress rate, which is typically several times the cost of same-cloud, cross-region traffic. Factor replication traffic into your cost planning. + == Install multicluster operators Install the Redpanda Operator in multicluster mode on each Kubernetes cluster. @@ -429,6 +447,61 @@ kubectl exec --namespace redpanda --context -it - + The output lists the brokers from all pools across all Kubernetes clusters. If you deployed without SASL, omit the `-X` flags. +== Optimize for region failures + +To keep a Stretch Cluster performing predictably through a region outage, enable rack awareness on every broker pool, pin partition leaders near your clients, and let Redpanda eject brokers that are permanently gone. + +=== Enable rack awareness on broker pools + +Rack awareness is the foundation for both leader pinning and safe replica placement. Set it on each RedpandaBrokerPool: + +[,yaml] +---- +spec: + rbac: + enabled: true # <1> + rackAwareness: + enabled: true + nodeAnnotation: topology.kubernetes.io/zone # <2> +---- +<1> Rack awareness requires per-pool RBAC, and the operator Helm chart must be installed with `rbac.createAdditionalControllerCRs=true`. +<2> The Kubernetes Node label whose value becomes each broker's rack ID. The default is `topology.kubernetes.io/zone`, which gives each availability zone its own rack. To treat each Kubernetes cluster or region as one rack, use a label whose value is shared by all nodes in that cluster. + +=== Pin partition leaders near your clients + +Without a leader preference, partition leaders can move to any region after a failure, including regions far from your producers. For example, when a broker fails and its replacement starts in a distant region, leaders can end up there. Pin leaders to the racks closest to your clients with the config_ref:default_leaders_preference,true,properties/cluster-properties[] cluster property in the StretchCluster spec: + +[,yaml] +---- +spec: + config: + cluster: + default_leaders_preference: "racks:," # <1> +---- +<1> One or more rack IDs, which are the values of the node label configured in `rackAwareness.nodeAnnotation`. With multiple racks, Redpanda balances leaders across them. + +Leaders fail over to other regions when the preferred racks are unavailable and move back automatically when they recover. For details, see xref:develop:produce-data/leader-pinning.adoc[]. + +=== Automatically eject ghost brokers + +When an entire region is lost, its brokers remain in the cluster as unreachable "ghost" brokers until they are decommissioned. With continuous partition balancing, Redpanda decommissions them automatically after the configured timeouts, so you don't have to clean up stale brokers manually after a regional outage: + +[,yaml] +---- +spec: + config: + cluster: + partition_autobalancing_mode: continuous # <1> + # Wait before moving partitions off an unavailable broker. + partition_autobalancing_node_availability_timeout_sec: 600 + # After this additional timeout, decommission the broker entirely. + partition_autobalancing_node_autodecommission_timeout_sec: 3600 # <2> +---- +<1> Automatic ejection applies only in `continuous` mode, which is an Enterprise feature. +<2> The total time before an unreachable broker is ejected is approximately the availability timeout plus the auto-decommission timeout. + +CAUTION: Keep these timeouts comfortably longer than any transient cross-region network disruption you expect. If they're too short, a brief WAN outage can trigger cross-region partition rebalancing or even decommission healthy brokers. + == Upgrade the operators Upgrade the multicluster operators one Kubernetes cluster at a time. The operator Raft group needs a quorum of `⌊n/2⌋ + 1` members, so upgrading two operators at once in a three-cluster deployment drops quorum and stalls reconciliation until the operators rejoin. From 74305471577f5a486507ea918b1ddadea93c3742 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 09:42:04 +0100 Subject: [PATCH 4/6] docs: add region-recovery troubleshooting for ejected brokers 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. --- .../redpanda/kubernetes/k-stretch-clusters.adoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index e6fcfc2291..b948c9e9f9 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -620,6 +620,20 @@ done kubectl delete secret cluster-bootstrap-user --namespace redpanda --context ---- +=== Broker crash-loops after its region recovers + +If a region comes back online after its broker was automatically decommissioned (see <>), the returning broker cannot rejoin with its old identity: the pod starts but never becomes ready, and its logs show that the broker was removed from the cluster. + +Delete the broker's PersistentVolumeClaim and Pod so it rejoins as a new broker with a fresh ID: + +[,bash] +---- +kubectl delete pvc --namespace redpanda --context --wait=false +kubectl delete pod --namespace redpanda --context +---- + +The broker joins with a new broker ID, and continuous balancing moves partition replicas back onto it. + === Brokers cannot communicate across clusters If brokers in different Kubernetes clusters cannot reach each other: From 872276df76b4224168fb18a228595a29bee6e2a2 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 10:21:53 +0100 Subject: [PATCH 5/6] docs: add Choose Your Deployment chooser and re-nest K8s deploy nav 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. --- modules/ROOT/nav.adoc | 7 +- .../kubernetes/k-choose-deployment.adoc | 77 +++++++++++++++++++ .../kubernetes/k-production-deployment.adoc | 2 +- .../kubernetes/k-stretch-clusters.adoc | 2 +- .../deploy/partials/high-availability.adoc | 6 ++ .../disaster-recovery/shadowing/overview.adoc | 2 +- .../kubernetes/k-decommission-brokers.adoc | 2 +- 7 files changed, 91 insertions(+), 7 deletions(-) create mode 100644 modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 18e2ffa57f..86bc3a7d45 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -78,10 +78,11 @@ **** xref:deploy:redpanda/kubernetes/k-production-workflow.adoc[Deployment Workflow] **** xref:deploy:redpanda/kubernetes/k-requirements.adoc[Requirements and Recommendations] **** xref:deploy:redpanda/kubernetes/k-tune-workers.adoc[Tune Worker Nodes] -**** xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Deploy Redpanda] +**** xref:deploy:redpanda/kubernetes/k-choose-deployment.adoc[Choose Your Deployment] +***** xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] +***** xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Deploy Redpanda] +***** xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Deploy a Stretch Cluster] **** xref:deploy:redpanda/kubernetes/k-production-readiness.adoc[] -**** xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] -**** xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] *** xref:deploy:redpanda/manual/index.adoc[Linux] **** xref:deploy:redpanda/manual/production/requirements.adoc[Hardware and Software Requirements] **** xref:deploy:redpanda/manual/production/index.adoc[Deployment Options] diff --git a/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc new file mode 100644 index 0000000000..e811bf2d80 --- /dev/null +++ b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc @@ -0,0 +1,77 @@ += Choose Your Deployment +:description: Compare Redpanda deployment topologies for Kubernetes and choose the one that matches the failures you must survive and your recovery objectives. +:env-kubernetes: true +:page-categories: Deployment, High Availability +:page-topic-type: concept +:personas: platform_operator, platform_engineer + +Before you deploy Redpanda for production, choose the cluster topology that matches the failures you must survive and your recovery objectives: how much data you can afford to lose (recovery point objective, or RPO) and how quickly you must recover (recovery time objective, or RTO). This page compares the available topologies and routes you to the right deployment guide. + +== What you're protecting against + +Each topology mitigates a different class of failure: + +include::deploy:partial$high-availability.adoc[tag=failure-mitigation] + +== Decision dimensions + +Weigh the options against these dimensions: + +* **Failure domain**: The largest unit whose loss you must survive: a broker, a rack, an availability zone (AZ), a region, or an entire Kubernetes cluster. +* **RPO**: Synchronous Raft replication within one cluster means zero data loss. Asynchronous replication between clusters means near-real-time copies with some replication lag. +* **Failover**: A single cluster fails over automatically through Raft leader election. Independent clusters require a runbook-driven failover, including redirecting clients. +* **Latency**: Synchronous replication across distant locations adds produce latency and requires tuning. Asynchronous replication has no distance ceiling. +* **Client semantics**: A single cluster keeps one set of offsets. Shadowing preserves offsets on an independent cluster, so consumers can resume after failover. +* **License and complexity**: Some topologies require an Enterprise license and more operational investment. + +== Compare topologies + +[cols="2,2,2,2,2,1,2"] +|=== +| Topology | Survives | Replication and RPO | Failover | Latency requirement | License | Deployment guide + +| Single cluster, multi-AZ +| Loss of one AZ (with three or more AZs) +| Synchronous (Raft), zero data loss +| Automatic +| Low inter-AZ latency +| Community +| xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[] with xref:manage:kubernetes/k-rack-awareness.adoc[rack awareness] + +| Stretch Cluster (one cluster across Kubernetes clusters) +| Loss of one region, data center, or Kubernetes cluster (with three or more) +| Synchronous (Raft), zero data loss, one set of offsets +| Automatic +| Low inter-cluster latency (under 50 ms recommended); requires WAN tuning +| Enterprise +| xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] + +| Independent clusters with asynchronous replication (Shadowing) +| Loss of an entire region or cluster; also isolates the replica from many data-corruption events +| Asynchronous, near real time, offset-preserving; RPO greater than zero +| Runbook-driven: fail over shadow topics, then redirect clients +| None; any distance +| Enterprise +| xref:manage:disaster-recovery/shadowing/overview.adoc[] +|=== + +For read-only offloading rather than disaster recovery, see xref:manage:kubernetes/k-remote-read-replicas.adoc[Remote Read Replicas]. + +== Quick picks + +* **You need zonal resilience with the lowest latency and cost**: Deploy a single cluster across three or more AZs with rack awareness. +* **You need zero data loss across regions and you run Kubernetes**: Deploy a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster]. +* **You need disaster recovery across any distance, or an isolated recovery copy**: Keep clusters independent and replicate with xref:manage:disaster-recovery/shadowing/overview.adoc[Shadowing]. +* **You need to serve remote consumers without a second writable cluster**: Use xref:manage:kubernetes/k-remote-read-replicas.adoc[Remote Read Replicas]. + +== Stretch Clusters and Shadowing + +Stretch Clusters and Shadowing solve different problems and can complement each other. A Stretch Cluster is one logical cluster with synchronous replication and a single set of offsets; Shadowing asynchronously replicates data and metadata between two independent clusters for disaster recovery, protecting against events that affect a whole cluster, including some it cannot survive synchronously. + +In this release, a Stretch Cluster can act as the shadow (target) cluster of a shadow link. Using a Stretch Cluster as the source cluster of a shadow link is not supported. + +== Next steps + +* xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability in Kubernetes] for the concepts behind these topologies, including replica placement and failure modes. +* xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Deploy Redpanda] or xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Deploy a Stretch Cluster] to get started. +* xref:deploy:redpanda/kubernetes/k-production-readiness.adoc[] to validate your deployment, whichever topology you choose. diff --git a/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc b/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc index 27faaef75b..6a1073bf24 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc @@ -6,7 +6,7 @@ :env-kubernetes: true :page-categories: Deployment, GitOps -This topic describes how to configure and deploy one or more Redpanda clusters and Redpanda Console in Kubernetes. +This topic describes how to configure and deploy one or more Redpanda clusters and Redpanda Console in Kubernetes. Each Redpanda cluster runs within a single Kubernetes cluster. For multi-region topologies and other deployment shapes, see xref:deploy:redpanda/kubernetes/k-choose-deployment.adoc[]. == Prerequisites diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index b948c9e9f9..3fca899dbc 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -16,7 +16,7 @@ Get high availability across regions or data centers by running a single logical include::shared:partial$enterprise-license.adoc[] ==== -TIP: For an overview of all high-availability deployment patterns, see xref:deploy:redpanda/kubernetes/k-high-availability.adoc[]. For asynchronous disaster recovery between two independent clusters, see xref:manage:disaster-recovery/shadowing/overview.adoc[]. +TIP: To compare this topology with the other deployment options, see xref:deploy:redpanda/kubernetes/k-choose-deployment.adoc[]. For asynchronous disaster recovery between two independent clusters, see xref:manage:disaster-recovery/shadowing/overview.adoc[]. After reading this page, you will be able to: diff --git a/modules/deploy/partials/high-availability.adoc b/modules/deploy/partials/high-availability.adoc index e023b01634..9ac31c8ede 100644 --- a/modules/deploy/partials/high-availability.adoc +++ b/modules/deploy/partials/high-availability.adoc @@ -20,6 +20,7 @@ endif::[] Consider the following Redpanda deployment strategies for the most common types of failures. +// tag::failure-mitigation[] |=== | Failure | Impact | Mitigation strategy @@ -47,6 +48,7 @@ Consider the following Redpanda deployment strategies for the most common types | Corrupt or unavailable data that also affects synchronous replicas | Offline backups |=== +// end::failure-mitigation[] ifndef::env-kubernetes[See also: xref:deploy:redpanda/manual/production/production-deployment.adoc[Deploy for Production]] @@ -54,6 +56,10 @@ ifndef::env-kubernetes[See also: xref:deploy:redpanda/manual/production/producti This section explains the trade-offs with different HA configurations. +ifdef::env-kubernetes[] +TIP: To compare these topologies side by side and go straight to a deployment guide, see xref:deploy:redpanda/kubernetes/k-choose-deployment.adoc[]. +endif::[] + * <> * <> * <> diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index abce0a949a..34726b088a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -44,7 +44,7 @@ Shadowing complements Redpanda's existing availability and recovery capabilities endif::[] ifndef::env-cloud[] -Shadowing complements Redpanda's existing availability and recovery capabilities. xref:deploy:redpanda/manual/high-availability.adoc[High availability] actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While xref:deploy:redpanda/manual/disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] provides point-in-time recovery from xref:manage:tiered-storage.adoc[Tiered Storage], Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. If you run Redpanda on Kubernetes and need multi-region availability without a separate standby cluster, you can instead deploy a single cluster across multiple Kubernetes clusters with synchronous replication. See xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. +Shadowing complements Redpanda's existing availability and recovery capabilities. xref:manage:high-availability.adoc[High availability] actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While xref:deploy:redpanda/manual/disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] provides point-in-time recovery from xref:manage:tiered-storage.adoc[Tiered Storage], Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. If you run Redpanda on Kubernetes and need multi-region availability without a separate standby cluster, you can instead deploy a single cluster across multiple Kubernetes clusters with synchronous replication. See xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. endif::[] // TODO: insert diagram. Possibly with a .gif animation showing cluster Cluster A being written and cluster B being replicated with a data flow arrow and geo-separation. Diagram must show Icons or labels for topics, configurations, offsets, ACLs, schemas that are being copied diff --git a/modules/manage/pages/kubernetes/k-decommission-brokers.adoc b/modules/manage/pages/kubernetes/k-decommission-brokers.adoc index 13914950c1..747c8e1cb2 100644 --- a/modules/manage/pages/kubernetes/k-decommission-brokers.adoc +++ b/modules/manage/pages/kubernetes/k-decommission-brokers.adoc @@ -90,7 +90,7 @@ ID HOST PORT RACK The output shows four racks (A/B/C/D), so you might want to have at least four brokers to use all racks. -Rack awareness is just one aspect of availability. Refer to xref:deploy:deployment-option/self-hosted/kubernetes/k-high-availability.adoc[High Availability] for more details on deploying Redpanda for high availability. +Rack awareness is just one aspect of availability. Refer to xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] for more details on deploying Redpanda for high availability. === Cost From 8edf6b9e64eef8286a5a1496c1db103c1c32189f Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 10:33:55 +0100 Subject: [PATCH 6/6] docs: keep High Availability as sibling of the deployment chooser 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. --- modules/ROOT/nav.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 86bc3a7d45..3e9ea5eea9 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -79,9 +79,9 @@ **** xref:deploy:redpanda/kubernetes/k-requirements.adoc[Requirements and Recommendations] **** xref:deploy:redpanda/kubernetes/k-tune-workers.adoc[Tune Worker Nodes] **** xref:deploy:redpanda/kubernetes/k-choose-deployment.adoc[Choose Your Deployment] -***** xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] ***** xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Deploy Redpanda] ***** xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Deploy a Stretch Cluster] +**** xref:deploy:redpanda/kubernetes/k-high-availability.adoc[High Availability] **** xref:deploy:redpanda/kubernetes/k-production-readiness.adoc[] *** xref:deploy:redpanda/manual/index.adoc[Linux] **** xref:deploy:redpanda/manual/production/requirements.adoc[Hardware and Software Requirements]