chore: merge main and solve conflicts

Signed-off-by: Gabriele Quaresima <[email protected]>

.github/workflows/continuous-delivery.yml

@@ -37,7 +37,7 @@ env:
   GOLANG_VERSION: "1.23.x"
   KUBEBUILDER_VERSION: "2.3.1"
   KIND_VERSION: "v0.24.0"
-  ROOK_VERSION: "v1.15.2"
+  ROOK_VERSION: "v1.15.3"
   EXTERNAL_SNAPSHOTTER_VERSION: "v8.1.0"
   OPERATOR_IMAGE_NAME: "ghcr.io/${{ github.repository }}-testing"
   BUILD_PUSH_PROVENANCE: ""

.wordlist-en-custom.txt

@@ -500,6 +500,7 @@ allowPrivilegeEscalation
 allowVolumeExpansion
 amd
 angus
+anonymization
 api
 apiGroup
 apiGroups
@@ -795,6 +796,7 @@ http
 httpGet
 https
 hugepages
+icu
 ident
 imageCatalogRef
 imageName

api/v1/backup_funcs.go

@@ -24,6 +24,7 @@ import (
 	volumesnapshot "github.com/kubernetes-csi/external-snapshotter/client/v8/apis/volumesnapshot/v1"
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 	"k8s.io/utils/ptr"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
@@ -230,6 +231,17 @@ func (backup *Backup) GetVolumeSnapshotConfiguration(
 	return config
 }
 
+// EnsureGVKIsPresent ensures that the GroupVersionKind (GVK) metadata is present in the Backup object.
+// This is necessary because informers do not automatically include metadata inside the object.
+// By setting the GVK, we ensure that components such as the plugins have enough metadata to typecheck the object.
+func (backup *Backup) EnsureGVKIsPresent() {
+	backup.SetGroupVersionKind(schema.GroupVersionKind{
+		Group:   GroupVersion.Group,
+		Version: GroupVersion.Version,
+		Kind:    BackupKind,
+	})
+}
+
 // IsEmpty checks if the plugin configuration is empty or not
 func (configuration *BackupPluginConfiguration) IsEmpty() bool {
 	return configuration == nil || len(configuration.Name) == 0

api/v1/cluster_funcs.go

@@ -28,13 +28,13 @@ import (
 	"github.com/cloudnative-pg/machinery/pkg/image/reference"
 	"github.com/cloudnative-pg/machinery/pkg/log"
 	"github.com/cloudnative-pg/machinery/pkg/postgres/version"
+	"github.com/cloudnative-pg/machinery/pkg/stringset"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/resource"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/types"
 
 	"github.com/cloudnative-pg/cloudnative-pg/internal/configuration"
-	"github.com/cloudnative-pg/cloudnative-pg/pkg/stringset"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/system"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/utils"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/versions"

api/v1/cluster_funcs_test.go

@@ -22,12 +22,12 @@ import (
 
 	barmanCatalog "github.com/cloudnative-pg/barman-cloud/pkg/catalog"
 	"github.com/cloudnative-pg/machinery/pkg/postgres/version"
+	"github.com/cloudnative-pg/machinery/pkg/stringset"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/resource"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/utils/ptr"
 
-	"github.com/cloudnative-pg/cloudnative-pg/pkg/stringset"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/utils"
 
 	. "github.com/onsi/ginkgo/v2"

api/v1/cluster_webhook.go

@@ -27,6 +27,7 @@ import (
 	"github.com/cloudnative-pg/machinery/pkg/image/reference"
 	"github.com/cloudnative-pg/machinery/pkg/log"
 	"github.com/cloudnative-pg/machinery/pkg/postgres/version"
+	"github.com/cloudnative-pg/machinery/pkg/stringset"
 	"github.com/cloudnative-pg/machinery/pkg/types"
 	storagesnapshotv1 "github.com/kubernetes-csi/external-snapshotter/client/v8/apis/volumesnapshot/v1"
 	v1 "k8s.io/api/core/v1"
@@ -44,7 +45,6 @@ import (
 
 	"github.com/cloudnative-pg/cloudnative-pg/internal/configuration"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/postgres"
-	"github.com/cloudnative-pg/cloudnative-pg/pkg/stringset"
 	"github.com/cloudnative-pg/cloudnative-pg/pkg/utils"
 )
 

api/v1/database_types.go

@@ -42,6 +42,9 @@ type DatabaseSpec struct {
 
 	// The name inside PostgreSQL
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
+	// +kubebuilder:validation:XValidation:rule="self != 'postgres'",message="the name postgres is reserved"
+	// +kubebuilder:validation:XValidation:rule="self != 'template0'",message="the name template0 is reserved"
+	// +kubebuilder:validation:XValidation:rule="self != 'template1'",message="the name template1 is reserved"
 	Name string `json:"name"`
 
 	// The owner
@@ -57,6 +60,36 @@ type DatabaseSpec struct {
 	// +optional
 	Encoding string `json:"encoding,omitempty"`
 
+	// The locale (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="locale is immutable"
+	// +optional
+	Locale string `json:"locale,omitempty"`
+
+	// The locale provider (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="locale_provider is immutable"
+	// +optional
+	LocaleProvider string `json:"locale_provider,omitempty"`
+
+	// The LC_COLLATE (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="lc_collate is immutable"
+	// +optional
+	LcCollate string `json:"lc_collate,omitempty"`
+
+	// The LC_CTYPE (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="lc_ctype is immutable"
+	// +optional
+	LcCtype string `json:"lc_ctype,omitempty"`
+
+	// The ICU_LOCALE (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="icu_locale is immutable"
+	// +optional
+	IcuLocale string `json:"icu_locale,omitempty"`
+
+	// The ICU_RULES (cannot be changed)
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="icu_rules is immutable"
+	// +optional
+	IcuRules string `json:"icu_rules,omitempty"`
+
 	// True when the database is a template
 	// +optional
 	IsTemplate *bool `json:"isTemplate,omitempty"`

api/v1/pooler_webhook.go

@@ -20,15 +20,14 @@ import (
 	"fmt"
 
 	"github.com/cloudnative-pg/machinery/pkg/log"
+	"github.com/cloudnative-pg/machinery/pkg/stringset"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"k8s.io/apimachinery/pkg/util/validation/field"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/webhook"
 	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
-
-	"github.com/cloudnative-pg/cloudnative-pg/pkg/stringset"
 )
 
 var (

config/crd/bases/postgresql.cnpg.io_databases.yaml

@@ -93,15 +93,57 @@ spec:
                 x-kubernetes-validations:
                 - message: encoding is immutable
                   rule: self == oldSelf
+              icu_locale:
+                description: The ICU_LOCALE (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: icu_locale is immutable
+                  rule: self == oldSelf
+              icu_rules:
+                description: The ICU_RULES (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: icu_rules is immutable
+                  rule: self == oldSelf
               isTemplate:
                 description: True when the database is a template
                 type: boolean
+              lc_collate:
+                description: The LC_COLLATE (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: lc_collate is immutable
+                  rule: self == oldSelf
+              lc_ctype:
+                description: The LC_CTYPE (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: lc_ctype is immutable
+                  rule: self == oldSelf
+              locale:
+                description: The locale (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: locale is immutable
+                  rule: self == oldSelf
+              locale_provider:
+                description: The locale provider (cannot be changed)
+                type: string
+                x-kubernetes-validations:
+                - message: locale_provider is immutable
+                  rule: self == oldSelf
               name:
                 description: The name inside PostgreSQL
                 type: string
                 x-kubernetes-validations:
                 - message: name is immutable
                   rule: self == oldSelf
+                - message: the name postgres is reserved
+                  rule: self != 'postgres'
+                - message: the name template0 is reserved
+                  rule: self != 'template0'
+                - message: the name template1 is reserved
+                  rule: self != 'template1'
               owner:
                 description: The owner
                 type: string

docs/src/bootstrap.md

@@ -389,44 +389,59 @@ to the ["Recovery" section](recovery.md).
 
 ### Bootstrap from a live cluster (`pg_basebackup`)
 
-The `pg_basebackup` bootstrap mode lets you create a new cluster (*target*) as
-an exact physical copy of an existing and **binary compatible** PostgreSQL
-instance (*source*), through a valid *streaming replication* connection.
-The source instance can be either a primary or a standby PostgreSQL server.
+The `pg_basebackup` bootstrap mode allows you to create a new cluster
+(*target*) as an exact physical copy of an existing and **binary-compatible**
+PostgreSQL instance (*source*) managed by CloudNativePG, using a valid
+*streaming replication* connection. The source instance can either be a primary
+or a standby PostgreSQL server. It’s crucial to thoroughly review the
+requirements section below, as the pros and cons of PostgreSQL physical
+replication fully apply.
+
+The primary use cases for this method include:
+
+- Reporting and business intelligence clusters that need to be regenerated
+  periodically (daily, weekly)
+- Test databases containing live data that require periodic regeneration
+  (daily, weekly, monthly) and anonymization
+- Rapid spin-up of a standalone replica cluster
+- Physical migrations of CloudNativePG clusters to different namespaces or
+  Kubernetes clusters
 
-The primary use case for this method is represented by **migrations** to CloudNativePG,
-either from outside Kubernetes or within Kubernetes (e.g., from another operator).
+!!! Important
+    Avoid using this method, based on physical replication, to migrate an
+    existing PostgreSQL cluster outside of Kubernetes into CloudNativePG unless you
+    are completely certain that all requirements are met and the operation has been
+    thoroughly tested. The CloudNativePG community does not endorse this approach
+    for such use cases and recommends using logical import instead. It is
+    exceedingly rare that all requirements for physical replication are met in a
+    way that seamlessly works with CloudNativePG.
 
 !!! Warning
-    The current implementation creates a *snapshot* of the origin PostgreSQL
-    instance when the cloning process terminates and immediately starts
-    the created cluster. See ["Current limitations"](#current-limitations) below for details.
-
-Similar to the case of the `recovery` bootstrap method, once the clone operation
-completes, the operator will take ownership of the target cluster, starting from
-the first instance. This includes overriding some configuration parameters, as
-required by CloudNativePG, resetting the superuser password, creating
-the `streaming_replica` user, managing the replicas, and so on. The resulting
-cluster will be completely independent of the source instance.
+    In its current implementation, this method clones the source PostgreSQL
+    instance, thereby creating a *snapshot*. Once the cloning process has finished,
+    the new cluster is immediately started.
+    Refer to ["Current limitations"](#current-limitations) for more details.
+
+Similar to the `recovery` bootstrap method, once the cloning operation is
+complete, the operator takes full ownership of the target cluster, starting
+from the first instance. This includes overriding certain configuration
+parameters as required by CloudNativePG, resetting the superuser password,
+creating the `streaming_replica` user, managing replicas, and more. The
+resulting cluster operates independently from the source instance.
 
 !!! Important
-    Configuring the network between the target instance and the source instance
-    goes beyond the scope of CloudNativePG documentation, as it depends
-    on the actual context and environment.
+    Configuring the network connection between the target and source instances
+    lies outside the scope of CloudNativePG documentation, as it depends heavily on
+    the specific context and environment.
 
-The streaming replication client on the target instance, which will be
-transparently managed by `pg_basebackup`, can authenticate itself on the source
-instance in any of the following ways:
+The streaming replication client on the target instance, managed transparently
+by `pg_basebackup`, can authenticate on the source instance using one of the
+following methods:
 
-1. via [username/password](#usernamepassword-authentication)
-2. via [TLS client certificate](#tls-certificate-authentication)
+1. [Username/password](#usernamepassword-authentication)
+2. [TLS client certificate](#tls-certificate-authentication)
 
-The latter is the recommended one if you connect to a source managed
-by CloudNativePG or configured for TLS authentication.
-The first option is, however, the most common form of authentication to a
-PostgreSQL server in general, and might be the easiest way if the source
-instance is on a traditional environment outside Kubernetes.
-Both cases are explained below.
+Both authentication methods are detailed below.
 
 #### Requirements
 
@@ -650,7 +665,7 @@ instance using a second connection (see the `--wal-method=stream` option for
 Once the backup is completed, the new instance will be started on a new timeline
 and diverge from the source.
 For this reason, it is advised to stop all write operations to the source database
-before migrating to the target database in Kubernetes.
+before migrating to the target database.
 
 !!! Important
     Before you attempt a migration, you must test both the procedure

docs/src/cloudnative-pg.v1.md

@@ -2314,6 +2314,48 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-
    <p>The encoding (cannot be changed)</p>
 </td>
 </tr>
+<tr><td><code>locale</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The locale (cannot be changed)</p>
+</td>
+</tr>
+<tr><td><code>locale_provider</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The locale provider (cannot be changed)</p>
+</td>
+</tr>
+<tr><td><code>lc_collate</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The LC_COLLATE (cannot be changed)</p>
+</td>
+</tr>
+<tr><td><code>lc_ctype</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The LC_CTYPE (cannot be changed)</p>
+</td>
+</tr>
+<tr><td><code>icu_locale</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The ICU_LOCALE (cannot be changed)</p>
+</td>
+</tr>
+<tr><td><code>icu_rules</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>The ICU_RULES (cannot be changed)</p>
+</td>
+</tr>
 <tr><td><code>isTemplate</code><br/>
 <i>bool</i>
 </td>

docs/src/samples/database-example-icu.yaml

@@ -0,0 +1,16 @@
+# NOTE: this manifest will only work properly if the Postgres version supports
+# ICU locales and rules (version 16 and newer)
+apiVersion: postgresql.cnpg.io/v1
+kind: Database
+metadata:
+  name: db-icu
+spec:
+  name: declarative-icu
+  owner: app
+  encoding: UTF8
+  locale_provider: icu
+  icu_locale: en
+  icu_rules: fr
+  template: template0
+  cluster:
+    name: cluster-example