Merge pull request #5751 from EnterpriseDB/BA/TDE-with-CMK

TDE on BigAnimal with Customer Managed Keys

product_docs/docs/biganimal/release/administering_cluster/projects.mdx

@@ -88,18 +88,21 @@ To delete a project that you created:
 1. Go to **Settings** on the left-side navigation.
 1. From the **Settings** list, select **Security**.
 1. Select **Add a key**. 
-1. On the **Add a key** page, select:
-   - Select the **Provider & Region**
-   - Select **Next**
-   - Enter AWS Key Management System ARN
-   - Enter a friendly name for your key
-   - Select **Finish**
+1. On the **Add a key** page, select the **Cloud Service Provider**. 
+1. Select the **Region** for the key. The interface only displays the regions available in the cloud account you configured.
+1. Complete the remaining fields according to your cloud provider. 
+1. Select **Add Key** to finalize the configuration.
 
-Now, use this TDE key to create a cluster. For more information, see [Creating a cluster](/biganimal/release/getting_started/creating_a_cluster/#security).
+!!!note Note for GCP keys
+   If the key you added was created in a different Google Cloud Platform account than the TDE-enabled cluster you want to create, ensure you enable the [Cloud KMS API](https://cloud.google.com/kms/docs/create-encryption-keys#before-you-begin) in the Google console before assigning it to your cluster in BigAnimal.
+
+Now, use this TDE key to [create a cluster](/biganimal/release/getting_started/creating_a_cluster/#security).
+
+For more information about TDE support, see [Transparent Data Encryption](../overview/03_security#your-own-encryption-key---transparent-data-encryption-tde)
 
 ## Deleting a TDE key 
 
-1. From the Projects pageXOffset, select an existing project.
+1. From the Projects page, select an existing project.
 
 1. Go to **Settings** on the left-side navigation.
 

product_docs/docs/biganimal/release/getting_started/creating_a_cluster/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Creating a cluster"
 description: Describes cluster creation options
+deepToC: true
 redirects:
   #adding hierarchy to the structure (Creating a Cluster topic nows has a child topic) so created a folder and moved the contents from 03_create_cluster to index.mdx
   - ../03_create_cluster/
@@ -216,16 +217,86 @@ Enable **Superuser Access** to grant superuser privileges to the edb_admin role.
 
 ### Security 
 
-Enable **Transparent Data Encryption (TDE)** to use your own encryption key. This option is available for EDB Postgres Advanced Server and EDB Postgres Extended Server for version 15 and later on AWS. Select an encryption key from your project and region to encrypt the cluster with TDE.
+Enable **Transparent Data Encryption (TDE)** to use your own encryption key. This option is available for EDB Postgres Advanced Server and EDB Postgres Extended Server for version 15 and later. Select an encryption key from your project and region to encrypt the cluster with TDE. To learn more about TDE support, see [Transparent Data Encryption](../../overview/03_security/#your-own-encryption-key---transparent-data-encryption-tde).
 
 !!!Note "Important"
-- To enable and use TDE for cluster, the encryption key must be enabled and added at the project level. For more information, see [Adding a TDE key at project level](../../administering_cluster/projects.mdx/#adding-a-tde-key).
-- If the TDE enabled cluster creation is in progress and the process is waiting providing **Encryption Key Error** next to the cluster name on the clusters page:
-  - Select the cluster name and go to the cluster's home page.
-  - See the **Action required: grant key permissions to activate the cluster** on the cluster's overview tab.
-  - Copy the **Principal** and add it to your key policy to provide **kms:Encrypt** and **kms:Decrypt** permission. 
+- To enable and use TDE for a cluster, the encryption key must be enabled and added at the project level before creating a cluster. 
+  To add a key, see [Adding a TDE key at project level](../../administering_cluster/projects.mdx/#adding-a-tde-key).
+- To enable and use TDE for a cluster, you must complete the configuration on the platform of your key management provider after creating a cluster. See [Completing the TDE configuration](#completing-the-TDE-configuration) for more information.
 !!!
 
+#### Completing the TDE configuration
+
+After you create the cluster in the BigAnimal console, the UI will display the **Waiting for access to encryption key** state. To complete the configuration and enable the key sync between BigAnimal and the key management platform you must grant encrypt and decrypt permissions to your key:
+
+1.  In BigAnimal, select the cluster name and access the cluster's page. See the **Action required: grant key permissions to activate the cluster**.
+
+1.  Copy the **Principal** identifier (AWS), **service account** (GCP) or **MSI Workload Identity** (Azure) to your clipboard. 
+
+1.  Follow the on-screen guide to grant encrypt and decrypt permissions to your key. Here is additional information in case you require further guidance:
+
+    <details><summary>AWS</summary>
+
+    1.  Copy the **Principal** identifier to your clipboard. 
+    1.  Go to the AWS console, and navigate to the **Key Management Service**
+    1.  Select **Customer-managed keys**, and **Edit policy** for your key.
+    1.  Append a new policy statement where the `Principal.AWS` field equals the **Principal** identifier you copied to    your clipboard and where the `Principal.Action` field contains **kms:Encrypt** and **kms:Decrypt** permissions. 
+
+        This example contains the default AWS policy statement and the BigAnimal policy statement that corresponds to the TDE configuration.  
+
+        ```
+        {
+             "Version": "2012-10-17",
+             "Id": "key-consolepolicy-3",
+             "Statement": [
+                 {
+                     "Sid": "Enable IAM User Permissions",
+                     "Effect": "Allow",
+                     "Principal": {
+                         "AWS": "arn:aws:iam::<aws_project_id>:root"
+                     },
+                     "Action": "kms:*",
+                     "Resource": "*"
+                 },
+                 {
+                     "Sid": "Enable TDE on cluster ExampleCluster",
+                     "Effect": "Allow",
+                     "Principal": {
+                         "AWS": "arn:aws:iam::<aws_project_id>:role/<pg_cluster_role>"
+                     },
+                     "Action": [
+                         "kms:Encrypt",
+                         "kms:Decrypt"
+                     ],
+                     "Resource": "*"
+                 }
+             ]
+         }
+        ```
+
+    </details>
+
+    <details><summary>GCP</summary>
+
+    1.  Copy the **service account** to your clipboard.
+    1.  Go to the Google Cloud console, select **Security**, **VIEW BY PRINCIPALS**, **GRANT ACCESS** for your key.
+    1.  Paste the service account into the **New principals** field.
+    1.  Assign the `Cloud KMS CryptoKey Decrypter` and `Cloud KMS CryptoKey Encrypter` roles and save. 
+
+    </details>
+
+    <details><summary>Azure</summary>
+
+    1.  Copy the **MSI Workload Identity** to your clipboard. 
+    1.  Got to the Microsoft Azure console, and navigate to **Key vaults**. 
+    1.  Select the key, go to **Access configuration** and set the **Permission model** to **Vault access policy**.
+    1.  Select **Access policies**, and **Create**.
+    1.  In **Permissions**, select **Encrypt** and **Decrypt**.
+    1.  In **Principal**, paste the MSI Workload Identity you copied to your clipboard and finish creating the policy.
+
+    </details>
+
+
 ## What’s next
 
 After you create your cluster, use these resources to learn about cluster use and management:

product_docs/docs/biganimal/release/overview/03_security/index.mdx

@@ -1,28 +1,73 @@
 ---
 title: "Security"
+deepToC: true
 ---
 
 BigAnimal runs in your own cloud account or BigAnimal's cloud account. Every BigAnimal cluster is logically isolated from other BigAnimal clusters, but the security properties of the system are different in each [deployment option](/biganimal/release/planning/deployment_options). The key security features are:
 
--   **Data isolation:** With both deployment options, data is fully isolated between separate clusters. No two BigAnimal clusters share a Postgres process, virtual machine, or storage volume. The implementation of this isolation depends on the deployment option.
-    -   **Your own cloud account:** Clusters are installed and managed on virtual machines and storage volumes deployed by BigAnimal on your behalf in your cloud environment. Complete segregation of your data is assured. Your data never leaves your cloud account, and your clusters don't share network segments with other customers' clusters.
-    -   **BigAnimal's cloud account:** BigAnimal deploys cloud infrastructure in accounts owned by BigAnimal. Every cluster is assigned a dedicated set of virtual machines and storage volumes, and these resources are never reused by BigAnimal across multiple clusters. Two clusters can share the same network segment, but access to the system is limited to prevent communication between clusters in the BigAnimal infrastructure.
+## Data isolation  
 
--   **Granular access control:** With both deployment options, you can use single sign-on (SSO) and define your own sets of roles and role-based access control (RBAC) policies to manage your individual cloud environments. See [Managing portal access](../../administering_cluster/01_portal_access/) for more information. 
+**Data isolation:** With both deployment options, data is fully isolated between separate clusters. No two BigAnimal clusters share a Postgres process, virtual machine, or storage volume. The implementation of this isolation depends on the deployment option.
 
--   **Data encryption:** 
-    - **BigAnimal's encryption** - All data in BigAnimal is encrypted in motion and at rest. Network traffic is encrypted using Transport Layer Security (TLS) v1.2 or greater. Data at rest is encrypted using AES with 256-bit keys. Data encryption keys are envelope encrypted, and the wrapped data encryption keys are securely stored in a key management system. When you use your own cloud account, encryption keys never leave your cloud environment.
-    - **Your own encryption key** - Optionally enable Transparent Data Encryption (TDE) at the database level on BigAnimal's cloud account and on AWS. You can't enable TDE on existing clusters. You can enable TDE, only while creating a cluster. To enable TDE, use your own encryption keys. Connect the encryption keys to BigAnimal at the project level and select those keys to encrypt the databases. You can't disable TDE on TDE-enabled clusters. 
+-   **Your own cloud account:** Clusters are installed and managed on virtual machines and storage volumes deployed by BigAnimal on your behalf in your cloud environment. Complete segregation of your data is assured. Your data never leaves your cloud account, and your clusters don't share network segments with other customers' clusters.
 
-    !!!note
-    Enabling TDE using your own encryption key is supported on EDB Postgres Advanced Server versions 15 and later. The process of encryption and decryption adds additional overhead in terms of CPU and RAM consumption, performance, and for managing keys for faraway replicas.
-    !!!
--   **Portal audit logging:** Activities in the portal, such as those related to user roles, organization updates, and cluster creation and deletion, are tracked and viewed in the activity log.  
+-   **BigAnimal's cloud account:** BigAnimal deploys cloud infrastructure in accounts owned by BigAnimal. Every cluster is assigned a dedicated set of virtual machines and storage volumes, and these resources are never reused by BigAnimal across multiple clusters. Two clusters can share the same network segment, but access to the system is limited to prevent communication between clusters in the BigAnimal infrastructure.
 
--   **Database logging and auditing:** Functionality to track and analyze database activities is enabled automatically. For PostgreSQL, the PostgreSQL Audit Extension (pgAudit) is enabled for you when deploying a Postgres cluster. For EDB Postgres Advanced Server and EDB Postgres Extended Server, the EDB Audit extension (edb_audit) is enabled for you. 
-    -   **pgAudit:** The classes of statements being logged for pgAudit are set globally on a cluster with `pgaudit.log = 'write,ddl'`. The following statements made on tables are logged by default when the cluster type is PostgreSQL: `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, AND `COPY`. All `DDL` is logged. 
+## Granular access control
 
--   **Database cluster permissions:** With both deployment options, managing database cluster permissions is your responsibility. The edb_admin user created during the cluster creation process is granted superuser-like permissions, including the CREATEDB and CREATEROLE database roles. We recommend using the edb_admin user to create a new application user and new application database for further isolation. See [Managing Postgres access](../../using_cluster/01_postgres_access/) for more information.
+With both deployment options, you can use single sign-on (SSO) and define your own sets of roles and role-based access control (RBAC) policies to manage your individual cloud environments. See [Managing portal access](../../administering_cluster/01_portal_access/) for more information. 
+
+## Data encryption
+
+### BigAnimal's encryption
+
+All data in BigAnimal is encrypted in motion and at rest. Network traffic is encrypted using Transport Layer Security (TLS) v1.2 or greater. Data at rest is encrypted using AES with 256-bit keys. Data encryption keys are envelope encrypted, and the wrapped data encryption keys are securely stored in a key management system. When you use your own cloud account, encryption keys never leave your cloud environment.
+
+### Your own encryption key - Transparent Data Encryption (TDE)
+
+Optionally enable Transparent Data Encryption (TDE) at the database level on BigAnimal's cloud account, on AWS, GCP or Azure. TDE encrypts all data files, the write-ahead log (WAL) and temporary files used during query processing and database system operations. 
+
+You can't enable nor disable TDE on existing clusters. To enable TDE, first connect the encryption keys to BigAnimal at the project level, and then select those keys while creating a cluster. 
+
+EDB supports enabling TDE with your own encryption key on Single Node and Primary/Standby High Availability deployments running EDB Postgres Advanced Server or EDB Postgres Extended Server versions 15 and later.
+Both the key and cluster must be in the same region and hosted by the same underlying cloud provider. 
+
+This overview shows the supported cluster-to-key combinations: 
+
+|                             | AWS cluster (BYOA) | AWS cluster (BAH) | GCP cluster (BYOA) | GCP cluster (BAH) | Azure cluster (BYOA) | Azure cluster (BAH) |
+|-----------------------------|--------------------|-------------------|--------------------|-------------------|----------------------|---------------------|
+| AWS Key Management Service  | ✓            | ✓           | ✗            | ✗           | ✗              | ✗             |
+| Google Cloud Key Management | ✗            | ✗           | ✓            | ✓           | ✗              | ✗             |
+| Azure Key Vault             | ✗            | ✗           | ✗            | ✗           | ✓              | ✗             |
+
+
+**BYOA or Bring your own account:** BigAnimal deploys the cluster on your own cloud provider account.
+
+**BAH or BigAnimal hosted:** BigAnimal deploys the cluster on a cloud provider account owned and managed by EDB.   
+
+!!!note
+   The process of encryption and decryption adds additional overhead in terms of CPU and RAM consumption, performance, and for managing keys for faraway replicas.
+!!!
+
+**To enable TDE**:
+
+- Before you create a TDE-enabled cluster, you must [add a TDE key](../../administering_cluster/projects##adding-a-tde-key).
+
+- See [Creating a new cluster - Security](../../getting_started/creating_a_cluster#security) to enable a TDE key during the cluster creation.
+
+## Portal audit logging 
+
+Activities in the portal, such as those related to user roles, organization updates, and cluster creation and deletion, are tracked and viewed in the activity log.  
+
+## Database logging and auditing
+
+Functionality to track and analyze database activities is enabled automatically. For PostgreSQL, the PostgreSQL Audit Extension (pgAudit) is enabled for you when deploying a Postgres cluster. For EDB Postgres Advanced Server and EDB Postgres Extended Server, the EDB Audit extension (edb_audit) is enabled for you. 
+
+- **pgAudit:** The classes of statements being logged for pgAudit are set globally on a cluster with `pgaudit.log = 'write,ddl'`. The following statements made on tables are logged by default when the cluster type is PostgreSQL: `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, AND `COPY`. All `DDL` is logged. 
+
+## Database cluster permissions
+
+With both deployment options, managing database cluster permissions is your responsibility. The edb_admin user created during the cluster creation process is granted superuser-like permissions, including the CREATEDB and CREATEROLE database roles. We recommend using the edb_admin user to create a new application user and new application database for further isolation. See [Managing Postgres access](../../using_cluster/01_postgres_access/) for more information.
 
 ## See also 
 

product_docs/docs/biganimal/release/using_cluster/05a_deleting_your_cluster.mdx

@@ -30,7 +30,7 @@ You can restore your deleted cluster for as long as the backup is available.
     When the process completes, the restored cluster is available on the [Clusters](https://portal.biganimal.com/clusters) page.
 
 !!! note
-To restore a TDE enabled cluster, the TDE key material must match with source cluster encryption key material. In case a different key material is used the restore operation fails.
+To restore a TDE-enabled cluster, the TDE key material must match the source cluster encryption key material. If a different key material is used, the restore operation will fail.
 
-We recommend, not to enable TDE while restoring a cluster, if the source cluster is a non-TDE cluster.
+EDB does not support enabling TDE when restoring a non-TDE cluster.
 !!!

product_docs/docs/biganimal/release/using_cluster/managing_replicas.mdx

@@ -34,7 +34,6 @@ You can create faraway replicas in any active regions in your cloud. There's no
 
    Under the **Backups** section, change the default replica backup retention period of 30 days using the **Retention Time** controls. You can configure the retention period as follows:
    - 1–180 days
-
    - 1–25 weeks
    - 1–6 months
 
@@ -53,9 +52,9 @@ You can create faraway replicas in any active regions in your cloud. There's no
    Under the **Security** section, the **Transparent Data Encryption (TDE)** option is enabled by default only when your primary cluster is TDE-enabled. It automatically enables TDE and allows you to select the encryption key from the available List.
 
    !!!Note
-   TDE key material for faraway replicas must be same as the primary cluster encryption key. In case you use different key material, the cluster provisioning fails.
-
-   We recommend, not to enable TDE for faraway replica cluster creation, if the source cluster is a non-TDE cluster.
+   The TDE key material for faraway replicas must be the same as the primary cluster encryption key. If you use different key material, the cluster provisioning will fail.
+ 
+   EDB does not support enabling TDE when restoring non-TDE faraway replica clusters.
    !!!
 
 1. To turn on the ability to log in to Postgres using your AWS IAM credentials, enable Identity and Access Management (IAM) Authentication. See [Access](/biganimal/latest/getting_started/creating_a_cluster/#access).