docs: import CloudNativePG main

Author: cnpg-bot

website/docs/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

website/docs/installation_upgrade.md

@@ -267,8 +267,66 @@ removed before installing the new one. This won't affect user data but
 only the operator itself.
 
 
+<!--
+### Upgrading to 1.30.0 or 1.29.2
+
+:::info[Important]
+    We strongly recommend that all CloudNativePG users upgrade to version
+    1.30.0, or at least to the latest stable version of your current minor release
+    (e.g., 1.29.2).
+:::
+
+Starting from versions 1.30.0 and 1.29.2, for security reasons,
+CloudNativePG SCRAM-SHA-256 encodes role passwords **operator-side**
+(client-side from PostgreSQL's point of view) before issuing
+`CREATE`/`ALTER ROLE` statements. As a result, the literal that reaches
+the PostgreSQL parser (and that extensions such as `pg_stat_statements`
+or `pgaudit` may observe) is the same hash that ends up in
+`pg_authid.rolpassword`, never the cleartext secret. The encoding is
+applied to every basic-auth `Secret` the operator consumes: the
+`postgres` superuser secret, the application-user secret, and any
+managed-role password secret. Passwords already supplied in MD5 or
+SCRAM-SHA-256 shadow form are passed through unchanged.
+
+Since PostgreSQL [14](https://www.postgresql.org/docs/release/14.0/),
+`password_encryption` defaults to `scram-sha-256`, so we do not expect
+existing installations to be affected by this change.
+
+If your cluster has explicitly overridden `password_encryption` to a
+value other than `scram-sha-256` (for example, `md5`) and you want
+PostgreSQL (not the operator) to decide how the password is hashed,
+opt out by setting the annotation `cnpg.io/passwordPassthrough: "enabled"`
+on each basic-auth `Secret` the operator consumes. The operator will
+then forward the password value verbatim, and PostgreSQL will encode it
+according to its own `password_encryption` GUC.
+
+:::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.
+:::
+
+:::warning
+    With `cnpg.io/passwordPassthrough: "enabled"` the operator forwards the
+    Secret's `password` value verbatim. If that value is cleartext, as is
+    common on `password_encryption = md5` clusters, extensions such as
+    `pg_stat_statements` or `pgaudit` will observe it.
+:::
+
+See ["Opting out of operator-side encoding"](declarative_role_management.md#opting-out-of-operator-side-encoding)
+for details.
+
+-->
+
 ### Upgrading to 1.29.1 or 1.28.3
 
+:::info[Important]
+    We strongly recommend that all CloudNativePG users upgrade to version
+    1.29.1, or at least to the latest stable version of your current minor release
+    (e.g., 1.28.x).
+:::
+
 Version 1.29.1 and 1.28.3 ship the fix for `CVE-2026-44477` /
 `GHSA-423p-g724-fr39`. The metrics exporter now authenticates as a
 dedicated `cnpg_metrics_exporter` role with `pg_monitor` privileges
@@ -283,14 +341,6 @@ the metrics exporter
 role"](monitoring.md#manually-creating-the-metrics-exporter-role) in
 the monitoring documentation.
 
-### Upgrading to 1.29.0 or 1.28.x
-
-:::info[Important]
-    We strongly recommend that all CloudNativePG users upgrade to version
-    1.29.0, or at least to the latest stable version of your current minor release
-    (e.g., 1.28.x).
-:::
-
 ### Upgrading to 1.27 from a previous minor version
 
 Version 1.27 introduces a change in the default behavior of the

website/docs/labels_annotations.md

@@ -201,6 +201,14 @@ CloudNativePG manages the following predefined annotations:
 `cnpg.io/operatorVersion`
 :   Version of the operator.
 
+`cnpg.io/passwordPassthrough`
+:   When set to `enabled` on a basic-auth `Secret` consumed by the
+    operator (superuser, application user, or a managed-role password
+    secret), the operator forwards the password value verbatim in the
+    `CREATE`/`ALTER ROLE` statement instead of SCRAM-SHA-256 encoding
+    it operator-side. PostgreSQL then encodes the value according to its
+    own `password_encryption` setting. See [Opting out of operator-side encoding](declarative_role_management.md#opting-out-of-operator-side-encoding).
+
 `cnpg.io/pgControldata`
 :   Output of the `pg_controldata` command. This annotation replaces the old,
     deprecated `cnpg.io/hibernatePgControlData` annotation.