Merge pull request #360 from percona/PG-1229-Improve-WAL-doc

PG-1229 Improved WAL encryption doc

documentation/docs/setup.md

@@ -90,9 +90,13 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
 
 ## WAL encryption configuration (tech preview)
 
-After you [enabled `pg_tde`](#enable-extension) and started the Percona Server for PostgreSQL, a principal key and a keyring for WAL are created. Now you need to instruct `pg_tde ` to encrypt WAL files by configuring WAL encryption. Here's how to do it:
+After you [enabled `pg_tde`](#enable-extension) and started the Percona Server for PostgreSQL, a principal key and internal keys for WAL encryption are created. They are stored in the data directory so that after WAL encryption is enabled, any process that requires access to WAL (a recovery or a checkpointer) can use them for decryption.
 
-1. Enable WAL level encryption using the `ALTER SYSTEM SET` command. You need the privileges of the superuser to run this command:
+Now you need to instruct `pg_tde ` to encrypt WAL files by configuring WAL encryption. Here's how to do it:
+
+### Enable WAL level encryption
+
+1.  Use the `ALTER SYSTEM SET` command. You need the privileges of the superuser to run this command:
 
     ```sql
     ALTER SYSTEM set pg_tde.wal_encrypt = on;
@@ -112,13 +116,19 @@ After you [enabled `pg_tde`](#enable-extension) and started the Percona Server f
        sudo systemctl restart postgresql-17
        ```
 
-3. We highly recommend you to create your own keyring and rotate the principal key. This is because the default principal key is created from the local keyfile and is stored unencrypted. 
+On the server start 
+
+### Rotate the principal key
+
+We highly recommend you to create your own keyring and rotate the principal key. This is because the default principal key is created from the local keyfile and is stored unencrypted. 
+
+Rotating the principal key means re-encrypting internal keys used for WAL encryption with the new principal key. This process doesn't stop the database operation meaning that reads and writes can take place as usual during key rotation. 
 
-    Set up the key provider for WAL encryption
+1. Set up the key provider for WAL encryption
 
     === "With HashiCorp Vault"
 
-        ```sql
+        ```
         SELECT pg_tde_add_key_provider_vault_v2('PG_TDE_GLOBAL','provider-name',:'secret_token','url','mount','ca_path');
         ``` 
 
@@ -136,17 +146,32 @@ After you [enabled `pg_tde`](#enable-extension) and started the Percona Server f
 
         This setup is intended for development and stores the keys unencrypted in the specified data file.    
 
-        ```sql
+        ```
         SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file');
         ```
 
-4. Rotate the principal key. Don't forget to specify the `PG_TDE_GLOBAL` constant to rotate only the principal key for WAL.
+2. Rotate the principal key. Don't forget to specify the `PG_TDE_GLOBAL` constant to rotate only the principal key for WAL.
 
-    ```sql
+    ```
     SELECT pg_tde_rotate_principal_key('PG_TDE_GLOBAL', 'new-principal-key', 'provider-name');
     ```
 
-Now all WAL files are encrypted for both encrypted and unencrypted tables.
+    Now all WAL files are encrypted for both encrypted and unencrypted tables. 
+   
+3. Verify the encryption by checking the `pg_tde.wal_encrypt` GUC (Grand Unified Configuration) parameter as follows: 
+
+    ```
+    SELECT name, setting FROM pg_settings WHERE name = 'pg_tde.wal_encrypt';
+    ```
+
+    ??? example "Sample output"
+
+        ```{.text .no-copy}
+
+                name        | setting
+        --------------------+---------
+         pg_tde.wal_encrypt | on
+        ```
 
 ## Next steps