docs: import CloudNativePG v1.28.4

Author: cnpg-bot

website/versioned_docs/version-1.28/appendixes/object_stores.md

@@ -168,6 +168,26 @@ spec:
         [...]
 ```
 
+:::note
+Recent changes to the [boto3 implementation](https://github.com/boto/boto3/issues/4392)
+of [Amazon S3 Data Integrity Protections](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)
+may lead to the `x-amz-content-sha256` error. If you encounter this issue, you
+can apply the following workaround by setting specific environment variables at
+the cluster level through `spec.env`:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  env:
+    - name: AWS_REQUEST_CHECKSUM_CALCULATION
+      value: when_required
+    - name: AWS_RESPONSE_CHECKSUM_VALIDATION
+      value: when_required
+```
+:::
+
 ### Using Object Storage with a private CA
 
 Suppose you configure an Object Storage provider which uses a certificate

website/versioned_docs/version-1.28/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]

website/versioned_docs/version-1.28/bootstrap.md

@@ -384,6 +384,16 @@ Objects in each list will be processed sequentially.
     leaving the cluster incomplete and requiring manual intervention.
 :::
 
+:::note
+These queries run with the standard `"$user", public` `search_path`, even
+though operator-issued connections otherwise pin a fixed `search_path` for
+security reasons.
+See [Schema resolution and `search_path` hardening](security.md#schema-resolution-and-search_path-hardening)
+for details.
+Schema-qualify object references if you need them to be independent of the
+`search_path`.
+:::
+
 :::info[Important]
     Ensure the existence of entries inside the ConfigMaps or Secrets specified
     in `postInitSQLRefs`, `postInitTemplateSQLRefs`, and
@@ -614,7 +624,7 @@ file on the source PostgreSQL instance:
 host replication streaming_replica all md5
 ```
 
-The following manifest creates a new PostgreSQL 18.3 cluster,
+The following manifest creates a new PostgreSQL 18.4 cluster,
 called `target-db`, using the `pg_basebackup` bootstrap method
 to clone an external PostgreSQL cluster defined as `source-db`
 (in the `externalClusters` array). As you can see, the `source-db`
@@ -629,7 +639,7 @@ metadata:
   name: target-db
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
+  imageName: ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
 
   bootstrap:
     pg_basebackup:
@@ -649,7 +659,7 @@ spec:
 ```
 
 All the requirements must be met for the clone operation to work, including
-the same PostgreSQL version (in our case 18.3).
+the same PostgreSQL version (in our case 18.4).
 
 #### TLS certificate authentication
 
@@ -665,7 +675,7 @@ in the same Kubernetes cluster.
     outside the Kubernetes cluster.
 :::
 
-The manifest defines a new PostgreSQL 18.3 cluster called `cluster-clone-tls`,
+The manifest defines a new PostgreSQL 18.4 cluster called `cluster-clone-tls`,
 which is bootstrapped using the `pg_basebackup` method from the `cluster-example`
 external cluster. The host is identified by the read/write service
 in the same cluster, while the `streaming_replica` user is authenticated
@@ -680,7 +690,7 @@ metadata:
   name: cluster-clone-tls
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
+  imageName: ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
 
   bootstrap:
     pg_basebackup:

website/versioned_docs/version-1.28/cloudnative-pg.v1.md

@@ -427,6 +427,24 @@ _Appears in:_
 | `secret` _[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)_ | Name of the secret containing the initial credentials for the<br />owner of the user database. If empty a new secret will be<br />created from scratch |  |  |  |
 
 
+#### CatalogComponentImage
+
+
+
+CatalogComponentImage is a named image entry for a non-PostgreSQL component.
+
+
+
+_Appears in:_
+
+- [ImageCatalogSpec](#imagecatalogspec)
+
+| Field | Description | Required | Default | Validation |
+| --- | --- | --- | --- | --- |
+| `key` _string_ | Key is the unique identifier for this image within the catalog. | True |  | MaxLength: 63 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br /> |
+| `image` _string_ | Image is the container image reference. | True |  |  |
+
+
 #### CatalogImage
 
 
@@ -634,6 +652,7 @@ _Appears in:_
 | --- | --- | --- | --- | --- |
 | `instances` _integer_ | The total number of PVC Groups detected in the cluster. It may differ from the number of existing instance pods. |  |  |  |
 | `readyInstances` _integer_ | The total number of ready instances in the cluster. It is equal to the number of ready instance pods. |  |  |  |
+| `selector` _string_ | Selector is the serialized form of the label selector that identifies<br />the pods managed by this cluster. Populated by the operator and exposed<br />through the scale sub-resource so an autoscaler (such as HPA or VPA)<br />can discover the managed instance pods. |  |  |  |
 | `instancesStatus` _object (keys:[PodStatus](#podstatus), values:string array)_ | InstancesStatus indicates in which status the instances are |  |  |  |
 | `instancesReportedState` _object (keys:[PodName](#podname), values:[InstanceReportedState](#instancereportedstate))_ | The reported state of the instances during the last reconciliation loop |  |  |  |
 | `managedRolesStatus` _[ManagedRoles](#managedroles)_ | ManagedRolesStatus reports the state of the managed roles in the cluster |  |  |  |
@@ -1180,6 +1199,7 @@ _Appears in:_
 | Field | Description | Required | Default | Validation |
 | --- | --- | --- | --- | --- |
 | `images` _[CatalogImage](#catalogimage) array_ | List of CatalogImages available in the catalog | True |  | MaxItems: 8 <br />MinItems: 1 <br /> |
+| `componentImages` _[CatalogComponentImage](#catalogcomponentimage) array_ | ComponentImages is a list of named images for components other than PostgreSQL<br />(e.g. pgbouncer). Keys must be unique within a catalog. |  |  | MaxItems: 32 <br /> |
 
 
 #### ImageInfo
@@ -1444,7 +1464,7 @@ _Appears in:_
 | Field | Description | Required | Default | Validation |
 | --- | --- | --- | --- | --- |
 | `byStatus` _object (keys:[RoleStatus](#rolestatus), values:string array)_ | ByStatus gives the list of roles in each state |  |  |  |
-| `cannotReconcile` _object (keys:string, values:string array)_ | CannotReconcile lists roles that cannot be reconciled in PostgreSQL,<br />with an explanation of the cause |  |  |  |
+| `cannotReconcile` _object (keys:string, values:string array)_ | CannotReconcile lists roles that cannot be reconciled, with an<br />explanation of the cause. Failures may originate in PostgreSQL<br />(e.g. dropping a role that owns objects) or in Kubernetes (e.g.<br />the referenced password Secret cannot be fetched). |  |  |  |
 | `passwordStatus` _object (keys:string, values:[PasswordState](#passwordstate))_ | PasswordStatus gives the last transaction id and password secret version for each managed role |  |  |  |
 
 
@@ -2351,7 +2371,7 @@ _Appears in:_
 | `name` _string_ | Name of the role | True |  |  |
 | `comment` _string_ | Description of the role |  |  |  |
 | `ensure` _[EnsureOption](#ensureoption)_ | Ensure the role is `present` or `absent` - defaults to "present" |  | present | Enum: [present absent] <br /> |
-| `passwordSecret` _[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)_ | Secret containing the password of the role (if present)<br />If null, the password will be ignored unless DisablePassword is set |  |  |  |
+| `passwordSecret` _[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)_ | Secret containing the password of the role (if present).<br />If null, the password will be ignored unless DisablePassword is set.<br />When set, the secret must follow the `kubernetes.io/basic-auth` format<br />and contain both a `username` and a `password` field. |  |  |  |
 | `connectionLimit` _integer_ | If the role can log in, this specifies how many concurrent<br />connections the role can make. `-1` (the default) means no limit. |  | -1 |  |
 | `validUntil` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)_ | Date and time after which the role's password is no longer valid.<br />When omitted, the password will never expire (default). |  |  |  |
 | `inRoles` _string array_ | List of one or more existing roles to which this role will be<br />immediately added as a new member. Default empty. |  |  |  |

website/versioned_docs/version-1.28/cnpg_i.md

@@ -94,6 +94,12 @@ TCP gRPC endpoint behind a Service, with **mTLS** for secure communication.
 Standalone plugins are discovered dynamically by watching for Services with the
 required labels and annotations — no operator restart is needed.
 
+When a standalone plugin's pods are rolled (for example, after upgrading its
+image), the operator detects the change through the EndpointSlices backing the
+plugin Service and reconciles every cluster using that plugin, so they start
+interacting with the new pods promptly instead of waiting for the periodic
+resync.
+
 Example Deployment:
 
 ```yaml

website/versioned_docs/version-1.28/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
@@ -192,15 +198,26 @@ GRANT CONNECT ON DATABASE postgres TO cnpg_pooler_pgbouncer;
 
 Create the lookup function for password verification. This function is created
 in the `postgres` database with `SECURITY DEFINER` privileges and is used by
-PgBouncer’s `auth_query` option:
+PgBouncer’s `auth_query` option. Because it runs as the function owner, its
+`search_path` is pinned to `pg_catalog, pg_temp` so that the function body
+cannot resolve operators or objects through a caller- or
+tenant-controlled `search_path`:
 
 ```sql
 CREATE OR REPLACE FUNCTION public.user_search(uname TEXT)
   RETURNS TABLE (usename name, passwd text)
-  LANGUAGE sql SECURITY DEFINER AS
+  LANGUAGE sql SECURITY DEFINER
+  SET search_path = pg_catalog, pg_temp AS
   'SELECT usename, passwd FROM pg_catalog.pg_shadow WHERE usename=$1;';
 ```
 
+:::note
+Clusters created with an earlier version of CloudNativePG carry a
+`user_search` function without the pinned `search_path`. The operator
+recreates the function with the `SET search_path` clause automatically
+during reconciliation when the cluster is upgraded.
+:::
+
 Restrict and grant permissions on the lookup function:
 
 ```sql

website/versioned_docs/version-1.28/database_import.md

@@ -24,8 +24,8 @@ As a result, the instructions in this section are suitable for both:
 - importing one or more databases from an existing PostgreSQL instance, even
   outside Kubernetes
 - importing the database from any PostgreSQL version to one that is either the
-  same or newer, enabling *major upgrades* of PostgreSQL (e.g. from version 13.x
-  to version 17.x)
+  same or newer, enabling *major upgrades* of PostgreSQL (e.g. from version 14.x
+  to version 18.x)
 
 :::warning
     When performing major upgrades of PostgreSQL you are responsible for making

website/versioned_docs/version-1.28/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
@@ -150,6 +156,11 @@ spec:
 Deleting this `Database` object will automatically remove the `two` database
 from the `cluster-example` cluster.
 
+On a replica cluster the database is read-only, so deleting a `Database` object
+releases its finalizer and removes the Kubernetes object without dropping the
+PostgreSQL database, even with `databaseReclaimPolicy: delete`. Dropping the
+database is left to the primary cluster, which owns it.
+
 ### Declaratively Setting `ensure: absent`
 
 To remove a database, set the `ensure` field to `absent` like in the following

website/versioned_docs/version-1.28/declarative_hibernation.md

@@ -57,7 +57,7 @@ $ kubectl cnpg status <cluster-name>
 Cluster Summary
 Name:              cluster-example
 Namespace:         default
-PostgreSQL Image:  ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
+PostgreSQL Image:  ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
 Primary instance:  cluster-example-2
 Status:            Cluster in healthy state 
 Instances:         3

website/versioned_docs/version-1.28/declarative_role_management.md

@@ -179,23 +179,74 @@ stringData:
   password: SCRAM-SHA-256$<iteration count>:<salt>$<StoredKey>:<ServerKey>
 ```
 
+:::warning
+    The example above uses `stringData:`, where Kubernetes encodes the value
+    for you, which is the safest path for pre-hashed passwords. If you must
+    use `data:`, encode the bytes exactly with `printf '%s' "$hash" | base64`
+    (or `echo -n "$hash" | base64`). A trailing newline from a naive
+    `echo "$hash" | base64` makes the value miss the SCRAM/MD5 shadow-format
+    check, so the operator falls back to treating it as cleartext and
+    re-hashes it, and login stops working.
+:::
+
 ### Safety when transmitting cleartext passwords
 
-While role passwords are safely managed in Kubernetes using Secrets,
-there is still a risk on the PostgreSQL side. If creating/altering a role with
-password, PostgreSQL may print the password as part of the query statement
-in some `postgres` logs, as mentioned in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html):
+Role passwords are safely managed in Kubernetes using Secrets, but the
+SQL path between the operator and PostgreSQL is also a concern. As noted
+in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html):
 
 > The password will be transmitted to the server in cleartext, and it might
 > also be logged in the client's command history or the server log
 
-CloudNativePG adds a safety layer by temporarily suppressing both statement
-logging (`log_statement`) and error statement logging
-(`log_min_error_statement`) for any CREATE or ALTER operation on a role with
-password, thus preventing leakage in both success and failure scenarios.
+CloudNativePG protects this path in two complementary ways:
+
+1. Before emitting `CREATE`/`ALTER ROLE ... PASSWORD '...'`, the operator
+   SCRAM-SHA-256 encodes any cleartext password operator-side (client-side
+   from PostgreSQL's point of view). This is the standard PostgreSQL
+   practice for keeping cleartext out of server logs and extensions like
+   `pg_stat_statements` or `pgaudit`, and is the same encoding that
+   `psql \password` and libpq's `PQencryptPasswordConn` perform. The
+   literal PostgreSQL receives is the SCRAM-SHA-256 verifier stored in
+   `pg_authid.rolpassword`. Passwords already provided in MD5 or
+   SCRAM-SHA-256 shadow form are forwarded unchanged.
+2. The same `CREATE`/`ALTER ROLE` statements are executed inside a
+   transaction that temporarily suppresses both statement logging
+   (`log_statement`) and error statement logging
+   (`log_min_error_statement`), preventing leakage to the PostgreSQL log
+   in both success and failure scenarios.
+
 The Status section of the cluster does not print the query statement for any
 managed role operation.
 
+#### Opting out of operator-side encoding
+
+If you need PostgreSQL (not the operator) to decide how the password is
+hashed (for example, on a cluster running `password_encryption = md5`),
+set the annotation `cnpg.io/passwordPassthrough: "enabled"` on the
+basic-auth Secret. The operator will then forward the password value
+verbatim.
+
+:::warning
+    The `cnpg.io/passwordPassthrough` annotation must be set on the
+    **basic-auth Secret** itself, not on the `Cluster` resource. Placing it
+    on the `Cluster` has no effect, and the operator will continue to apply
+    SCRAM-SHA-256 encoding to the password before sending it to PostgreSQL.
+:::
+
+The opt-in is per-Secret and applies to every basic-auth Secret the
+operator consumes (managed-role secrets, but also the superuser and
+application-user secrets), so a single cluster can mix passthrough
+secrets and operator-encoded secrets freely. The statement-logging
+suppression layer described above still applies in both modes.
+
+:::warning
+    With `cnpg.io/passwordPassthrough: "enabled"`, the operator forwards
+    the Secret's `password` value verbatim. If that value is cleartext (the
+    common case on a `password_encryption = md5` cluster), extensions such
+    as `pg_stat_statements` or `pgaudit` will observe it. This is the
+    expected trade-off for letting PostgreSQL choose the hash format.
+:::
+
 ## Unrealizable role configurations
 
 In PostgreSQL, in some cases, commands cannot be honored by the database and