docs: cross-namespace shadow links via clusterRef.namespace (DOC-2274)

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: ''

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:
 +