From 22f6759a4f736bfb83d5adf5c8bd7c866da0fc76 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 13 Jul 2026 13:02:13 +0100 Subject: [PATCH 01/25] 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 02/25] 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 03/25] 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 04/25] 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 05/25] 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 06/25] 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] From aa8004567521772f8424d261ac3b54816c9ce691 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 12:46:18 +0100 Subject: [PATCH 07/25] docs: remove invalid 'Kubernetes' page category from stretch page Flagged by the attribute-validation extension in the full-site build; sibling deploy pages use 'Deployment, High Availability'. --- .../deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc | 2 +- 1 file changed, 1 insertion(+), 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 3fca899dbc..af91992d07 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -1,7 +1,7 @@ = 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-categories: Deployment, High Availability :page-toclevels: 1 :page-topic-type: how-to :personas: platform_operator, platform_engineer From 127227fb8cf74678e5f6402113e1db83fd350413 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 14 Jul 2026 13:01:54 +0100 Subject: [PATCH 08/25] docs: note the pinned operator version is a beta release on the stretch 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. --- .../deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index af91992d07..dd175dbee2 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -36,6 +36,8 @@ A Stretch Cluster deployment includes: 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 <>. ++ +NOTE: During the 26.2 beta, this is a beta release of the operator. Beta releases are not recommended for production use. The installation steps on this page pin the beta chart version. * **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]. From 9121c593b3b8f068dad2b05a97153b206c63423c Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 15 Jul 2026 13:13:37 +0100 Subject: [PATCH 09/25] docs: link the Geo-stretch mitigation to the Stretch Clusters page 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. --- modules/deploy/partials/high-availability.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/deploy/partials/high-availability.adoc b/modules/deploy/partials/high-availability.adoc index 9ac31c8ede..12dd194ad1 100644 --- a/modules/deploy/partials/high-availability.adoc +++ b/modules/deploy/partials/high-availability.adoc @@ -38,7 +38,7 @@ Consider the following Redpanda deployment strategies for the most common types | Region failure | Loss of brokers/VMs hosted within that region, or loss of connectivity to them -| Geo-stretch (latency dependent) or replicated deployment +| Geo-stretch (latency dependent), such as a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster] on Kubernetes, or replicated deployment | Global, systemic outage (DNS failures, routing failures) | Complete outage for all systems and services impacting customers and staff From a62ad80dcca92a707f1721f003887773b418519a Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 15 Jul 2026 13:23:59 +0100 Subject: [PATCH 10/25] docs: note NodePool CRD documentation removal in release notes 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. --- modules/get-started/pages/release-notes/operator.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index da35c929d5..b28b5235f6 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -22,6 +22,10 @@ The release also adds the `rpk k8s multicluster` plugin, with commands to bootst * xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] -- Deploy a Stretch Cluster across multiple Kubernetes clusters. +=== NodePool CRD documentation removed + +The NodePool custom resource (beta in v26.1.x) is intended for internal use in Redpanda Cloud (BYOC) deployments and is no longer documented for self-managed deployments. The CRD remains available and actively maintained, and existing configurations continue to work. If you adopted the NodePool CRD in a self-managed cluster, contact your Redpanda account team for guidance. + == Redpanda Operator v26.1.x link:https://github.com/redpanda-data/redpanda-operator/blob/release/v26.1.x/operator/CHANGELOG.md[Changelog^] From bdeeabf8cb17ac6ac39f6b7aa45b19190526e516 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Wed, 15 Jul 2026 13:39:31 +0100 Subject: [PATCH 11/25] Apply suggestion from @JakeSCahill --- modules/get-started/pages/release-notes/operator.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index b28b5235f6..d306a5845d 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -24,7 +24,7 @@ The release also adds the `rpk k8s multicluster` plugin, with commands to bootst === NodePool CRD documentation removed -The NodePool custom resource (beta in v26.1.x) is intended for internal use in Redpanda Cloud (BYOC) deployments and is no longer documented for self-managed deployments. The CRD remains available and actively maintained, and existing configurations continue to work. If you adopted the NodePool CRD in a self-managed cluster, contact your Redpanda account team for guidance. +The NodePool custom resource (beta in v26.1.x) is intended for internal use in Redpanda Cloud (BYOC) deployments and is no longer documented for self-managed deployments. The CRD remains available and actively maintained, and existing configurations continue to work. == Redpanda Operator v26.1.x From 6d30516c6ed824252f93738aa43f8359238d0255 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 15 Jul 2026 17:22:34 +0100 Subject: [PATCH 12/25] docs: fix style-guide violations and squished topology table - 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 --- .../kubernetes/k-choose-deployment.adoc | 60 ++++++++++--------- .../kubernetes/k-stretch-clusters.adoc | 32 +++++----- .../pages/release-notes/operator.adoc | 2 +- 3 files changed, 50 insertions(+), 44 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc index e811bf2d80..44caed708f 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc @@ -17,41 +17,47 @@ include::deploy:partial$high-availability.adoc[tag=failure-mitigation] 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. +* *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"] +[cols="1h,2,2,2"] |=== -| Topology | Survives | Replication and RPO | Failover | Latency requirement | License | Deployment guide +| | Single cluster, multi-AZ | Stretch Cluster (one cluster across Kubernetes clusters) | Independent clusters with asynchronous replication (Shadowing) -| Single cluster, multi-AZ +| Survives | 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 + +| Replication and RPO +| Synchronous (Raft), zero data loss +| Synchronous (Raft), zero data loss, one set of offsets | Asynchronous, near real time, offset-preserving; RPO greater than zero + +| Failover +| Automatic +| Automatic | Runbook-driven: fail over shadow topics, then redirect clients + +| Latency requirement +| Low inter-AZ latency +| Low inter-cluster latency (under 50 ms recommended); requires WAN tuning | None; any distance + +| License +| Community +| Enterprise | Enterprise + +| Deployment guide +| xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[] with xref:manage:kubernetes/k-rack-awareness.adoc[rack awareness] +| xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[] | xref:manage:disaster-recovery/shadowing/overview.adoc[] |=== @@ -59,10 +65,10 @@ For read-only offloading rather than disaster recovery, see xref:manage:kubernet == 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]. +* *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 diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index dd175dbee2..28c39ffbc5 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -26,42 +26,42 @@ After reading this page, you will be able to: 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. +* *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 Operator {operator-beta-version} or later* on each Kubernetes cluster, installed with experimental CRDs enabled. See <>. + NOTE: During the 26.2 beta, this is a beta release of the operator. Beta releases are not recommended for production use. The installation steps on this page pin the beta chart version. -* **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]. +* *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: +* *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. +* *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 <>. +* *Cross-cluster networking*: One of the networking modes described in <>. -* **Network requirements**: +* *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. +* *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. +* *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. @@ -92,10 +92,10 @@ Choose `flat` for the best performance when you control the network infrastructu 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. +* *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. diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index d306a5845d..e0a0aa0b08 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -20,7 +20,7 @@ The Redpanda Operator supports Stretch Clusters: a single logical Redpanda clust 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. +For deployment steps, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. === NodePool CRD documentation removed From 2200b8551af6768004a8bd8471b847f987b1d66c Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 16 Jul 2026 12:06:10 +0100 Subject: [PATCH 13/25] docs: fix rpk k8s plugin install instructions for beta 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. --- .../pages/redpanda/kubernetes/k-stretch-clusters.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 28c39ffbc5..7dcac2ad07 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -41,12 +41,14 @@ NOTE: During the 26.2 beta, this is a beta release of the operator. Beta release * *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: +* *rpk with the `k8s` plugin*: The xref:reference:rpk/index.adoc[rpk CLI] version 26.2 or later, with the xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[`k8s` plugin] installed: + [,bash] ---- -rpk plugin install k8s +rpk k8s install --plugin-version {operator-beta-version} ---- ++ +NOTE: During the 26.2 beta, no plugin release is marked as latest, so running `rpk k8s install` without flags fails with `no latest Redpanda Kubernetes plugin release found`. Pin the version as shown. * *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. + From 2f74d21422908ee5cc43b520ae580a500ea2716e Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 16 Jul 2026 12:04:39 +0100 Subject: [PATCH 14/25] docs: add rpk k8s command reference (26.2) 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. --- modules/ROOT/nav.adoc | 9 + .../pages/rpk/rpk-k8s/rpk-k8s-install.adoc | 50 +++++ .../rpk-k8s-multicluster-bootstrap.adoc | 185 ++++++++++++++++++ .../rpk-k8s/rpk-k8s-multicluster-bundle.adoc | 95 +++++++++ .../rpk-k8s/rpk-k8s-multicluster-status.adoc | 79 ++++++++ .../rpk/rpk-k8s/rpk-k8s-multicluster.adoc | 50 +++++ .../pages/rpk/rpk-k8s/rpk-k8s-uninstall.adoc | 46 +++++ .../pages/rpk/rpk-k8s/rpk-k8s-upgrade.adoc | 41 ++++ .../pages/rpk/rpk-k8s/rpk-k8s-version.adoc | 33 ++++ .../reference/pages/rpk/rpk-k8s/rpk-k8s.adoc | 56 ++++++ 10 files changed, 644 insertions(+) create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-uninstall.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-upgrade.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s-version.adoc create mode 100644 modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 3e9ea5eea9..7e3ce02ca4 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -421,6 +421,15 @@ **** xref:reference:rpk/rpk-group/rpk-group-seek.adoc[] *** xref:reference:rpk/rpk-help.adoc[] *** xref:reference:rpk/rpk-iotune.adoc[] +*** xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[] +**** xref:reference:rpk/rpk-k8s/rpk-k8s-install.adoc[] +**** xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[] +***** xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc[] +***** xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc[] +***** xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc[] +**** xref:reference:rpk/rpk-k8s/rpk-k8s-uninstall.adoc[] +**** xref:reference:rpk/rpk-k8s/rpk-k8s-upgrade.adoc[] +**** xref:reference:rpk/rpk-k8s/rpk-k8s-version.adoc[] *** xref:reference:rpk/rpk-plugin/rpk-plugin.adoc[] **** xref:reference:rpk/rpk-plugin/rpk-plugin-list.adoc[] **** xref:reference:rpk/rpk-plugin/rpk-plugin-uninstall.adoc[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc new file mode 100644 index 0000000000..3a59efd658 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc @@ -0,0 +1,50 @@ += rpk k8s install +:description: Install the Redpanda Kubernetes plugin. This command installs the latest version by default. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Install the Redpanda Kubernetes plugin. + +This command installs the latest version by default. + +Alternatively, you may specify a version using the `--plugin-version` flag. + +You may force the installation using the `--force` flag. + +NOTE: During the 26.2 beta, no plugin release is marked as latest, so running `rpk k8s install` without flags fails with `no latest Redpanda Kubernetes plugin release found`. Pin the beta version instead: `rpk k8s install --plugin-version {operator-beta-version}`. + +== Usage + +[,bash] +---- +rpk k8s install [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--force |bool |Force install of the Redpanda Kubernetes plugin. +|--plugin-version |string |Plugin version to install (for example, 25.3.5). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc new file mode 100644 index 0000000000..991b817401 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc @@ -0,0 +1,185 @@ += rpk k8s multicluster bootstrap +:description: Bootstrap TLS certificates and kubeconfig secrets across multiple Kubernetes clusters for a Redpanda multicluster deployment. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Bootstrap TLS certificates and kubeconfig secrets across multiple +Kubernetes clusters for a Redpanda multicluster deployment. + +This command connects to each specified Kubernetes context, generates a shared +CA certificate, and distributes per-cluster TLS certificates and kubeconfig +secrets so that the multicluster operator can communicate across clusters. + +If `--kubeconfig` is provided, all contexts in the file are used automatically +and `--context` flags are not required. If both are provided, only the specified +contexts from the kubeconfig file are used. + +`--loadbalancer` provisions a standalone LoadBalancer Service on each cluster +before signing certificates, waits for the cloud provider to assign an +external address, and bakes that address into the cert SANs. This resolves +the deploy/redeploy cycle that otherwise forces a first helm install just +to learn each cluster's external IP/hostname. The resulting peer list is +printed on success for pasting into helm values. + +`--output=yaml` skips applying anything and writes manifests as YAML. No +cluster contact or kubeconfig is needed: cluster names are derived from +`--context` flags (LB mode) or `--dns-override` keys (bootstrap mode). + +When `--output-dir` is set, one file per cluster is written into the +directory as `.yaml`. This is required for the TLS bootstrap path +because each cluster's tls.key is per-cluster identity material that +must not be applied to other clusters. The LoadBalancer-only step has +no secrets and additionally allows streaming to stdout (split on '---' +with comment headers). +Use this for GitOps pipelines that commit manifests and apply them via +Argo, Flux, or similar. + +Two-step GitOps workflow: + +1. bootstrap `--output=yaml` `--loadbalancer` `--context` ... + Emits only LoadBalancer Service manifests. Apply them, wait for the + cloud provider to assign external addresses. + +2. bootstrap `--output=yaml` `--output-dir` `--dns-override` ctx=
... + Emits Namespace and TLS Secret manifests into `/.yaml` with + the known addresses baked into the cert SANs. + +When `--loadbalancer` is NOT set, `--dns-override` is required for every +cluster; cluster names are derived from the override keys. +ServiceAccount, SA token, and kubeconfig cache Secrets are not emitted +because the operator regenerates them at runtime. + +== Usage + +[,bash] +---- +rpk k8s multicluster bootstrap [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk k8s multicluster bootstrap`. + +Bootstrap all clusters from a kubeconfig file: + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --kubeconfig /path/to/kubeconfig \ + --namespace redpanda +---- + +Bootstrap specific contexts (uses default kubeconfig loading rules): + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --context cluster-a --context cluster-b --context cluster-c \ + --namespace redpanda +---- + +Override the TLS secret prefix when Helm release names differ from context names: + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --context cluster-a --context cluster-b --context cluster-c \ + --name-override cluster-a=redpanda-operator \ + --name-override cluster-b=redpanda-operator \ + --name-override cluster-c=redpanda-operator \ + --namespace redpanda +---- + +Override DNS names for TLS SANs on specific clusters: + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --context cluster-a --context cluster-b \ + --dns-override cluster-a=cluster-a.example.com \ + --dns-override cluster-b=cluster-b.example.com \ + --namespace redpanda +---- + +Provision LoadBalancer Services and use their addresses for certificate SANs: + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --kubeconfig /path/to/kubeconfig \ + --namespace redpanda \ + --loadbalancer +---- + +Bootstrap only TLS certificates: + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --kubeconfig /path/to/kubeconfig \ + --namespace redpanda \ + --tls --kubeconfigs=false +---- + +GitOps step 1, emit LoadBalancer Service manifests (no kubeconfig needed): + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --context cluster-a --context cluster-b \ + --namespace redpanda \ + --loadbalancer \ + --output=yaml > multicluster-services.yaml +---- + +GitOps step 2, emit Namespace and TLS Secret manifests (no kubeconfig needed): + +[,bash] +---- +rpk k8s multicluster bootstrap \ + --namespace redpanda \ + --dns-override cluster-a=cluster-a.example.com \ + --dns-override cluster-b=cluster-b.example.com \ + --output=yaml --output-dir ./multicluster-bootstrap +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--context |strings |Kubernetes contexts. Repeatable. If omitted with `--kubeconfig`, all contexts in the file are used. +|--create-namespace |bool |Create the namespace if it does not exist (default true). +|--dns-override |stringArray |DNS override for TLS SANs, in `context=address` format. Repeatable. +|--kubeconfig |string |Path to a kubeconfig file (all contexts in the file are used unless `--context` is also specified). +|--kubeconfigs |bool |Bootstrap kubeconfig secrets (default true). +|--loadbalancer |bool |Provision a standalone LoadBalancer Service per cluster and use its external address for TLS SANs. +|--loadbalancer-timeout |duration |Per-cluster timeout waiting for a LoadBalancer address (0 = default of 10m). +|--name-override |stringArray |Override the TLS secret prefix for a context, in `context=prefix` format. Defaults to the context name. Repeatable. +|--namespace |string |Namespace for operator resources (default `redpanda`). +|--organization |string |Organization name for generated TLS certificates (default "Redpanda"). +|--output |string |Output mode. Empty (the default) applies resources to clusters. `yaml` emits manifests for GitOps and makes no cluster calls. +|--output-dir |string |With `--output=yaml`, write one file per cluster (named `.yaml`) into this directory. Required when emitting TLS Secrets; per-cluster routing prevents leaking peer identity keys across the trust boundary. +|--service-name |string |Operator deployment label selector value (`app.kubernetes.io/name`) (default `operator`). +|--tls |bool |Bootstrap TLS certificates (default true). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc new file mode 100644 index 0000000000..483999ac67 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc @@ -0,0 +1,95 @@ += rpk k8s multicluster bundle +:description: pass:q[Collects environment data from each Kubernetes cluster running the Redpanda multicluster operator and packages it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves.] + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Collects environment data from each Kubernetes cluster running the +Redpanda multicluster operator and packages it into a ZIP file for support. +This is the operator-side counterpart to `rpk debug bundle`, which collects +data from the Redpanda brokers themselves. + +By default, only one Kubernetes context is required. The bundle command +discovers peer clusters from labelled cache Secrets stored by the operator's +raft-bootstrap flow on the starting cluster, so the tool stays useful when +one of the peer clusters is down. Pass multiple `--context` flags to bypass +discovery and diagnose exactly that set. + +== Usage + +[,bash] +---- +rpk k8s multicluster bundle [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk k8s multicluster bundle`. + +Use a single context and discover peers from the starting cluster: + +[,bash] +---- +rpk k8s multicluster bundle --kubeconfig /path/to/kubeconfig +---- + +Start from a specific cluster in the default kubeconfig: + +[,bash] +---- +rpk k8s multicluster bundle --context cluster-a +---- + +Bypass discovery and bundle the listed clusters directly: + +[,bash] +---- +rpk k8s multicluster bundle --context cluster-a --context cluster-b --context cluster-c +---- + +Write the bundle to a specific path: + +[,bash] +---- +rpk k8s multicluster bundle --context cluster-a -o /tmp/operator-bundle.zip +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--context |strings |Kubernetes contexts. Repeatable. If omitted with `--kubeconfig`, all contexts in the file are used. +|--include-private-keys |bool |Include TLS private keys and cached peer kubeconfigs in serialised Secrets. Off by default. +|--kubeconfig |string |Path to a kubeconfig file (all contexts in the file are used unless `--context` is also specified). +|--logs-size-limit |string |Per-container log byte cap (`human-readable`, for example, "5M", "10MiB", "1G"; "0" disables the cap) (default "5M"). +|--logs-tail-lines |int |Per-container log tail-line cap (0 disables the cap) (default 5000). +|--metrics-interval |duration |Interval between successive `/metrics` samples (for example, 10s, 1m). Must be > 0. (default 10s). +|--metrics-samples |int |Number of `/metrics` samples taken per cluster (>= 2). Lets investigators compute counter rates post-hoc. (default 2). +|--name-override |stringArray |Override the TLS secret prefix for a context, in `context=prefix` format. Defaults to the context name. Repeatable. +|--namespace |string |Namespace for operator resources (default `redpanda`). +|-o, --output |string |Output mode. Empty (the default) applies resources to clusters. `yaml` emits manifests for GitOps and makes no cluster calls. +|--service-name |string |Operator deployment label selector value (`app.kubernetes.io/name`) (default `operator`). +|--skip-logs |bool |Skip operator pod log collection. +|--skip-metrics |bool |Skip operator `/metrics` scrape. +|-v, --verbose |bool |Print per-step progress to stderr (use to diagnose slow runs / hangs). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc new file mode 100644 index 0000000000..a07d6725a9 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc @@ -0,0 +1,79 @@ += rpk k8s multicluster status +:description: Checks each cluster's operator pod health, raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Checks each cluster's operator pod health, raft consensus state, +TLS certificate validity, and cross-cluster consistency. + +Connects to each specified Kubernetes context, finds the multicluster operator +pod, port-forwards to its gRPC transport, and queries raft status. Also +inspects Deployment configuration and TLS secrets for correctness. + +== Usage + +[,bash] +---- +rpk k8s multicluster status [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk k8s multicluster status`. + +Check status across all clusters in a kubeconfig: + +[,bash] +---- +rpk k8s multicluster status --kubeconfig /path/to/kubeconfig +---- + +Check specific clusters: + +[,bash] +---- +rpk k8s multicluster status \ + --context cluster-a --context cluster-b --context cluster-c +---- + +Override the TLS secret prefix per context (when Helm release names differ from context names): + +[,bash] +---- +rpk k8s multicluster status \ + --context cluster-a --context cluster-b \ + --name-override cluster-a=redpanda-operator \ + --name-override cluster-b=rp-operator +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--context |strings |Kubernetes contexts. Repeatable. If omitted with `--kubeconfig`, all contexts in the file are used. +|--kubeconfig |string |Path to a kubeconfig file (all contexts in the file are used unless `--context` is also specified). +|--name-override |stringArray |Override the TLS secret prefix for a context, in `context=prefix` format. Defaults to the context name. Repeatable. +|--namespace |string |Namespace for operator resources (default `redpanda`). +|--service-name |string |Operator deployment label selector value (`app.kubernetes.io/name`) (default `operator`). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc new file mode 100644 index 0000000000..87e20d9a48 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc @@ -0,0 +1,50 @@ += rpk k8s multicluster +:description: Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. + +== Usage + +[,bash] +---- +rpk k8s multicluster [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc[`rpk k8s multicluster bootstrap`] +|Bootstrap TLS certificates and kubeconfig secrets across multiple Kubernetes clusters for a Redpanda multicluster deployment. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc[`rpk k8s multicluster bundle`] +|Collects environment data from each Kubernetes cluster running the Redpanda multicluster operator and packages it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc[`rpk k8s multicluster status`] +|Checks each cluster's operator pod health, raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-uninstall.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-uninstall.adoc new file mode 100644 index 0000000000..dabe39c19d --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-uninstall.adoc @@ -0,0 +1,46 @@ += rpk k8s uninstall +:description: pass:q[Uninstall the Redpanda Kubernetes plugin. By default this removes only the plugin binary that `rpk` installed at `$HOME/.local/bin/.rpk.managed-k8s`.] + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Uninstall the Redpanda Kubernetes plugin. + +By default this removes only the plugin binary that `rpk` installed at `$HOME/.local/bin/.rpk.managed-k8s`. If the resolved plugin was not installed by rpk (a self-managed copy, for example one you downloaded or installed through a package manager), `rpk` refuses to remove it unless you pass `--force`. + +If the resolved plugin shadows other k8s plugin copies elsewhere on your PATH, those are left in place unless you pass `--include-shadowed`. + +== Usage + +[,bash] +---- +rpk k8s uninstall [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--force |bool |Remove the plugin even if it was not installed by rpk (`self-managed`). +|--include-shadowed |bool |Also remove other k8s plugin copies shadowed by the resolved one. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-upgrade.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-upgrade.adoc new file mode 100644 index 0000000000..0d2fbfaefb --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-upgrade.adoc @@ -0,0 +1,41 @@ += rpk k8s upgrade +:description: Upgrade to the latest Redpanda Kubernetes plugin version. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Upgrade to the latest Redpanda Kubernetes plugin version. + +== Usage + +[,bash] +---- +rpk k8s upgrade [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--no-confirm |bool |Disable confirmation prompt for major version upgrades. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-version.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-version.adoc new file mode 100644 index 0000000000..01b9f701b7 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-version.adoc @@ -0,0 +1,33 @@ += rpk k8s version +:description: Print build information. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Print build information. + +== Usage + +[,bash] +---- +rpk k8s version [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc new file mode 100644 index 0000000000..d7bf56f81b --- /dev/null +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc @@ -0,0 +1,56 @@ += rpk k8s +:description: Interact with Redpanda clusters running on Kubernetes. + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Interact with Redpanda clusters running on Kubernetes. + +== Usage + +[,bash] +---- +rpk k8s [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-k8s/rpk-k8s-install.adoc[`rpk k8s install`] +|Install the Redpanda Kubernetes plugin. This command installs the latest version by default. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[`rpk k8s multicluster`] +|Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-uninstall.adoc[`rpk k8s uninstall`] +|Uninstall the Redpanda Kubernetes plugin. By default this removes only the plugin binary that `rpk` installed at `$HOME/.local/bin/.rpk.managed-k8s`. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-upgrade.adoc[`rpk k8s upgrade`] +|Upgrade to the latest Redpanda Kubernetes plugin version. + +|xref:reference:rpk/rpk-k8s/rpk-k8s-version.adoc[`rpk k8s version`] +|Print build information. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/Library/Application Support/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] From 8f801c90e99c5dfa686b6b41ea56fc4efaf074f6 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 16 Jul 2026 14:42:16 +0100 Subject: [PATCH 15/25] docs: bridge multicluster and Stretch Cluster terminology; link rpk k8s 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. --- .../pages/redpanda/kubernetes/k-stretch-clusters.adoc | 8 ++++---- modules/get-started/pages/release-notes/operator.adoc | 2 +- .../reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc | 6 ++++-- modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc | 2 +- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 7dcac2ad07..35284148b4 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -28,7 +28,7 @@ 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. +* *Multicluster operators*: One Redpanda Operator in each Kubernetes cluster. The operators coordinate through Raft consensus to manage the Stretch Cluster as a single unit. The rpk commands for this operator plane live under xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[`rpk k8s multicluster`]. * *Cross-cluster networking*: Direct broker-to-broker communication across Kubernetes clusters for Raft replication. == Prerequisites @@ -65,7 +65,7 @@ NOTE: Brokers derive their advertised addresses from the `apps.kubernetes.io/pod * *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. +NOTE: You do not need to create TLS certificates for inter-operator communication yourself. The xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc[`rpk k8s multicluster bootstrap`] command generates an ECDSA P-256 certificate authority (CA) and per-operator certificates automatically. == Choose a networking mode @@ -510,7 +510,7 @@ CAUTION: Keep these timeouts comfortably longer than any transient cross-region 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: +. Before you start, verify that the Raft group is healthy on every cluster with xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc[`rpk k8s multicluster status`]: + [,bash] ---- @@ -549,7 +549,7 @@ This command validates: * 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. +To collect a diagnostics bundle for Redpanda Support, run xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc[`rpk k8s multicluster bundle`] with the same connection flags. === Operators not forming a Raft group diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index e0a0aa0b08..9219bd8a6f 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -18,7 +18,7 @@ link:https://github.com/redpanda-data/redpanda-operator/blob/release/v26.2.x/ope 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`). +The release also adds the xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[`rpk k8s` plugin], with xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[`rpk k8s multicluster`] commands to bootstrap TLS certificates and peer configuration (`bootstrap`), check deployment health (`status`), and collect diagnostics bundles (`bundle`). For deployment steps, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc index 87e20d9a48..f07bf96147 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc @@ -1,10 +1,12 @@ = rpk k8s multicluster -:description: Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. +:description: Commands for bootstrapping and managing the multicluster operators that run a Redpanda Stretch Cluster across multiple Kubernetes clusters. // This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc // tag::single-source[] -Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. +Commands for bootstrapping and managing the multicluster operators that run a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster] across multiple Kubernetes clusters. + +A multicluster deployment is the operator plane behind a Stretch Cluster: one Redpanda Operator in each Kubernetes cluster, coordinating through Raft consensus to manage the Stretch Cluster as a single unit. == Usage diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc index d7bf56f81b..94d56d04f3 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s.adoc @@ -26,7 +26,7 @@ rpk k8s [flags] |Install the Redpanda Kubernetes plugin. This command installs the latest version by default. |xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[`rpk k8s multicluster`] -|Commands for bootstrapping and managing Redpanda multicluster deployments across multiple Kubernetes clusters. +|Commands for bootstrapping and managing the multicluster operators that run a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster] across multiple Kubernetes clusters. |xref:reference:rpk/rpk-k8s/rpk-k8s-uninstall.adoc[`rpk k8s uninstall`] |Uninstall the Redpanda Kubernetes plugin. By default this removes only the plugin binary that `rpk` installed at `$HOME/.local/bin/.rpk.managed-k8s`. From 1dbe8ea8836af4b2d12f8a2aeb1c36313aa965cf Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 16 Jul 2026 15:27:35 +0100 Subject: [PATCH 16/25] docs: frame rpk k8s multicluster descriptions around Stretch Clusters 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. --- .../pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc | 5 ++--- .../pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc | 5 ++--- .../pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc | 5 ++--- .../reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc | 6 +++--- 4 files changed, 9 insertions(+), 12 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc index 991b817401..52717d7e31 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc @@ -1,11 +1,10 @@ = rpk k8s multicluster bootstrap -:description: Bootstrap TLS certificates and kubeconfig secrets across multiple Kubernetes clusters for a Redpanda multicluster deployment. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. +:description: Bootstrap the TLS certificates and kubeconfig secrets that the multicluster operators of a Redpanda Stretch Cluster need to communicate across Kubernetes clusters. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. // This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc // tag::single-source[] -Bootstrap TLS certificates and kubeconfig secrets across multiple -Kubernetes clusters for a Redpanda multicluster deployment. +Bootstrap the TLS certificates and kubeconfig secrets that the multicluster operators of a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster] need to communicate across Kubernetes clusters. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc index 483999ac67..84c0b52bad 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc @@ -1,11 +1,10 @@ = rpk k8s multicluster bundle -:description: pass:q[Collects environment data from each Kubernetes cluster running the Redpanda multicluster operator and packages it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves.] +:description: pass:q[Collect environment data from each Kubernetes cluster in a Redpanda Stretch Cluster deployment and package it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves.] // This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc // tag::single-source[] -Collects environment data from each Kubernetes cluster running the -Redpanda multicluster operator and packages it into a ZIP file for support. +Collect environment data from each Kubernetes cluster in a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster] deployment and package it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves. diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc index a07d6725a9..37127bc9ef 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc @@ -1,11 +1,10 @@ = rpk k8s multicluster status -:description: Checks each cluster's operator pod health, raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. +:description: Check the health of the multicluster operators that run a Redpanda Stretch Cluster: operator pod health, Raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. // This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc // tag::single-source[] -Checks each cluster's operator pod health, raft consensus state, -TLS certificate validity, and cross-cluster consistency. +Check the health of the multicluster operators that run a xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[Stretch Cluster]: operator pod health, Raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. Also diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc index f07bf96147..89079fa2ca 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-multicluster.adoc @@ -25,13 +25,13 @@ rpk k8s multicluster [flags] |Command |Description |xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bootstrap.adoc[`rpk k8s multicluster bootstrap`] -|Bootstrap TLS certificates and kubeconfig secrets across multiple Kubernetes clusters for a Redpanda multicluster deployment. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. +|Bootstrap the TLS certificates and kubeconfig secrets that the multicluster operators of a Stretch Cluster need to communicate across Kubernetes clusters. This command connects to each specified Kubernetes context, generates a shared CA certificate, and distributes per-cluster TLS certificates and kubeconfig secrets so that the multicluster operator can communicate across clusters. |xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-bundle.adoc[`rpk k8s multicluster bundle`] -|Collects environment data from each Kubernetes cluster running the Redpanda multicluster operator and packages it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves. +|Collect environment data from each Kubernetes cluster in a Stretch Cluster deployment and package it into a ZIP file for support. This is the operator-side counterpart to `rpk debug bundle`, which collects data from the Redpanda brokers themselves. |xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster-status.adoc[`rpk k8s multicluster status`] -|Checks each cluster's operator pod health, raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. +|Check the health of the multicluster operators that run a Stretch Cluster: operator pod health, Raft consensus state, TLS certificate validity, and cross-cluster consistency. Connects to each specified Kubernetes context, finds the multicluster operator pod, port-forwards to its gRPC transport, and queries raft status. |=== From 2b57a6bc4ade7f80e1348e6d68c11fa9aa816d14 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Fri, 17 Jul 2026 17:01:53 +0100 Subject: [PATCH 17/25] docs: recommend 2/2/1 broker layout with replication factor 5 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. --- .../redpanda/kubernetes/k-stretch-clusters.adoc | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 35284148b4..20d76af2f4 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -324,7 +324,9 @@ spec: key: license.key config: cluster: - default_topic_replications: 3 + # Five replicas spread over a 2/2/1 broker layout keep a Raft + # majority through the loss of any one location. + default_topic_replications: 5 # 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 @@ -350,7 +352,9 @@ 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`: +Each RedpandaBrokerPool defines a group of brokers in one Kubernetes cluster and binds to the StretchCluster through `spec.clusterRef`. + +Redpanda Data recommends five brokers distributed 2/2/1 across the three Kubernetes clusters, with `default_topic_replications: 5`. With this layout, every partition and the cluster's Raft groups keep a majority through the loss of any one location, including either two-broker location, and the single-broker location acts as a tiebreaker. Save the following to `brokerpool-cluster1.yaml`: + [,yaml,subs="attributes+"] ---- @@ -364,7 +368,7 @@ spec: group: cluster.redpanda.com kind: StretchCluster name: cluster - replicas: 3 + replicas: 2 # 2/2/1 across the three clusters image: # <2> repository: docker.redpanda.com/redpandadata/redpanda tag: {latest-redpanda-tag} @@ -387,7 +391,7 @@ spec: <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: +Apply each pool to its own cluster, changing `metadata.name` for each one and setting `replicas` to 2, 2, and 1: + [,bash] ---- From 0bfd907cca1da0dce058e27b58787d7989f03bce Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 20 Jul 2026 09:35:37 +0100 Subject: [PATCH 18/25] docs: reference the supported Kubernetes versions instead of a 1.28 floor The 1.28 pod-index requirement is a technical floor well below the supported range for the 26.2 operator; point the prerequisite at the compatibility matrix instead and drop the now-moot pod-index NOTE. --- .../deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 20d76af2f4..29189f2df5 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -50,9 +50,7 @@ rpk k8s install --plugin-version {operator-beta-version} + NOTE: During the 26.2 beta, no plugin release is marked as latest, so running `rpk k8s install` without flags fails with `no latest Redpanda Kubernetes plugin release found`. Pin the version as shown. -* *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. +* *At least three Kubernetes clusters, running a xref:upgrade:k-compatibility.adoc#compatibility-matrix[supported Kubernetes version]*: 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. * *Cross-cluster networking*: One of the networking modes described in <>. From 1b621a27295a6d7ad548d60051f079a065fb1920 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 20 Jul 2026 13:53:45 +0100 Subject: [PATCH 19/25] docs: add operator restart step to bootstrap-user recovery Re-validation on Kubernetes 1.34 reproduced the bootstrap-user race and showed that deleting the mismatched Secret copies is not always enough: reconciliation can stay wedged on a maintenance-mode check that fails to resolve broker hostnames that were never created. Restarting the operator Deployments clears it (verified live). --- .../pages/redpanda/kubernetes/k-stretch-clusters.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 29189f2df5..3224b0879c 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -626,6 +626,15 @@ done kubectl delete secret cluster-bootstrap-user --namespace redpanda --context ---- +If the StretchCluster still reports no brokers after the Secrets converge, restart the operator Deployments to clear the stalled reconciliation: + +[,bash] +---- +for ctx in ; do + kubectl rollout restart deployment --namespace redpanda --context "$ctx" +done +---- + === 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. From a9d0f783e1ccd2074bd4d9b122fb4ef8a0cfd9f2 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 21 Jul 2026 10:41:29 +0100 Subject: [PATCH 20/25] docs: assume 26.2 GA; remove beta operator framing Per release framing decision: drop the beta-release NOTEs, install the operator with the standard {latest-operator-version} pin, install the rpk k8s plugin unpinned (the GA release is marked latest), and revert the antora.yml beta-version fallbacks, which no page references now. --- antora.yml | 8 +++++--- .../pages/redpanda/kubernetes/k-stretch-clusters.adoc | 10 +++------- .../reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc | 2 -- 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/antora.yml b/antora.yml index e854317b0d..512cc4b025 100644 --- a/antora.yml +++ b/antora.yml @@ -34,12 +34,11 @@ asciidoc: # We try to fetch the latest versions from GitHub at build time # -- full-version: 26.2.1 - latest-redpanda-tag: 'v26.1.9' + latest-redpanda-tag: 'v26.1.12' latest-console-tag: 'v3.3.1' latest-release-commit: 'ebee215fdb2b8004735c6f800e532564cdcc05e1' latest-operator-version: 'v2.3.8-24.3.6' - operator-beta-version: '26.2.1-beta.3' - operator-beta-tag: 'v26.2.1-beta.3' + operator-beta-tag: '' helm-beta-tag: '' latest-redpanda-helm-chart-version: '' redpanda-beta-version: '' @@ -53,6 +52,9 @@ asciidoc: supported-rhel-recommended: '9+' supported-ubuntu-required: '20.04 LTS' supported-ubuntu-recommended: '22.04+' + # Linux package repository migration (dl.redpanda.com -> linux.pkg.redpanda.com) + legacy-repo-shutdown-date: 'September 28, 2026' + repo-dual-publish-start: 'June 1, 2026' badge-deprecated: 'image:https://img.shields.io/badge/-Deprecated-red.svg[xref=upgrade:deprecated/index.adoc]' removals-without-aliases: - page: reference/rpk/rpk-cloud/ diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 3224b0879c..8522cb6c54 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -35,9 +35,7 @@ A Stretch Cluster deployment includes: 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 <>. -+ -NOTE: During the 26.2 beta, this is a beta release of the operator. Beta releases are not recommended for production use. The installation steps on this page pin the beta chart version. +* *Redpanda Operator 26.2 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]. @@ -45,10 +43,8 @@ NOTE: During the 26.2 beta, this is a beta release of the operator. Beta release + [,bash] ---- -rpk k8s install --plugin-version {operator-beta-version} +rpk k8s install ---- -+ -NOTE: During the 26.2 beta, no plugin release is marked as latest, so running `rpk k8s install` without flags fails with `no latest Redpanda Kubernetes plugin release found`. Pin the version as shown. * *At least three Kubernetes clusters, running a xref:upgrade:k-compatibility.adoc#compatibility-matrix[supported Kubernetes version]*: 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. @@ -230,7 +226,7 @@ helm repo update helm install redpanda/operator \ --kube-context \ --namespace redpanda \ - --version {operator-beta-version} \ + --version {latest-operator-version} \ --set fullnameOverride= \ --set crds.enabled=true \ --set crds.experimental=true \ diff --git a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc index 3a59efd658..63a11e13b0 100644 --- a/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc +++ b/modules/reference/pages/rpk/rpk-k8s/rpk-k8s-install.adoc @@ -12,8 +12,6 @@ Alternatively, you may specify a version using the `--plugin-version` flag. You may force the installation using the `--force` flag. -NOTE: During the 26.2 beta, no plugin release is marked as latest, so running `rpk k8s install` without flags fails with `no latest Redpanda Kubernetes plugin release found`. Pin the beta version instead: `rpk k8s install --plugin-version {operator-beta-version}`. - == Usage [,bash] From 02dc7a8f2b92c3595571f4e26c278488f12ef3e5 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 21 Jul 2026 12:22:56 +0100 Subject: [PATCH 21/25] docs: pin operator install to 26.2.1 The latest-operator-version attribute resolves at build time to the newest published release, which is still 26.1.x until GA day, so previews would show a version without Stretch Cluster support. Pin 26.2.1 for now; swap back to the attribute after GA. --- debug-page-attrs.js | 18 ++++ local-antora-playbook.yml | 3 +- local-antora-playbook.yml.bak | 97 +++++++++++++++++++ .../kubernetes/k-stretch-clusters.adoc | 2 +- 4 files changed, 118 insertions(+), 2 deletions(-) create mode 100644 debug-page-attrs.js create mode 100644 local-antora-playbook.yml.bak diff --git a/debug-page-attrs.js b/debug-page-attrs.js new file mode 100644 index 0000000000..caa5b6fc0b --- /dev/null +++ b/debug-page-attrs.js @@ -0,0 +1,18 @@ +'use strict' + +module.exports.register = function () { + this.on('documentsConverted', ({ contentCatalog }) => { + const targets = [ + '/connect/components/inputs/postgres_cdc/', + '/connect/components/inputs/kafka/', + ] + contentCatalog.getPages((p) => p.pub && targets.includes(p.pub.url)).forEach((page) => { + const attrs = page.asciidoc?.attributes || {} + const pageAttrs = Object.keys(attrs).filter((k) => k.startsWith('page-')) + console.log(`[debug-page-attrs] ${page.pub.url}`) + console.log(` page-* keys: ${JSON.stringify(pageAttrs)}`) + console.log(` page-context-switcher: ${attrs['page-context-switcher']}`) + console.log(` page-cloud-available: ${attrs['page-cloud-available']}`) + }) + }) +} diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 1636d5f304..27e5753f7a 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -29,7 +29,7 @@ content: start_paths: [home, data-platform, self-managed] ui: bundle: - url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip + url: /private/tmp/claude-502/-Users-jakecahill-Documents-docs-ui/42a37509-86eb-4a87-8e12-5d09930a904a/scratchpad/ui-bundle.zip snapshot: true asciidoc: attributes: @@ -43,6 +43,7 @@ asciidoc: antora: extensions: # Conditional home page redirect when agentic-data-plane component doesn't exist + - require: ./debug-page-attrs.js - require: '@redpanda-data/docs-extensions-and-macros/extensions/conditional-home-redirect' # Unified navigation extension (config-driven) # Components with page-navigation attribute use that config diff --git a/local-antora-playbook.yml.bak b/local-antora-playbook.yml.bak new file mode 100644 index 0000000000..1636d5f304 --- /dev/null +++ b/local-antora-playbook.yml.bak @@ -0,0 +1,97 @@ +site: + title: Redpanda Docs + start_page: 26.2@streaming:get-started:intro-to-events.adoc + url: http://localhost:5002 + robots: disallow + keys: + preview: true +urls: + html_extension_style: indexify + latest_version_segment: 'current' +output: + clean: true + +content: + sources: + - url: . + branches: HEAD + - url: https://github.com/redpanda-data/docs + branches: [v/*, main, shared, site-search,'!v-end-of-life/*'] + - url: https://github.com/redpanda-data/cloud-docs + branches: main + - url: https://github.com/redpanda-data/redpanda-labs + branches: main + start_paths: [docs,'*/docs'] + - url: https://github.com/redpanda-data/rp-connect-docs + branches: main + - url: https://github.com/redpanda-data/docs-site + branches: 'main' + start_paths: [home, data-platform, self-managed] +ui: + bundle: + url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip + snapshot: true +asciidoc: + attributes: + extensions: + - '@asciidoctor/tabs' + - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components' + - '@redpanda-data/docs-extensions-and-macros/macros/glossary' + - '@redpanda-data/docs-extensions-and-macros/macros/config-ref' + - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref' + - '@redpanda-data/docs-extensions-and-macros/asciidoc-extensions/add-line-numbers-highlights' +antora: + extensions: + # Conditional home page redirect when agentic-data-plane component doesn't exist + - require: '@redpanda-data/docs-extensions-and-macros/extensions/conditional-home-redirect' + # Unified navigation extension (config-driven) + # Components with page-navigation attribute use that config + # Components without page-navigation use standard Antora navigation + - require: '@redpanda-data/docs-extensions-and-macros/extensions/unified-navigation' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-info' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/unpublish-pages' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/validate-attributes' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' + data: + sets: + docker_labs: + component: labs + family: page + filter: docker-compose + env_type: Docker + attribute_name: docker-labs-index + - require: '@redpanda-data/docs-extensions-and-macros/extensions/archive-attachments' + data: + archives: + - component: 'streaming' + output_archive: 'redpanda-quickstart.tar.gz' + file_patterns: + - '**/test-resources/**/docker-compose/**' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments' + data: + replacements: + - components: + - 'streaming' + - 'labs' + file_patterns: + - '**/docker-compose.yaml' + - '**/docker-compose.yml' + - require: '@sntke/antora-mermaid-extension' + mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs + script_stem: mermaid-scripts + mermaid_initialize_options: + start_on_load: true + theme: base + theme_variables: + line_color: '#e2401b' + font_family: Inter, sans-serif + - require: '@redpanda-data/docs-extensions-and-macros/extensions/collect-bloblang-samples' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/find-related-docs' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/find-related-labs' + - require: '@redpanda-data/docs-extensions-and-macros/extensions/aggregate-terms' diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 8522cb6c54..42a5516023 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -226,7 +226,7 @@ helm repo update helm install redpanda/operator \ --kube-context \ --namespace redpanda \ - --version {latest-operator-version} \ + --version 26.2.1 \ --set fullnameOverride= \ --set crds.enabled=true \ --set crds.experimental=true \ From 1a7f05e488a6c5c4d386f8d6b52b8b4a2c88363d Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 21 Jul 2026 12:25:23 +0100 Subject: [PATCH 22/25] Revert "docs: pin operator install to 26.2.1" This reverts commit 02dc7a8f2b92c3595571f4e26c278488f12ef3e5. --- debug-page-attrs.js | 18 ---- local-antora-playbook.yml | 3 +- local-antora-playbook.yml.bak | 97 ------------------- .../kubernetes/k-stretch-clusters.adoc | 2 +- 4 files changed, 2 insertions(+), 118 deletions(-) delete mode 100644 debug-page-attrs.js delete mode 100644 local-antora-playbook.yml.bak diff --git a/debug-page-attrs.js b/debug-page-attrs.js deleted file mode 100644 index caa5b6fc0b..0000000000 --- a/debug-page-attrs.js +++ /dev/null @@ -1,18 +0,0 @@ -'use strict' - -module.exports.register = function () { - this.on('documentsConverted', ({ contentCatalog }) => { - const targets = [ - '/connect/components/inputs/postgres_cdc/', - '/connect/components/inputs/kafka/', - ] - contentCatalog.getPages((p) => p.pub && targets.includes(p.pub.url)).forEach((page) => { - const attrs = page.asciidoc?.attributes || {} - const pageAttrs = Object.keys(attrs).filter((k) => k.startsWith('page-')) - console.log(`[debug-page-attrs] ${page.pub.url}`) - console.log(` page-* keys: ${JSON.stringify(pageAttrs)}`) - console.log(` page-context-switcher: ${attrs['page-context-switcher']}`) - console.log(` page-cloud-available: ${attrs['page-cloud-available']}`) - }) - }) -} diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 27e5753f7a..1636d5f304 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -29,7 +29,7 @@ content: start_paths: [home, data-platform, self-managed] ui: bundle: - url: /private/tmp/claude-502/-Users-jakecahill-Documents-docs-ui/42a37509-86eb-4a87-8e12-5d09930a904a/scratchpad/ui-bundle.zip + url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip snapshot: true asciidoc: attributes: @@ -43,7 +43,6 @@ asciidoc: antora: extensions: # Conditional home page redirect when agentic-data-plane component doesn't exist - - require: ./debug-page-attrs.js - require: '@redpanda-data/docs-extensions-and-macros/extensions/conditional-home-redirect' # Unified navigation extension (config-driven) # Components with page-navigation attribute use that config diff --git a/local-antora-playbook.yml.bak b/local-antora-playbook.yml.bak deleted file mode 100644 index 1636d5f304..0000000000 --- a/local-antora-playbook.yml.bak +++ /dev/null @@ -1,97 +0,0 @@ -site: - title: Redpanda Docs - start_page: 26.2@streaming:get-started:intro-to-events.adoc - url: http://localhost:5002 - robots: disallow - keys: - preview: true -urls: - html_extension_style: indexify - latest_version_segment: 'current' -output: - clean: true - -content: - sources: - - url: . - branches: HEAD - - url: https://github.com/redpanda-data/docs - branches: [v/*, main, shared, site-search,'!v-end-of-life/*'] - - url: https://github.com/redpanda-data/cloud-docs - branches: main - - url: https://github.com/redpanda-data/redpanda-labs - branches: main - start_paths: [docs,'*/docs'] - - url: https://github.com/redpanda-data/rp-connect-docs - branches: main - - url: https://github.com/redpanda-data/docs-site - branches: 'main' - start_paths: [home, data-platform, self-managed] -ui: - bundle: - url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip - snapshot: true -asciidoc: - attributes: - extensions: - - '@asciidoctor/tabs' - - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components' - - '@redpanda-data/docs-extensions-and-macros/macros/glossary' - - '@redpanda-data/docs-extensions-and-macros/macros/config-ref' - - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref' - - '@redpanda-data/docs-extensions-and-macros/asciidoc-extensions/add-line-numbers-highlights' -antora: - extensions: - # Conditional home page redirect when agentic-data-plane component doesn't exist - - require: '@redpanda-data/docs-extensions-and-macros/extensions/conditional-home-redirect' - # Unified navigation extension (config-driven) - # Components with page-navigation attribute use that config - # Components without page-navigation use standard Antora navigation - - require: '@redpanda-data/docs-extensions-and-macros/extensions/unified-navigation' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-info' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/unpublish-pages' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/validate-attributes' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data' - data: - sets: - docker_labs: - component: labs - family: page - filter: docker-compose - env_type: Docker - attribute_name: docker-labs-index - - require: '@redpanda-data/docs-extensions-and-macros/extensions/archive-attachments' - data: - archives: - - component: 'streaming' - output_archive: 'redpanda-quickstart.tar.gz' - file_patterns: - - '**/test-resources/**/docker-compose/**' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments' - data: - replacements: - - components: - - 'streaming' - - 'labs' - file_patterns: - - '**/docker-compose.yaml' - - '**/docker-compose.yml' - - require: '@sntke/antora-mermaid-extension' - mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs - script_stem: mermaid-scripts - mermaid_initialize_options: - start_on_load: true - theme: base - theme_variables: - line_color: '#e2401b' - font_family: Inter, sans-serif - - require: '@redpanda-data/docs-extensions-and-macros/extensions/collect-bloblang-samples' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/find-related-docs' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/find-related-labs' - - require: '@redpanda-data/docs-extensions-and-macros/extensions/aggregate-terms' diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 42a5516023..8522cb6c54 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -226,7 +226,7 @@ helm repo update helm install redpanda/operator \ --kube-context \ --namespace redpanda \ - --version 26.2.1 \ + --version {latest-operator-version} \ --set fullnameOverride= \ --set crds.enabled=true \ --set crds.experimental=true \ From 6edfa0176d5e0fdeef55955aded1c5bdbe647c1c Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 22 Jul 2026 13:02:10 +0100 Subject: [PATCH 23/25] docs: link StretchCluster and RedpandaBrokerPool CRD field reference The generated CRD reference gains these types via docs#1817 (redpanda-operator#1690 removes the Stretch ignore for GA), so the manifest steps can now link field-level documentation. Merge order: docs#1817 before this PR, or the anchors resolve only at GA regen. --- .../deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index 8522cb6c54..b2cdbe1ac0 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -334,6 +334,8 @@ spec: ---- <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. + +For all StretchCluster fields, see the xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-stretchcluster[StretchCluster reference]. + Apply the manifest to every cluster: + @@ -384,6 +386,8 @@ spec: <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. + +For all RedpandaBrokerPool fields, see the xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandabrokerpool[RedpandaBrokerPool reference]. + Apply each pool to its own cluster, changing `metadata.name` for each one and setting `replicas` to 2, 2, and 1: + From 3b7a460a5ed5a6b3c9eadbb98affc40440e41893 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 22 Jul 2026 13:45:13 +0100 Subject: [PATCH 24/25] docs: apply standards review fixes - Correct BYOC expansion to Bring Your Own Cloud in operator release notes - Use 'introduces' for the Stretch Clusters release-note entry - Add learning objectives and expand the intro on the chooser page - Remove undated 'In this release' phrasing - Move the Enterprise license NOTE above the intro to match sibling pages - Fully qualify two pre-existing relative xrefs in k-production-deployment --- .../redpanda/kubernetes/k-choose-deployment.adoc | 13 ++++++++++--- .../kubernetes/k-production-deployment.adoc | 4 ++-- .../redpanda/kubernetes/k-stretch-clusters.adoc | 4 ++-- .../get-started/pages/release-notes/operator.adoc | 4 ++-- 4 files changed, 16 insertions(+), 9 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc index 44caed708f..ba087731f9 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-choose-deployment.adoc @@ -4,12 +4,19 @@ :page-categories: Deployment, High Availability :page-topic-type: concept :personas: platform_operator, platform_engineer +:learning-objective-1: Compare Redpanda deployment topologies by failure domain, recovery objectives, and operational cost +:learning-objective-2: Choose the deployment guide that matches your availability requirements -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. +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). Each topology mitigates a different class of failure, from the loss of a single broker to the loss of an entire region, and makes different trade-offs in latency, license requirements, and operational complexity. This page compares the available topologies along those dimensions and routes you to the right deployment guide. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} == What you're protecting against -Each topology mitigates a different class of failure: +Use this table to identify the failures you must plan for and the mechanisms that mitigate them: include::deploy:partial$high-availability.adoc[tag=failure-mitigation] @@ -74,7 +81,7 @@ For read-only offloading rather than disaster recovery, see xref:manage:kubernet 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. +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 diff --git a/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc b/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc index 6a1073bf24..5c911cc1c2 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc @@ -715,7 +715,7 @@ statefulset: WARNING: Disabling `podAntiAffinity` rules is not recommended for production environments as it allows multiple brokers to be scheduled on the same node, increasing the risk of data loss if a node fails. -See also: xref:./k-high-availability.adoc[] +See also: xref:deploy:redpanda/kubernetes/k-high-availability.adoc[] === Graceful shutdown @@ -785,6 +785,6 @@ See the xref:manage:kubernetes/index.adoc[Manage Kubernetes topics] to learn how include::shared:partial$suggested-reading.adoc[] -- xref:./k-high-availability.adoc[] +- xref:deploy:redpanda/kubernetes/k-high-availability.adoc[] - xref:reference:k-redpanda-helm-spec.adoc[Redpanda Helm Specification] - xref:reference:k-crd.adoc[Redpanda CRD Reference] diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index b2cdbe1ac0..f339333229 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -9,13 +9,13 @@ :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. - [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +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: 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/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index 9219bd8a6f..777263e450 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -16,7 +16,7 @@ link:https://github.com/redpanda-data/redpanda-operator/blob/release/v26.2.x/ope === 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 Redpanda Operator introduces 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 xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[`rpk k8s` plugin], with xref:reference:rpk/rpk-k8s/rpk-k8s-multicluster.adoc[`rpk k8s multicluster`] commands to bootstrap TLS certificates and peer configuration (`bootstrap`), check deployment health (`status`), and collect diagnostics bundles (`bundle`). @@ -24,7 +24,7 @@ For deployment steps, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.ado === NodePool CRD documentation removed -The NodePool custom resource (beta in v26.1.x) is intended for internal use in Redpanda Cloud (BYOC) deployments and is no longer documented for self-managed deployments. The CRD remains available and actively maintained, and existing configurations continue to work. +The NodePool custom resource (beta in v26.1.x) is intended for internal use in Bring Your Own Cloud (BYOC) deployments and is no longer documented for self-managed deployments. The CRD remains available and actively maintained, and existing configurations continue to work. == Redpanda Operator v26.1.x From f5d4b85a7799f219b3bacad8e38e20affaa6fe97 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 22 Jul 2026 13:49:30 +0100 Subject: [PATCH 25/25] docs: correct stretch cluster facts against operator source - Multicluster mode, not crds.experimental, installs the StretchCluster and RedpandaBrokerPool CRDs; drop the unnecessary flag - Correct the flat-mode default port list (9093/9644/33145; no 9092) - Note that rerunning bootstrap rotates the CA and requires an operator restart on all clusters --- .../pages/redpanda/kubernetes/k-stretch-clusters.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc index f339333229..0db34edf3a 100644 --- a/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc +++ b/modules/deploy/pages/redpanda/kubernetes/k-stretch-clusters.adoc @@ -35,7 +35,7 @@ A Stretch Cluster deployment includes: Before deploying a Stretch Cluster, ensure you have: -* *Redpanda Operator 26.2 or later* on each Kubernetes cluster, installed with experimental CRDs enabled. See <>. +* *Redpanda Operator 26.2 or later* on each Kubernetes cluster, installed in multicluster mode. Multicluster mode installs the StretchCluster and RedpandaBrokerPool CRDs. 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]. @@ -75,7 +75,7 @@ Brokers in a Stretch Cluster replicate data and maintain Raft consensus across K |`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). +|CNI configuration that routes pod IPs across clusters, non-overlapping pod CIDR ranges, and firewall rules that allow traffic on the Redpanda ports (by default, 9093 for the Kafka API, 9644 for the Admin API, and 33145 for internal RPC). |`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. @@ -229,7 +229,6 @@ helm install redpanda/operator \ --version {latest-operator-version} \ --set fullnameOverride= \ --set crds.enabled=true \ - --set crds.experimental=true \ --set multicluster.enabled=true \ --set multicluster.name= \ --set multicluster.apiServerExternalAddress= \ @@ -579,7 +578,7 @@ kubectl get secret --namespace redpanda --context