feat: support keeper on a different namespace

api/v1alpha1/clickhousecluster_types.go

@@ -32,8 +32,9 @@ type ClickHouseClusterSpec struct {
 	Shards *int32 `json:"shards"`
 
 	// Reference to the KeeperCluster that is used for ClickHouse coordination.
+	// When namespace is omitted, the ClickHouseCluster namespace is used.
 	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Keeper Cluster Reference"
-	KeeperClusterRef *corev1.LocalObjectReference `json:"keeperClusterRef"`
+	KeeperClusterRef KeeperClusterReference `json:"keeperClusterRef"`
 
 	// Parameters passed to the ClickHouse pod spec.
 	// +optional
@@ -206,6 +207,37 @@ type ClickHouseClusterStatus struct {
 	VersionProbeRevision string `json:"versionProbeRevision,omitempty"`
 }
 
+// KeeperClusterReference identifies the KeeperCluster used by a ClickHouseCluster.
+type KeeperClusterReference struct {
+	// Name of the KeeperCluster resource.
+	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
+	// +kubebuilder:validation:MaxLength=63
+	Name string `json:"name"`
+	// Namespace of the KeeperCluster resource.
+	// When omitted, the ClickHouseCluster namespace is used.
+	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
+	// +kubebuilder:validation:MaxLength=63
+	// +optional
+	Namespace string `json:"namespace,omitempty"`
+}
+
+// NamespacedName resolves the reference to a fully-qualified Kubernetes object key.
+func (r *KeeperClusterReference) NamespacedName(defaultNamespace string) types.NamespacedName {
+	if r == nil {
+		return types.NamespacedName{}
+	}
+
+	namespace := r.Namespace
+	if namespace == "" {
+		namespace = defaultNamespace
+	}
+
+	return types.NamespacedName{
+		Namespace: namespace,
+		Name:      r.Name,
+	}
+}
+
 // ClickHouseCluster is the Schema for the `clickhouseclusters` API.
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
@@ -374,6 +406,11 @@ func (v *ClickHouseCluster) StatefulSetNameByReplicaID(id ClickHouseReplicaID) s
 	return fmt.Sprintf("%s-%d-%d", v.SpecificName(), id.ShardID, id.Index)
 }
 
