fix: make cluster reference immutable on Database, Pooler, Publication, Subscription and ScheduledBackup (cloudnative-pg#10743)

leonardoce · armru · mnencia · web-flow · commit 14afc858bb8b · 2026-05-25T19:02:30.000+02:00
Add a CEL `self == oldSelf` validation rule to the `cluster` field of
the Database, Pooler, Publication, Subscription and ScheduledBackup
resources so that the target cluster cannot be changed after the
resource is created.

Repointing these objects at a different cluster has no well-defined
semantics and previously left the controllers in an inconsistent state;
rejecting the update at the API server makes the constraint explicit to
users.

Regenerate the affected CRD manifests and document the new constraint in
the corresponding user guide sections.

Signed-off-by: Leonardo Cecchi &lt;leonardo.cecchi@enterprisedb.com&gt;
Signed-off-by: Armando Ruocco &lt;armando.ruocco@enterprisedb.com&gt;
Signed-off-by: Marco Nenciarini &lt;marco.nenciarini@enterprisedb.com&gt;
Co-authored-by: Armando Ruocco &lt;armando.ruocco@enterprisedb.com&gt;
Co-authored-by: Marco Nenciarini &lt;marco.nenciarini@enterprisedb.com&gt;
diff --git a/api/v1/database_types.go b/api/v1/database_types.go
@@ -60,6 +60,7 @@ const (
 // +kubebuilder:validation:XValidation:rule="!has(self.icuRules) || self.localeProvider == 'icu'",message="icuRules is only available when localeProvider is set to `icu`"
 type DatabaseSpec struct {
 	// The name of the PostgreSQL cluster hosting the database.
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="cluster reference is immutable after creation"
 	ClusterRef corev1.LocalObjectReference `json:"cluster"`
 
 	// Ensure the PostgreSQL database is `present` or `absent` - defaults to "present".
diff --git a/api/v1/pooler_types.go b/api/v1/pooler_types.go
@@ -88,6 +88,7 @@ const (
 type PoolerSpec struct {
 	// This is the cluster reference on which the Pooler will work.
 	// Pooler name should never match with any cluster name within the same namespace.
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="cluster reference is immutable after creation"
 	Cluster LocalObjectReference `json:"cluster"`
 
 	// Type of service to forward traffic to. Default: `rw`.
diff --git a/api/v1/publication_types.go b/api/v1/publication_types.go
@@ -41,6 +41,7 @@ const (
 // PublicationSpec defines the desired state of Publication
 type PublicationSpec struct {
 	// The name of the PostgreSQL cluster that identifies the "publisher"
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="cluster reference is immutable after creation"
 	ClusterRef corev1.LocalObjectReference `json:"cluster"`
 
 	// The name of the publication inside PostgreSQL
diff --git a/api/v1/scheduledbackup_types.go b/api/v1/scheduledbackup_types.go
@@ -39,6 +39,7 @@ type ScheduledBackupSpec struct {
 	Schedule string `json:"schedule"`
 
 	// The cluster to backup
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="cluster reference is immutable after creation"
 	Cluster LocalObjectReference `json:"cluster"`
 
 	// Indicates which ownerReference should be put inside the created backup resources.<br />
diff --git a/api/v1/subscription_types.go b/api/v1/subscription_types.go
@@ -41,6 +41,7 @@ const (
 // SubscriptionSpec defines the desired state of Subscription
 type SubscriptionSpec struct {
 	// The name of the PostgreSQL cluster that identifies the "subscriber"
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="cluster reference is immutable after creation"
 	ClusterRef corev1.LocalObjectReference `json:"cluster"`
 
 	// The name of the subscription inside PostgreSQL
diff --git a/config/crd/bases/postgresql.cnpg.io_databases.yaml b/config/crd/bases/postgresql.cnpg.io_databases.yaml
@@ -87,6 +87,9 @@ spec:
                     type: string
                 type: object
                 x-kubernetes-map-type: atomic
+                x-kubernetes-validations:
+                - message: cluster reference is immutable after creation
+                  rule: self == oldSelf
               collationVersion:
                 description: |-
                   Maps to the `COLLATION_VERSION` parameter of `CREATE DATABASE`. This
diff --git a/config/crd/bases/postgresql.cnpg.io_poolers.yaml b/config/crd/bases/postgresql.cnpg.io_poolers.yaml
@@ -65,6 +65,9 @@ spec:
                 required:
                 - name
                 type: object
+                x-kubernetes-validations:
+                - message: cluster reference is immutable after creation
+                  rule: self == oldSelf
               deploymentStrategy:
                 description: The deployment strategy to use for pgbouncer to replace
                   existing pods with new ones
diff --git a/config/crd/bases/postgresql.cnpg.io_publications.yaml b/config/crd/bases/postgresql.cnpg.io_publications.yaml
@@ -71,6 +71,9 @@ spec:
                     type: string
                 type: object
                 x-kubernetes-map-type: atomic
+                x-kubernetes-validations:
+                - message: cluster reference is immutable after creation
+                  rule: self == oldSelf
               dbname:
                 description: |-
                   The name of the database where the publication will be installed in
diff --git a/config/crd/bases/postgresql.cnpg.io_scheduledbackups.yaml b/config/crd/bases/postgresql.cnpg.io_scheduledbackups.yaml
@@ -72,6 +72,9 @@ spec:
                 required:
                 - name
                 type: object
+                x-kubernetes-validations:
+                - message: cluster reference is immutable after creation
+                  rule: self == oldSelf
               immediate:
                 description: If the first backup has to be immediately start after
                   creation or not
diff --git a/config/crd/bases/postgresql.cnpg.io_subscriptions.yaml b/config/crd/bases/postgresql.cnpg.io_subscriptions.yaml
@@ -71,6 +71,9 @@ spec:
                     type: string
                 type: object
                 x-kubernetes-map-type: atomic
+                x-kubernetes-validations:
+                - message: cluster reference is immutable after creation
+                  rule: self == oldSelf
               dbname:
                 description: |-
                   The name of the database where the publication will be installed in
diff --git a/docs/src/backup.md b/docs/src/backup.md
@@ -243,6 +243,12 @@ The schedule `"0 0 0 * * *"` triggers a backup every day at midnight
 (00:00:00). In Kubernetes CronJobs, the equivalent expression would be `0 0 * * *`,
 since seconds are not supported.
 
+:::warning
+    The `spec.cluster` field is immutable after creation. To schedule backups
+    for a different `Cluster`, create a new `ScheduledBackup` resource instead
+    of updating an existing one.
+:::
+
 ### Backup Frequency and RTO
 
 :::tip[Hint]
diff --git a/docs/src/connection_pooling.md b/docs/src/connection_pooling.md
@@ -59,6 +59,12 @@ spec:
     The pooler name can't be the same as any cluster name in the same namespace.
 :::
 
+:::warning
+    The `spec.cluster` field is immutable after creation. To point a pooler at
+    a different `Cluster`, create a new `Pooler` resource instead of updating
+    an existing one.
+:::
+
 This example creates a `Pooler` resource called `pooler-example-rw`
 that's strictly associated with the Postgres `Cluster` resource called
 `cluster-example`. It points to the primary, identified by the read/write
diff --git a/docs/src/declarative_database_management.md b/docs/src/declarative_database_management.md
@@ -71,6 +71,12 @@ The `Database` object must reference a specific `Cluster`, determining where
 the database will be created. It is managed by the cluster's primary instance,
 ensuring the database is created or updated as needed.
 
+:::warning
+    The `spec.cluster` field is immutable after creation. To target a
+    different `Cluster`, create a new `Database` resource instead of updating
+    an existing one.
+:::
+
 :::info
     The distinction between `metadata.name` and `spec.name` allows multiple
     `Database` resources to reference databases with the same name across different
diff --git a/docs/src/logical_replication.md b/docs/src/logical_replication.md
@@ -149,6 +149,12 @@ The `Publication` object must reference a specific `Cluster`, determining where
 the publication will be created. It is managed by the cluster's primary instance,
 ensuring the publication is created or updated as needed.
 
+:::warning
+    The `spec.cluster` field is immutable after creation. To create a
+    publication on a different `Cluster`, create a new `Publication` resource
+    instead of updating an existing one.
+:::
+
 ### Reconciliation and Status
 
 After creating a `Publication`, CloudNativePG manages it on the primary
@@ -287,6 +293,12 @@ where the subscription will be managed. CloudNativePG ensures that the
 subscription is created or updated on the primary instance of the specified
 cluster.
 
+:::warning
+    The `spec.cluster` field is immutable after creation. To manage the
+    subscription on a different `Cluster`, create a new `Subscription`
+    resource instead of updating an existing one.
+:::
+
 ### Reconciliation and Status
 
 After creating a `Subscription`, CloudNativePG manages it on the primary
