Introduce STRIMZI_CENTRAL_CLUSTER_ID env var to identify the central cluster

and validate KafkaNodePool deployment targets in stretch cluster setups

Signed-off-by: Aswin A <[email protected]>

Author: aswinayyolath

095-stretch-cluster.md

@@ -131,6 +131,20 @@ The values of the environment variables use the following format:
 The secrets referenced here must contain the kubeconfig for the Kubernetes cluster available at the provided URL as the value of secret key 'kubeconfig'.
 This allows the central Strimzi operator to authenticate with multiple Kubernetes clusters.
 
+```yaml
+- name: STRIMZI_CENTRAL_CLUSTER_ID
+  value: <central-cluster-id>
+```
+
+- `STRIMZI_CENTRAL_CLUSTER_ID` (Required)
+This environment variable defines the identifier (alias) of the central Kubernetes cluster, where the `Kafka` and `KafkaNodePool` CRs are created in a stretch Kafka deployment.
+This identifier must be unique and must not overlap with any of the cluster IDs defined in the `STRIMZI_REMOTE_KUBE_CONFIG` environment variable.
+This value is used to validate and match the `strimzi.io/stretch-cluster-alias` annotation in `KafkaNodePool` CR to determine whether the resources associated with a given node pool should be deployed in the central cluster.
+If a KafkaNodePool CR has a stretch cluster alias that matches the value of `STRIMZI_CENTRAL_CLUSTER_ID`, the operator will deploy the corresponding resources in the central cluster.
+
+Configuring the central cluster's identity explicitly avoids ambiguity and eliminates the risk of unintentionally deploying to the central cluster when a typo or misconfiguration occurs in the alias.
+This ensures that invalid cluster identifiers always result in a reconciliation failure, leading to a clearer user experience and safer operations.
+
 **Example Secret**
 
 Below is an example Kubernetes Secret containing a kubeconfig for a remote cluster
@@ -221,7 +235,23 @@ metadata:
 
 The identifier used here is required and must match one of the values defined by the user in 'Step 1' and added to the environment variable map value in 'Step 2'.
 This annotation is used to construct critical Kafka configuration properties such as `controller.quorum.voters` and `advertised.listeners`.
-If the identifier does not match any of the values defined in the `STRIMZI_REMOTE_KUBE_CONFIG` environment variable, the operator will deploy the node pool to the central Kubernetes cluster.
+The stretch cluster alias (defined via the annotation `strimzi.io/stretch-cluster-alias`) in the `KafkaNodePoo`l` CR must match exactly one of the following:
+- The value of the environment variable `STRIMZI_CENTRAL_CLUSTER_ID` (representing the current cluster the operator is running in), or
+- One of the cluster IDs defined in the `STRIMZI_REMOTE_KUBE_CONFIG` environment variable.
+
+If the alias does not match either of these, the configuration is considered invalid, and reconciliation for the Kafka CR will fail with an error indicating that the target cluster is not recognized.
+
+
+#### Validation Matrix
+
+| Kafka Stretch Enabled | `strimzi.io/stretch-cluster-alias` Present in KNP | Valid Alias (matches `STRIMZI_CENTRAL_CLUSTER_ID` or `STRIMZI_REMOTE_KUBE_CONFIG`)         | Result                        |
+| :-------------------- | :------------------------------------------------ | :------------------------------------------------------------------------------------------| :---------------------------- |
+| false                 | no                                                | -                                                                                          | ✅ Central-only, valid        |
+| false                 | yes                                               | -                                                                                          | ❌ Invalid, mixed config      |
+| true                  | no                                                | -                                                                                          | ❌ Invalid, alias required    |
+| true                  | yes                                               | ❌ no match                                                                                | ❌ Invalid, unknown cluster alias |
+| true                  | yes                                               | ✅ matches `STRIMZI_CENTRAL_CLUSTER_ID`                                                     | ✅ Deploy to central cluster  |
+| true                  | yes                                               | ✅ matches a cluster in `STRIMZI_REMOTE_KUBE_CONFIG`                                        | ✅ Deploy to remote cluster   |
 
 #### Cluster operator behaviour