From b2a47ac5c1ecee96b86bb3dab3e3bb7967b269a1 Mon Sep 17 00:00:00 2001
From: JakeSCahill <jake@redpanda.com>
Date: Tue, 14 Jul 2026 13:54:22 +0100
Subject: [PATCH] docs: document cross-namespace shadow links via
 clusterRef.namespace

The optional namespace field on clusterRef (operator 26.2.1-beta.x)
resolves the referenced cluster in another namespace, so same-Kubernetes-
cluster cross-namespace shadow links no longer require
staticConfiguration. Adds the example, the default behavior, and the
dev/test-only caveat from the changelog; repositions staticConfiguration
as the path for unmanaged/external clusters. Adds the operator beta
version fallbacks (same values as PRs #1681/#1787).
---
 antora.yml                                    |  3 +-
 .../shadowing/k-shadow-linking.adoc           | 35 +++++++++++++++++--
 2 files changed, 35 insertions(+), 3 deletions(-)

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/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc b/modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc
index e95664ad09..cdeb9afdad 100644
--- a/modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc
+++ b/modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc
@@ -70,10 +70,41 @@ The operator automatically resolves cluster connection details from the referenc
 +
 [NOTE]
 ====
-When using `clusterRef`, the operator handles authentication automatically using the cluster's internal credentials. For cross-namespace or external clusters, use `staticConfiguration` instead.
+When using `clusterRef`, the operator handles authentication automatically using the cluster's internal credentials. For clusters that the operator doesn't manage, such as clusters running in a different Kubernetes cluster, use `staticConfiguration` instead.
+====
++
+If the source and shadow clusters run in different namespaces on the same Kubernetes cluster, set the optional `namespace` field on the `clusterRef`. It defaults to the ShadowLink's own namespace. This field requires Redpanda Operator {operator-beta-version} or later.
++
+.`shadowlink.yaml`
+[,yaml]
+----
+apiVersion: cluster.redpanda.com/v1alpha2
+kind: ShadowLink
+metadata:
+  name: disaster-recovery-link
+  namespace: <shadow-namespace>
+spec:
+  shadowCluster:
+    clusterRef:
+      name: redpanda-shadow
+  sourceCluster:
+    clusterRef:
+      name: redpanda-source
+      namespace: <source-namespace> # <1>
+  topicMetadataSyncOptions:
+    autoCreateShadowTopicFilters:
+      - name: '*'
+        filterType: include
+        patternType: literal
+----
+<1> Resolves the source cluster in `<source-namespace>` instead of the ShadowLink's namespace.
++
+[CAUTION]
+====
+Running the source and shadow clusters on the same Kubernetes cluster is intended mainly for development and testing, such as cheaply rehearsing replication and failover, optionally with the two clusters pinned to non-overlapping availability zones. For production disaster recovery, place the source and shadow clusters in separate Kubernetes clusters and failure domains.
 ====
 
-- For external or cross-namespace clusters, use `staticConfiguration`:
+- For external clusters, or clusters running in a different Kubernetes cluster, use `staticConfiguration`:
 +
 Create a shadow link with explicit connection details:
 +