From 5f95c34096a45b1586998d5b2721ad8946cba098 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Thu, 7 Nov 2024 20:33:55 +0100 Subject: [PATCH] PG-1197 Removed steps for tde_heap_basic from docs (#330) * PG-1197 Removed steps for tde_heap_basic Added description of versions * Updated after the review --- documentation/_resource/overrides/main.html | 2 +- .../_resource/overrides/partials/header.html | 2 +- documentation/docs/index.md | 41 +++++++--- documentation/docs/install.md | 18 ++-- documentation/docs/setup.md | 10 +-- documentation/docs/test.md | 82 +++++-------------- documentation/snippets/services-banner.md | 2 +- 7 files changed, 67 insertions(+), 90 deletions(-) diff --git a/documentation/_resource/overrides/main.html b/documentation/_resource/overrides/main.html index 64aebe8d..4ef03fed 100644 --- a/documentation/_resource/overrides/main.html +++ b/documentation/_resource/overrides/main.html @@ -5,7 +5,7 @@ {% block announce %} This is a Beta version of Percona Transparent Encryption extension and it is - not recommended for production environments yet. We encourage you to test it and give your feedback. + not recommended for production environments yet. We encourage you to test it and give your feedback. This will help us improve the product and make it production-ready faster. {% endblock %} diff --git a/documentation/_resource/overrides/partials/header.html b/documentation/_resource/overrides/partials/header.html index e177d4dd..2d0d6e74 100644 --- a/documentation/_resource/overrides/partials/header.html +++ b/documentation/_resource/overrides/partials/header.html @@ -43,7 +43,7 @@ - Percona Documentation + Percona Software for PostgreSQL Documentation diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 338ea4b3..a377798e 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -1,41 +1,58 @@ # `pg_tde` documentation -`pg_tde` is the extension that brings in [Transparent Data Encryption (TDE)](tde.md) to PostgreSQL and enables users to keep sensitive data safe and secure. It enables users to configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys, while keeping others non encrypted. +`pg_tde` is the extension that brings in [Transparent Data Encryption (TDE)](tde.md) to PostgreSQL and enables users to keep sensitive data safe and secure. The encryption is transparent for users allowing them to access and manipulate the data and not to worry about the encryption process. + +Users can configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys, while keeping others non encrypted. !!! important - This is the {{release}} version of the extension and is not meant for production use yet. [Release notes](release-notes/release-notes.md) + This extension is in the experimental phase and is under active development. It is not meant for production use yet. + +[What's new ](release-notes/release-notes.md){.md-button} -## What's encrypted +## What's encrypted: `pg_tde` encrypts the following: * User data in tables, including TOAST tables, that are created using the extension. Metadata of those tables is not encrypted. -* Write-Ahead Log (WAL) data for tables created using the extension * Temporary tables created during the database operation for data tables created using the extension +* Write-Ahead Log (WAL) data for the entire database cluster. This includes WAL data in encrypted and non-encrypted tables +* Indexes on encrypted tables +* Logical replication on encrypted tables ## Known limitations -* Logical replication is not available as it doesn't work with encrypted tables. * Keys in the local keyfile are stored unencrypted. -* Indexes and `NULL` bitmaps of tuples are currently not encrypted. +* System tables are currently not encrypted. :material-alert: Warning: Note that introducing encryption/decryption affects performance. Our benchmark tests show less than 10% performance overhead for most situations. However, in some specific applications such as those using JSONB operations, performance degradation might be higher. -[Get started](install.md){.md-button} +## Versions and supported PostgreSQL deployments + +The `pg_tde` extension comes in two distinct versions with specific access methods to encrypt the data. These versions are database-specific and differ in terms of what they encrypt and with what access method. Each version is characterized by the database it supports, the access method it provides, and the scope of encryption it offers. + +* **Version for Percona Server for PostgreSQL** + + This `pg_tde` version is based on and supported for [Percona Server for PostgreSQL 17.x :octicons-link-external-16:](https://docs.percona.com/postgresql/17/postgresql-server.html) - an open source binary drop-in replacement for PostgreSQL Community. It provides the `tde_heap` access method and offers [full encryption capabilities](#whats-encrypted). -## Supported PostgreSQL versions +* **Community version** -`pg_tde` is currently based on Percona Server for PostgreSQL 17.0 and upstream PostgreSQL 16.x. + This version is supported for PostgreSQL Community 16 and 17, and Percona Distribution for PostgreSQL 16. It provides the `tde_heap_basic` access method, offering limited encryption features. The limitations are in encrypting WAL data only for tables created using the extension and no support of index encryption nor logical replication. -It is also supported for Percona Distribution for PostgreSQL 16.x and upstream PostgreSQL 16.x. +### Which version to chose? + +The answer is pretty straightforward: if you don't use indexes and don't need index encryption, use the community version and the `tde_heap_basic` access method. Check the [upstream documentation :octicons-link-external-16:](https://github.com/percona/pg_tde/blob/main/README.md) how to get started. + +Otherwise, enjoy full encryption with the Percona Server for PostgreSQL version and the `tde_heap` access method. + +Still not sure? [Contact our experts](https://www.percona.com/about/contact) to find the best solution for you. + +[Get started](install.md){.md-button} ## Future releases The following is planned for future releases of `pg_tde`: -* Encryption of indexes and `NULL` bitmaps of tuples -* Logical replication support * KMIP integration for key management * Global principal key management diff --git a/documentation/docs/install.md b/documentation/docs/install.md index 58da84e8..3c23651e 100644 --- a/documentation/docs/install.md +++ b/documentation/docs/install.md @@ -19,7 +19,7 @@ Install `pg_tde` using one of available installation methods: === "Package manager" - Starting with Aplha1 version, you can install the extension as package from Percona repositories using the `percona-release` tool. The packages are available for the following operating systems: + The packages are available for the following operating systems: - Red Hat Enterprise Linux 8 and compatible derivatives - Red Hat Enterprise Linux 9 and compatible derivatives @@ -33,15 +33,15 @@ Install `pg_tde` using one of available installation methods: === "Build from source" - The following steps apply to PostgreSQL 16. To build `pg_tde` for PostgreSQL 17, replace the version in the commands. + To build `pg_tde` from source code, do the following - 1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian: + 1. On Ubuntu/Debian: Install the following dependencies required for the build: ```sh - sudo apt install make gcc postgresql-server-dev-16 libcurl4-openssl-dev + sudo apt install make gcc postgresql-server-dev-17 libcurl4-openssl-dev ``` - 2. [Install Percona Distribution for PostgreSQL 16](https://docs.percona.com/postgresql/16/installing.html) or [upstream PostgreSQL 16](https://www.postgresql.org/download/) + 2. [Install Percona Distribution for PostgreSQL 17](https://docs.percona.com/postgresql/17/installing.html) or [upstream PostgreSQL 17](https://www.postgresql.org/download/) 3. If PostgreSQL is installed in a non standard directory, set the `PG_CONFIG` environment variable to point to the `pg_config` executable. @@ -62,7 +62,11 @@ Install `pg_tde` using one of available installation methods: === "Run in Docker" - You can find Docker images built from the current main branch on [Docker Hub](https://hub.docker.com/r/perconalab/pg_tde). Images are built on top of [postgres:16](https://hub.docker.com/_/postgres) official image. + !!! note + + The steps below are for the `pg_tde` community version. + + You can find Docker images built from the current main branch on [Docker Hub](https://hub.docker.com/r/perconalab/pg_tde). Images are built on top of [postgres:17](https://hub.docker.com/_/postgres) official image. To run `pg_tde` in Docker, use the following command: @@ -70,7 +74,7 @@ Install `pg_tde` using one of available installation methods: docker run --name pg-tde -e POSTGRES_PASSWORD=mysecretpassword -d perconalab/pg_tde ``` - It builds and adds `pg_tde` extension to PostgreSQL 16. The `postgresql.conf` contains the required modifications. The `pg_tde` extension is added to `template1` so that all new databases automatically have the `pg_tde` extension loaded. + It builds and adds `pg_tde` extension to PostgreSQL 17. The `postgresql.conf` contains the required modifications. The `pg_tde` extension is added to `template1` so that all new databases automatically have the `pg_tde` extension loaded. Keys are not created automatically. You must configure a key provider and a principal key for each database where you wish to use encrypted tables. See the instructions in the [Setup](setup.md) section, starting with the 4th point, as the first 3 steps are already completed in the Docker image. diff --git a/documentation/docs/setup.md b/documentation/docs/setup.md index 3dc54d5f..7207c6d4 100644 --- a/documentation/docs/setup.md +++ b/documentation/docs/setup.md @@ -78,11 +78,9 @@ Load the `pg_tde` at the start time. The extension requires additional shared me ## WAL encryption configuration (tech preview) -Perform this step if you [installed Percona Server for PostgreSQL :octicons-link-external-16:](https://docs.percona.com/postgresql/17/installing.html). Otherwise, proceed to the [Next steps](#next-steps). - 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: -1. Enable WAL level encryption using the `ALTER SYSTEM SET` command: +1. Enable WAL level encryption using 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; @@ -104,8 +102,8 @@ After you [enabled `pg_tde`](#enable-extension) and started the Percona Server f 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. - Set up the key provider for WAL encryption - + Set up the key provider for WAL encryption + === "With HashiCorp Vault" ```sql @@ -136,7 +134,7 @@ After you [enabled `pg_tde`](#enable-extension) and started the Percona Server f SELECT pg_tde_rotate_principal_key('PG_TDE_GLOBAL', 'new-principal-key', 'provider-name'); ``` -Now all WAL files are encrypted. +Now all WAL files are encrypted for both encrypted and unencrypted tables. ## Next steps diff --git a/documentation/docs/test.md b/documentation/docs/test.md index 9a1aa38f..42fe03d6 100644 --- a/documentation/docs/test.md +++ b/documentation/docs/test.md @@ -1,76 +1,34 @@ # Test Transparent Data Encryption -To check if the data is encrypted, do the following: - -=== "pg_tde Beta" - - 1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap_basic`. To enable data encryption, create the table using this access method as follows: - - ```sql - CREATE TABLE ( ) USING tde_heap_basic; - ``` - - !!! hint - - You can enable data encryption by default by setting the `default_table_access_method` to `tde_heap_basic`: - - ```sql - ALTER SYSTEM SET default_table_access_method=tde_heap; - ``` - - Reload the configuration to apply the changes: +!!! warning - ``` - SELECT pg_reload_conf(); - ``` - - 2. Run the following function: + This is the tech preview functionality. Its scope is not yet finalized and can change anytime.** Use it only for testing purposes.** - ```sql - SELECT pg_tde_is_encrypted('table_name'); - ``` - - The function returns `t` if the table is encrypted and `f` - if not. - - 3. Rotate the principal key when needed: - - ```sql - SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider - ``` - -=== "pg_tde Tech preview" - - !!! warning - - This is the tech preview functionality. Its scope is not yet finalized and can change anytime.** Use it only for testing purposes.** +To check if the data is encrypted, do the following: - 1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap`. To enable data encryption, create the table using this access method as follows: +1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap`. To enable data encryption, create the table using this access method as follows: - ```sql - CREATE TABLE ( ) USING tde_heap; - ``` + ```sql + CREATE TABLE ( ) USING tde_heap; + ``` - 2. Run the following function: +2. Run the following function: - ```sql - SELECT pg_tde_is_encrypted('table_name'); - ``` + ```sql + SELECT pg_tde_is_encrypted('table_name'); + ``` - The function returns `t` if the table is encrypted and `f` - if not. + The function returns `t` if the table is encrypted and `f` - if not. - 3. Rotate the principal key when needed: +3. Rotate the principal key when needed: - ```sql - SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider - ``` + ```sql + SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- changeprovider + ``` !!! hint diff --git a/documentation/snippets/services-banner.md b/documentation/snippets/services-banner.md index 31156ce9..81886f96 100644 --- a/documentation/snippets/services-banner.md +++ b/documentation/snippets/services-banner.md @@ -6,7 +6,7 @@ If you need assistance, visit the community forum for comprehensive and free dat
-[:material-forum-outline: Community Forum](https://forums.percona.com/c/postgresql/25?utm_campaign=Doc%20pages) [:percona-logo: Get a Percona Expert](https://www.percona.com/about/contact) +[:material-forum-outline: Community Forum](https://forums.percona.com/c/postgresql/pg-tde-transparent-data-encryption-tde/82) [:percona-logo: Get a Percona Expert](https://www.percona.com/about/contact)