docs: import CloudNativePG v1.28.2

Author: cnpg-bot

website/versioned_docs/version-1.28/bootstrap.md

@@ -614,7 +614,7 @@ file on the source PostgreSQL instance:
 host replication streaming_replica all md5
 ```
 
-The following manifest creates a new PostgreSQL 18.1 cluster,
+The following manifest creates a new PostgreSQL 18.3 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 +629,7 @@ metadata:
   name: target-db
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie
+  imageName: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
 
   bootstrap:
     pg_basebackup:
@@ -649,7 +649,7 @@ spec:
 ```
 
 All the requirements must be met for the clone operation to work, including
-the same PostgreSQL version (in our case 18.1).
+the same PostgreSQL version (in our case 18.3).
 
 #### TLS certificate authentication
 
@@ -665,7 +665,7 @@ in the same Kubernetes cluster.
     outside the Kubernetes cluster.
 :::
 
-The manifest defines a new PostgreSQL 18.1 cluster called `cluster-clone-tls`,
+The manifest defines a new PostgreSQL 18.3 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 +680,7 @@ metadata:
   name: cluster-clone-tls
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie
+  imageName: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
 
   bootstrap:
     pg_basebackup:

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

@@ -443,6 +443,7 @@ _Appears in:_
 | --- | --- | --- | --- | --- |
 | `image` _string_ | The image reference | True |  |  |
 | `major` _integer_ | The PostgreSQL major version of the image. Must be unique within the catalog. | True |  | Minimum: 10 <br /> |
