Add information regarding key rotation during backups for pg_basebackup making servers fail to start (#550)

- add as known issue in release notes
- fix a broken link in features.md (not related to issue...)
- add to global key providers a warning about keyring provider with WAL
encrypt
- add new subtopic in Backup WAL about key rotations during backups for
file-based key providers

Based on PG-1895 description.

contrib/pg_tde/documentation/docs/features.md

@@ -17,7 +17,7 @@ The following features are available for the extension:
 * Single-tenancy support via a [global keyring provider](global-key-provider-configuration/set-principal-key.md)
 * [Multi-tenancy support](how-to/multi-tenant-setup.md)
 * Table-level granularity for encryption and access control
-* Multiple [Key management options](global-key-provider-configuration/index.md)
+* Multiple [Key management options](global-key-provider-configuration/overview.md)
 
 ## Next steps
 

contrib/pg_tde/documentation/docs/global-key-provider-configuration/overview.md

@@ -11,6 +11,9 @@ To use an external KMS with `pg_tde`, follow these two steps:
 !!! note
      While key files may be acceptable for **local** or **testing environments**, KMS integration is the recommended approach for production deployments.
 
+!!! warning
+    Do not rotate encryption keys while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay. Schedule rotations outside your backup windows and run a new full backup afterward.
+
 `pg_tde` has been tested with the following key providers:
 
 | KMS Provider       | Description                                           | Documentation |

contrib/pg_tde/documentation/docs/how-to/backup-wal-enabled.md

@@ -21,6 +21,22 @@ Also copy any external files referenced by your providers configuration (such as
     - The `-E` flag only works with the `-X stream` option (default). It is not compatible with `-X none` or `-X fetch`. For more information, see [the other WAL methods topic](#other-wal-methods).
     - The `-E` flag is only supported with the plain output format (`-F p`). It cannot be used with the tar output format (`-F t`).
 
+## Key rotation during backups
+
+!!! warning
+    Do not rotate SMGR or WAL encryption keys while `pg_basebackup` is running. Standbys or standalone clusters created from such backups may fail to start during WAL replay.
+
+Rotations during a base backup can leave the standby in an inconsistent state where it cannot retrieve the correct key history.
+
+For example, you may see errors such as:
+
+```sql
+FATAL: failed to retrieve principal key "database_keyXXXX" from key provider "providerYYYY"
+CONTEXT: WAL redo at ... ROTATE_PRINCIPAL_KEY ...
+```
+
+To ensure standby recoverability, plan key rotations outside backup windows or take a new full backup after rotation completes.
+
 ## Restore a backup created with WAL encryption
 
 When you want to restore a backup created with `pg_basebackup -E`:

contrib/pg_tde/documentation/docs/release-notes/release-notes-v2.0.md

@@ -30,14 +30,22 @@ Clusters that did not use WAL encryption in beta can be upgraded normally.
 
 ## Known issues
 
+* Rotating encryption keys while `pg_basebackup` is running may cause standbys or standalone clusters initialized from the backup to fail during WAL replay.
+
+    Avoid key rotations during backups. Run a new full backup after completing a rotation.
+
+* Using `pg_basebackup` with `--wal-method=fetch` produces warnings.
+
+    This behavior is expected and will be addressed in a future release.
+
 * The default `mlock` limit on Rocky Linux 8 for ARM64-based architectures equals the memory page size and is 64 Kb. This results in the child process with `pg_tde` failing to allocate another memory page because the max memory limit is reached by the parent process.
 
-To prevent this, you can change the `mlock` limit to be at least twice bigger than the memory page size:
+    To prevent this, you can change the `mlock` limit to be at least twice bigger than the memory page size:
 
-* temporarily for the current session using the `ulimit -l <value>` command.
-* set a new hard limit in the `/etc/security/limits.conf` file. To do so, you require the superuser privileges.
+    * temporarily for the current session using the `ulimit -l <value>` command.
+    * set a new hard limit in the `/etc/security/limits.conf` file. To do so, you require the superuser privileges.
 
-Adjust the limits with caution since it affects other processes running in your system.
+    Adjust the limits with caution since it affects other processes running in your system.
 
 ## Changelog