+// KeeperClusterNamespacedName returns the fully-qualified KeeperCluster reference.
+func (v *ClickHouseCluster) KeeperClusterNamespacedName() types.NamespacedName {
+	return v.Spec.KeeperClusterRef.NamespacedName(v.Namespace)
+}
+
 // HostnameByID returns domain name for the specific replica to access within Kubernetes cluster.
 func (v *ClickHouseCluster) HostnameByID(id ClickHouseReplicaID) string {
 	return formatPodHostname(v.StatefulSetNameByReplicaID(id), v.HeadlessServiceName(), v.Namespace, v.Spec.ClusterDomain)

api/v1alpha1/types_test.go

@@ -6,6 +6,7 @@ import (
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
 )
 
 const testDefaultClusterDomain = "cluster.local"
@@ -57,6 +58,47 @@ var _ = Describe("KeeperCluster", func() {
 })
 
 var _ = Describe("ClickHouseCluster", func() {
+	Describe("KeeperClusterNamespacedName", func() {
+		It("should default the keeper namespace to the ClickHouseCluster namespace", func() {
+			cluster := &ClickHouseCluster{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "test",
+					Namespace: "clickhouse-ns",
+				},
+				Spec: ClickHouseClusterSpec{
+					KeeperClusterRef: KeeperClusterReference{
+						Name: "keeper",
+					},
+				},
+			}
+
+			Expect(cluster.KeeperClusterNamespacedName()).To(Equal(types.NamespacedName{
+				Namespace: "clickhouse-ns",
+				Name:      "keeper",
+			}))
+		})
+
+		It("should use the explicit keeper namespace when provided", func() {
+			cluster := &ClickHouseCluster{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "test",
+					Namespace: "clickhouse-ns",
+				},
+				Spec: ClickHouseClusterSpec{
+					KeeperClusterRef: KeeperClusterReference{
+						Name:      "keeper",
+						Namespace: "keeper-ns",
+					},
+				},
+			}
+
+			Expect(cluster.KeeperClusterNamespacedName()).To(Equal(types.NamespacedName{
+				Namespace: "keeper-ns",
+				Name:      "keeper",
+			}))
+		})
+	})
+
 	Describe("HostnameByID", func() {
 		var cluster *ClickHouseCluster
 

config/crd/bases/clickhouse.com_clickhouseclusters.yaml

@@ -1113,20 +1113,25 @@ spec:
                 - name
                 type: object
               keeperClusterRef:
-                description: Reference to the KeeperCluster that is used for ClickHouse
-                  coordination.
+                description: |-
+                  Reference to the KeeperCluster that is used for ClickHouse coordination.
+                  When namespace is omitted, the ClickHouseCluster namespace is used.
                 properties:
                   name:
-                    default: ""
+                    description: Name of the KeeperCluster resource.
+                    maxLength: 63
+                    pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+                    type: string
+                  namespace:
                     description: |-
-                      Name of the referent.
-                      This field is effectively required, but due to backwards compatibility is
-                      allowed to be empty. Instances of this type with an empty value here are
-                      almost certainly wrong.
-                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      Namespace of the KeeperCluster resource.
+                      When omitted, the ClickHouseCluster namespace is used.
+                    maxLength: 63
+                    pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
                     type: string
+                required:
+                - name
                 type: object
-                x-kubernetes-map-type: atomic
               labels:
                 additionalProperties:
                   type: string

dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml

@@ -1116,20 +1116,25 @@ spec:
                 - name
                 type: object
               keeperClusterRef:
-                description: Reference to the KeeperCluster that is used for ClickHouse
-                  coordination.
+                description: |-
+                  Reference to the KeeperCluster that is used for ClickHouse coordination.
+                  When namespace is omitted, the ClickHouseCluster namespace is used.
                 properties:
                   name:
-                    default: ""
+                    description: Name of the KeeperCluster resource.
+                    maxLength: 63
+                    pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+                    type: string
+                  namespace:
                     description: |-
-                      Name of the referent.
-                      This field is effectively required, but due to backwards compatibility is
-                      allowed to be empty. Instances of this type with an empty value here are
-                      almost certainly wrong.
-                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      Namespace of the KeeperCluster resource.
+                      When omitted, the ClickHouseCluster namespace is used.
+                    maxLength: 63
+                    pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
                     type: string
+                required:
+                - name
                 type: object
-                x-kubernetes-map-type: atomic
               labels:
                 additionalProperties:
                   type: string

docs/api_reference.md

@@ -47,7 +47,7 @@ ClickHouseClusterSpec defines the desired state of ClickHouseCluster.
 |-------|------|-------------|----------|---------|
 | `replicas` | integer | Number of replicas in the single shard. | false | 3 |
 | `shards` | integer | Number of shards in the cluster. | false | 1 |
-| `keeperClusterRef` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#localobjectreference-v1-core) | Reference to the KeeperCluster that is used for ClickHouse coordination. | true |  |
+| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Reference to the KeeperCluster that is used for ClickHouse coordination.<br />When namespace is omitted, the ClickHouseCluster namespace is used. | true |  |
 | `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parameters passed to the ClickHouse pod spec. | false |  |
 | `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parameters passed to the ClickHouse container spec. | false |  |
 | `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Specification of persistent storage for ClickHouse data. | false |  |
@@ -243,6 +243,19 @@ kind: KeeperClusterList
 | `items` | [KeeperCluster](#keepercluster) array |  | true |  |
 
 
+## KeeperClusterReference
+
+KeeperClusterReference identifies the KeeperCluster used by a ClickHouseCluster.
+
+| Field | Type | Description | Required | Default |
+|-------|------|-------------|----------|---------|
+| `name` | string | Name of the KeeperCluster resource. | true |  |
+| `namespace` | string | Namespace of the KeeperCluster resource.<br />When omitted, the ClickHouseCluster namespace is used. | false |  |
+
+Appears in:
+- [ClickHouseClusterSpec](#clickhouseclusterspec)
+
+
 ## KeeperClusterSpec
 
 KeeperClusterSpec defines the desired state of KeeperCluster.

docs/configuration.md

@@ -56,9 +56,12 @@ Every ClickHouse cluster must reference a KeeperCluster for coordination:
 ```yaml
 spec:
   keeperClusterRef:
-    name: my-keeper  # Name of the KeeperCluster in the same namespace
+    name: my-keeper
+    # namespace: keeper-system  # Optional, defaults to the ClickHouseCluster namespace
 ```
 
+When `keeperClusterRef.namespace` is set, the operator must watch both namespaces. If `WATCH_NAMESPACE` is configured, include the ClickHouse and Keeper namespaces in that list.
+
 ## KeeperCluster Configuration
 
 ```yaml

docs/introduction.md

@@ -68,8 +68,8 @@ spec:
 
 ### ClickHouse Keeper is Required
 
-Every ClickHouseCluster requires a ClickHouse Keeper cluster for distributed coordination. 
-The Keeper cluster must be referenced in the ClickHouseCluster spec using `keeperClusterRef`.
+Every ClickHouseCluster requires a ClickHouse Keeper cluster for distributed coordination.
+The Keeper cluster must be referenced in the ClickHouseCluster spec using `keeperClusterRef`. By default the operator looks in the ClickHouseCluster namespace, but you can also set `keeperClusterRef.namespace` to point at a KeeperCluster in another watched namespace.
 
 ###  One-to-One Keeper Relationship
 

docs/styles/config/vocabularies/ClickHouse/accept.txt

@@ -1,7 +1,7 @@
 kubectl
 hostname
 CRDs
-namespace
+[Nn]amespaces?
 uncomment
 PVCs
 PDBs

internal/controller/clickhouse/controller.go

@@ -40,6 +40,17 @@ type ClusterController struct {
 	EnablePDB bool
 }
 
+const keeperClusterReferenceField = "clickhouse.com/keeperClusterReference"
+
+func keeperReferenceFieldValue(cluster *v1.ClickHouseCluster) []string {
+	keeperKey := cluster.KeeperClusterNamespacedName()
+	if keeperKey.Name == "" {
+		return nil
+	}
+
+	return []string{keeperKey.String()}
+}
+
 // +kubebuilder:rbac:groups=clickhouse.com,resources=clickhouseclusters,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=clickhouse.com,resources=clickhouseclusters/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=clickhouse.com,resources=clickhouseclusters/finalizers,verbs=update
@@ -156,6 +167,17 @@ func SetupWithManager(mgr ctrl.Manager, log controllerutil.Logger, checker *upgr
 		EnablePDB: enablePDB,
 	}
 
+	if err := mgr.GetFieldIndexer().IndexField(context.Background(), &v1.ClickHouseCluster{}, keeperClusterReferenceField, func(obj client.Object) []string {
+		cluster, ok := obj.(*v1.ClickHouseCluster)
+		if !ok {
+			return nil
+		}
+
+		return keeperReferenceFieldValue(cluster)
+	}); err != nil {
+		return fmt.Errorf("index ClickHouseCluster keeper reference: %w", err)
+	}
+
 	controllerBuilder := ctrl.NewControllerManagedBy(mgr).
 		For(&v1.ClickHouseCluster{}, builder.WithPredicates(predicate.Or(predicate.GenerationChangedPredicate{}, predicate.LabelChangedPredicate{}, predicate.AnnotationChangedPredicate{}))).
 		Watches(
@@ -191,20 +213,20 @@ func (cc *ClusterController) clickHouseClustersForKeeper(ctx context.Context, ob
 
 	// List all ClickHouseClusters that reference this KeeperCluster
 	var chList v1.ClickHouseClusterList
-	if err := cc.List(ctx, &chList, client.InNamespace(zk.Namespace)); err != nil {
+	if err := cc.List(ctx, &chList, client.MatchingFields{
+		keeperClusterReferenceField: zk.NamespacedName().String(),
+	}); err != nil {
 		return nil
 	}
 
 	var requests []reconcile.Request
 	for _, ch := range chList.Items {
-		if ch.Spec.KeeperClusterRef.Name == zk.Name {
-			requests = append(requests, reconcile.Request{
-				NamespacedName: types.NamespacedName{
-					Name:      ch.Name,
-					Namespace: ch.Namespace,
-				},
-			})
-		}
+		requests = append(requests, reconcile.Request{
+			NamespacedName: types.NamespacedName{
+				Name:      ch.Name,
+				Namespace: ch.Namespace,
+			},
+		})
 	}
 
 	return requests