+| `extensions` _[ExtensionConfiguration](#extensionconfiguration) array_ | The configuration of the extensions to be added |  |  |  |
 
 
 #### CertificatesConfiguration
@@ -978,15 +979,37 @@ PostgreSQL extensions to the Cluster.
 
 _Appears in:_
 
+- [CatalogImage](#catalogimage)
 - [PostgresConfiguration](#postgresconfiguration)
 
 | Field | Description | Required | Default | Validation |
 | --- | --- | --- | --- | --- |
 | `name` _string_ | The name of the extension, required | True |  | MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9_]*[a-z0-9])?$` <br /> |
-| `image` _[ImageVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#imagevolumesource-v1-core)_ | The image containing the extension, required | True |  |  |
+| `image` _[ImageVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#imagevolumesource-v1-core)_ | The image containing the extension. |  |  |  |
 | `extension_control_path` _string array_ | The list of directories inside the image which should be added to extension_control_path.<br />If not defined, defaults to "/share". |  |  |  |
 | `dynamic_library_path` _string array_ | The list of directories inside the image which should be added to dynamic_library_path.<br />If not defined, defaults to "/lib". |  |  |  |
 | `ld_library_path` _string array_ | The list of directories inside the image which should be added to ld_library_path. |  |  |  |
+| `bin_path` _string array_ | A list of directories within the image to be appended to the<br />PostgreSQL process's `PATH` environment variable. |  |  |  |
+| `env` _[ExtensionEnvVar](#extensionenvvar) array_ | Env is a list of custom environment variables to be set in the<br />PostgreSQL process for this extension. It is the responsibility of the<br />cluster administrator to ensure the variables are correct for the<br />specific extension. Note that changes to these variables require<br />a manual cluster restart to take effect. |  |  |  |
+
+
+#### ExtensionEnvVar
+
+
+
+ExtensionEnvVar defines an environment variable for a specific extension
+image volume.
+
+
+
+_Appears in:_
+
+- [ExtensionConfiguration](#extensionconfiguration)
+
+| Field | Description | Required | Default | Validation |
+| --- | --- | --- | --- | --- |
+| `name` _string_ | Name of the environment variable to be injected into the<br />PostgreSQL process. | True |  | MinLength: 1 <br />Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$` <br /> |
+| `value` _string_ | Value of the environment variable. CloudNativePG performs a direct<br />replacement of this value, with support for placeholder expansion.<br />The $\{`image_root`\} placeholder resolves to the absolute mount path<br />of the extension's volume (e.g., `/extensions/my-extension`). This<br />is particularly useful for allowing applications or libraries to<br />locate specific directories within the mounted image.<br />Unrecognized placeholders are rejected. To include a literal $\{...\}<br />in the value, escape it as $$\{...\}. | True |  | MinLength: 1 <br /> |
 
 
 #### ExtensionSpec
@@ -1955,8 +1978,9 @@ _Appears in:_
 
 _Underlying type:_ _string_
 
-PrimaryUpdateMethod contains the method to use when upgrading
-the primary server of the cluster as part of rolling updates
+PrimaryUpdateMethod defines the method to use when upgrading
+the primary instance of the cluster as part of rolling updates.
+The default method is "restart"
 
 
 

website/versioned_docs/version-1.28/cnpg_i.md

@@ -41,7 +41,7 @@ CNPG-I is inspired by the Kubernetes
 The operator communicates with registered plugins using **gRPC**, following the
 [CNPG-I protocol](https://github.com/cloudnative-pg/cnpg-i/blob/main/docs/protocol.md).
 
-CloudNativePG discovers plugins **at startup**. You can register them in one of two ways:
+You can register plugins in one of two ways:
 
 - Sidecar container – run the plugin inside the operator’s Deployment
 - Standalone Deployment – run the plugin as a separate workload in the same
@@ -51,7 +51,9 @@ In both cases, the plugin must be packaged as a container image.
 
 ### Sidecar Container
 
-When running as a sidecar, the plugin must expose its gRPC server via a **Unix
+Sidecar plugins are discovered once at operator startup.
+
+The plugin must expose its gRPC server via a **Unix
 domain socket**. This socket must be placed in a directory shared with the
 operator container, mounted at the path set in `PLUGIN_SOCKET_DIR` (default:
 `/plugin`).
@@ -89,11 +91,8 @@ spec:
 Running a plugin as its own Deployment decouples its lifecycle from the
 operator’s and allows independent scaling. In this setup, the plugin exposes a
 TCP gRPC endpoint behind a Service, with **mTLS** for secure communication.
-
-:::warning
-    CloudNativePG does **not** discover plugins dynamically. If you deploy a new
-    plugin, you must **restart the operator** to detect it.
-:::
+Standalone plugins are discovered dynamically by watching for Services with the
+required labels and annotations — no operator restart is needed.
 
 Example Deployment:
 

website/versioned_docs/version-1.28/connection_pooling.md

@@ -380,8 +380,9 @@ The operator manages most of the [configuration options for PgBouncer](https://w
 allowing you to modify only a subset of them.
 
 :::warning
-    You are responsible for correctly setting the value of each option, as the
-    operator doesn't validate them.
+The operator passes these settings directly to PgBouncer without validation.
+To prevent configuration errors or crash loops, ensure each parameter is
+supported by your specific PgBouncer image version.
 :::
 
 These are the PgBouncer options you can customize, with links to the PgBouncer
@@ -394,7 +395,9 @@ are the ones directly set by PgBouncer.
 - [`cancel_wait_timeout`](https://www.pgbouncer.org/config.html#cancel_wait_timeout)
 - [`client_idle_timeout`](https://www.pgbouncer.org/config.html#client_idle_timeout)
 - [`client_login_timeout`](https://www.pgbouncer.org/config.html#client_login_timeout)
+- [`client_tls_ciphers`](https://www.pgbouncer.org/config.html#client_tls_ciphers)
 - [`client_tls_sslmode`](https://www.pgbouncer.org/config.html#client_tls_sslmode)
+- [`client_tls13_ciphers`](https://www.pgbouncer.org/config.html#client_tls13_ciphers) (1.25+)
 - [`default_pool_size`](https://www.pgbouncer.org/config.html#default_pool_size)
 - [`disable_pqexec`](https://www.pgbouncer.org/config.html#disable_pqexec)
 - [`dns_max_ttl`](https://www.pgbouncer.org/config.html#dns_max_ttl)
@@ -432,6 +435,7 @@ are the ones directly set by PgBouncer.
 - [`server_reset_query_always`](https://www.pgbouncer.org/config.html#server_reset_query_always)
 - [`server_round_robin`](https://www.pgbouncer.org/config.html#server_round_robin)
 - [`server_tls_ciphers`](https://www.pgbouncer.org/config.html#server_tls_ciphers)
+- [`server_tls13_ciphers`](https://www.pgbouncer.org/config.html#server_tls13_ciphers) (1.25+)
 - [`server_tls_protocols`](https://www.pgbouncer.org/config.html#server_tls_protocols)
 - [`server_tls_sslmode`](https://www.pgbouncer.org/config.html#server_tls_sslmode)
 - [`stats_period`](https://www.pgbouncer.org/config.html#stats_period)

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.1-system-trixie
+PostgreSQL Image:  ghcr.io/cloudnative-pg/postgresql:18.3-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,6 +179,23 @@ stringData:
   password: SCRAM-SHA-256$<iteration count>:<salt>$<StoredKey>:<ServerKey>
 ```
 
+### 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):
+
+> 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.
+The Status section of the cluster does not print the query statement for any
+managed role operation.
+
 ## Unrealizable role configurations
 
 In PostgreSQL, in some cases, commands cannot be honored by the database and

website/versioned_docs/version-1.28/image_catalog.md

@@ -44,7 +44,7 @@ spec:
     - major: 17
       image: ghcr.io/cloudnative-pg/postgresql:17.6-system-trixie
     - major: 18
-      image: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie
+      image: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
 ```
 
 **Example of a Cluster-Wide Catalog using `ClusterImageCatalog` Resource:**
@@ -63,7 +63,7 @@ spec:
     - major: 17
       image: ghcr.io/cloudnative-pg/postgresql:17.6-system-trixie
     - major: 18
-      image: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie
+      image: ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie
 ```
 
 A `Cluster` resource has the flexibility to reference either an `ImageCatalog`

website/versioned_docs/version-1.28/imagevolume_extensions.md

@@ -47,7 +47,7 @@ Extension images must be built according to the
 To use image volume extensions with CloudNativePG, you need:
 
 - **PostgreSQL 18 or later**, with support for `extension_control_path`.
-- **Kubernetes 1.33**, with the `ImageVolume` feature gate enabled.
+- **Kubernetes 1.35** or later (1.33 and 1.34 with the `ImageVolume` feature gate enabled).
 - **Container runtime with `ImageVolume` support**:
     - `containerd` v2.1.0 or later, or
     - `CRI-O` v1.31 or later.

website/versioned_docs/version-1.28/index.md

@@ -64,7 +64,7 @@ container images for both the operator and PostgreSQL (the operand).
 
 The CloudNativePG operator container images are available on the
 [`cloudnative-pg` project's GitHub Container Registry](https://github.com/cloudnative-pg/cloudnative-pg/pkgs/container/cloudnative-pg)
-in three different flavors:
+in two different flavors:
 
 - Debian 12 distroless
 - Red Hat UBI 9 micro (suffix `-ubi9`)
@@ -99,7 +99,7 @@ Three image flavors are available, each extending the previous one:
     Barman Cloud plugin, or another supported backup solution.
 :::
 
-By default, this version of CloudNativePG deploys `ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie`.
+By default, this version of CloudNativePG deploys `ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie`.
 
 All images are signed and shipped with SBOM and provenance attestations.
 Weekly automated builds ensure that critical vulnerabilities (CVEs) are promptly fixed.

website/versioned_docs/version-1.28/installation_upgrade.md

@@ -14,12 +14,12 @@ title: Installation and upgrades
 The operator can be installed like any other resource in Kubernetes,
 through a YAML manifest applied via `kubectl`.
 
-You can install the [latest operator manifest](https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.1.yaml)
+You can install the [latest operator manifest](https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.2.yaml)
 for this minor release as follows:
 
 ```sh
 kubectl apply --server-side -f \
-  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.1.yaml
+  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.2.yaml
 ```
 
 You can verify that with:
@@ -32,7 +32,7 @@ kubectl rollout status deployment \
 ### Using the `cnpg` plugin for `kubectl`
 
 You can use the `cnpg` plugin to override the default configuration options
-that are in the static manifests. 
+that are in the static manifests.
 
 For example, to generate the default latest manifest but change the watch
 namespaces to only be a specific namespace, you could run:
@@ -44,7 +44,7 @@ kubectl cnpg install generate \
 ```
 
 Please refer to ["`cnpg` plugin"](./kubectl-plugin.md#generation-of-installation-manifests) documentation
-for a more comprehensive example. 
+for a more comprehensive example.
 
 :::warning
     If you are deploying CloudNativePG on GKE and get an error (`... failed to
@@ -358,3 +358,110 @@ that apply declarative changes to enable or disable hibernation.
 The `hibernate status` command has been removed, as its purpose is now
 fulfilled by the standard `status` command.
 
+## Verifying release assets
+
+CloudNativePG cryptographically signs all official release assets. Verifying these
+signatures ensures the assets originate from the official repository and were
+published through our automated release workflow.
+
+:::info
+Refer to the ["Release integrity and supply chain" section](security.md#release-integrity-and-supply-chain)
+for more information.
+:::
+
+### Prerequisites
+
+- **Signature verification:** [cosign](https://github.com/sigstore/cosign) CLI
+- **SBOM and Provenance:** [Docker Buildx](https://docs.docker.com/build/install-buildx/)
+  (included in Docker Desktop and modern Docker versions)
+
+### Verifying the Operator YAML Deployment
+
+When installing via a direct YAML manifest, you should verify the manifest file
+using the corresponding bundle (the `.sigstore.json` file) provided on the
+[GitHub Release page](https://github.com/cloudnative-pg/cloudnative-pg/releases).
+
+Run the following command:
+
+```bash
+cosign verify-blob \
+  cnpg-{version}.yaml \
+  --bundle cnpg-{version}.sigstore.json \
+  --certificate-identity-regexp "^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"
+```
+
+#### Verifying SLSA provenance
+
+To verify a release binary, download both the artifact and the provenance file
+(`multiple.intoto.jsonl`) from the
+[GitHub release](https://github.com/cloudnative-pg/cloudnative-pg/releases),
+then run:
+
+```shell
+slsa-verifier verify-artifact <ARTIFACT> \
+  --provenance-path multiple.intoto.jsonl \
+  --source-uri github.com/cloudnative-pg/cloudnative-pg
+```
+
+### Verifying the operator container images
+
+Run the following command to verify the signature of the CloudNativePG operator
+images:
+
+```bash
+cosign verify ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
+  --certificate-identity-regexp="^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
+  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"
+```
+
+We provide OCI attestations for full transparency. To inspect the Software Bill
+of Materials (SBOM) or build provenance, use the `docker buildx imagetools`
+command:
+
+To view the Software Bill of Materials (SBOM) in SPDX format:
+
+```bash
+docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
+  --format '{{ json (index .SBOM "linux/amd64").SPDX }}'
+```
+
+To inspect the SLSA Provenance (build details):
+
+```bash
+docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
+  --format '{{ json (index .Provenance "linux/amd64").SLSA }}'
+```
+
+:::info
+Refer to ["Verifying SLSA provenance"](security.md#verifying-slsa-provenance)
+for SLSA Build Level 3 compliance verification.
+:::
+
+### Verifying PostgreSQL operand images
+
+CloudNativePG maintains container images for all supported PostgreSQL versions
+as part of the [`postgres-containers` project](https://github.com/cloudnative-pg/postgres-containers)
+(also called operand images).
+
+To verify the signature of a specific operand image:
+
+```bash
+cosign verify ghcr.io/cloudnative-pg/postgresql:{tag} \
+  --certificate-identity-regexp="^https://github.com/cloudnative-pg/postgres-containers/" \
+  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"
+```
+
+To view the Software Bill of Materials (SBOM) in SPDX format:
+
+```bash
+docker buildx imagetools inspect ghcr.io/cloudnative-pg/postgresql:{tag} \
+  --format '{{ json (index .SBOM "linux/amd64").SPDX }}'
+```
+
+To inspect the SLSA Provenance (Build details):
+
+```bash
+docker buildx imagetools inspect ghcr.io/cloudnative-pg/postgresql:{tag} \
+  --format '{{ json (index .Provenance "linux/amd64").SLSA }}'
+```