PSMDB-1780 Documented OpenBao support for PSMSDB

docs/data-at-rest-encryption.md

@@ -5,13 +5,14 @@ Encryption at rest should be used with data in transit encryption and policies t
 Data encryption at rest was introduced in Percona Server for MongoDB 3.6 and is fully compatible with MongoDB's encryption interface. Percona Server for MongoDB supports the following Key Management System (KMS) integrations:
 
 * [HashiCorp Vault](vault.md)
+* [OpenBao](openbao.md)
 * [Key Management Interoperability Protocol (KMIP) Servers](kmip.md)
 
 ## Workflow
 
 !!! important
 
-    You can only enable data at rest encryption and provide all encryption settings on an empty database, when you start the mongod instance for the first time. You cannot enable or disable encryption while the Percona Server for MongoDB server is already running and / or has some data. Nor can you change the effective encryption mode by simply restarting the server. Every time you restart the server, the encryption settings must be the same.
+    You can only enable data at rest encryption and provide all encryption settings on an empty database, when you start the `mongod` instance for the first time. You cannot enable or disable encryption while the Percona Server for MongoDB server is already running and / or has some data. Nor can you change the effective encryption mode by simply restarting the server. Every time you restart the server, the encryption settings must be the same.
 
 Each node of Percona Server for MongoDB generates a random, individual key for every database. It encrypts every database with an individual key and puts those keys into the special, so-called key database. Then each node of Percona Server for MongoDB randomly generates a unique master encryption key and encrypts the key database with this key. 
 
@@ -23,7 +24,7 @@ Thus, two types of keys are used for data at rest encryption:
 
 To manage the master encryption key, use one of the supported key management options:
 
-* Integration with an external key server (recommended). Percona Server for MongoDB is [integrated with HashiCorp Vault](vault.md) for this purpose and supports the secure transfer of keys using [Key Management Interoperability Protocol (KMIP)](kmip.md).
+* Integration with an external key server (recommended). Percona Server for MongoDB is [integrated with HashiCorp Vault](vault.md) and [OpenBao](openbao.md) for this purpose. It also supports the secure transfer of keys using [Key Management Interoperability Protocol (KMIP)](kmip.md).
 
 * [Local key management using a keyfile](keyfile.md).
 

docs/encryption-mode-switch.md

@@ -1,6 +1,6 @@
-# Migrate from key file encryption to HashiCorp Vault encryption
+# Migrate from key file encryption to HashiCorp Vault / OpenBao encryption
 
-The steps below describe how to migrate from the key file encryption to using  HashiCorp Vault.
+The steps below describe how to migrate from the key file encryption to using  HashiCorp Vault. This guide also applies to migration to [OpenBao](https://openbao.org/) - an open-source alternative to HashiCorp Vault. 
 
 !!! note 
 

docs/openbao.md

@@ -0,0 +1,133 @@
+# Use OpenBao for data-at-rest encryption
+
+[OpenBao](https://openbao.org/) is an open-source alternative to HashiCorp Vault. Percona Server for MongoDB is integrated with OpenBao for encryption key management and supports only OpenBao back end with KV Secrets Engine - Version 2 (API) with versioning enabled. 
+
+## Assumptions
+
+1. We assume that you have OpenBao up and running. Refer to [OpenBao](https://openbao.org/docs/install/) documentation for installation instructions. 
+2. For secure communication with OpenBao, [it's recommended to use TLS](https://openbao.org/docs/configuration/ui/#note-on-tls). 
+3. You have an empty Percona Server for MongoDB deployment. 
+
+## OpenBao setup
+
+OpenBao setup is similar to that of HashiCorp Vault. It consists of the following steps:
+
+1. Initialize OpenBao server. As a result, OpenBao generates the root token and the unseal key.
+
+    ```{.bash data-prompt="$"}
+    $ bao operator init
+    ```
+
+2. OpenBao is started in a sealed state. In this state OpenBao can access the storage but it cannot decrypt data. In order to use OpenBao, you need to unseal it using the unseal key.
+
+    ```{.bash data-prompt="$"}
+    $ bao operator unseal <your-unseal-key>
+    ```
+
+3. Next, authenticate in OpenBao using the root token.
+
+    ```{.bash data-prompt="$"}
+    $ bao login <root-token>
+    ```
+
+4. Enable the KV Secrets Engine – Version 2. By default, the secrets engine is enabled at the `secrets/` path. You can specify your own path using the `-path` flag
+
+    ```{.bash data-prompt="$"}
+    $ bao secrets enable --version=2 -path=secret kv
+    ```
+
+5. Create the access policy and grant Percona Server for MongoDB read permissions for the secret's metadata and the secrets engine configuration. Percona Server needs it to check the number of secrets on the OpenBao before it generates a new key. 
+
+   * Create an access policy file:
+
+     ```{.bash data-prompt="$"}
+     $ cat <<EOF > psmdb-access.hcl
+     path "secret/data/*" {
+       capabilities = ["create","read","update","delete"]
+     }
+     path "secret/metadata/*" {
+       capabilities = ["read"]
+     }
+     path "secret/config" {
+       capabilities = ["read"]
+     }
+     EOF
+     ```
+
+   * Upload the access policy to OpenBao:
+
+      ```{.bash data-prompt="$"}
+      $ bao policy write psmdb-policy psmdb-access.hcl
+      ```
+
+6. Create an access token that Percona Server for MongoDB will use. You need to create an access token for every instance of Percona Server for MongoDB in your deployment.
+
+    ```{.bash data-prompt="$"}
+    $ bao token create -policy=psmdb-policy
+    ```
+
+7. Export an access token to a file and restrict access to it for `mongod` user:
+
+    * Create a directory where you will store the token and SSL certificates if you [configured OpenBao with TLS](https://openbao.org/docs/auth/cert/#configuration)
+
+       ```{.bash data-prompt="$"}
+       $ sudo mkdir -p /etc/openbao
+       ```
+
+    * Export the token into the token file. For TLS communication, copy the `.crt` file from OpenBao.
+
+       ```{.bash data-prompt="$"}
+       $ echo "your-access-token-here" > /etc/openbao/token
+       ```
+
+    * Restrict access to the token and certificate files for the `mongod` user:
+
+       ```{.bash data-prompt="$"}
+       $ sudo chmod 400 /etc/openbao/token
+       $ sudo chown mongod:mongod /etc/openbao/token
+       ```
+
+!!! admonition "See also"
+
+    To learn more about OpenBao configuration, see the following resources:
+
+    * [How to configure KV secrets engine - version 2](https://openbao.org/docs/secrets/kv/kv-v2/)
+    * [Master key loss prevention](vault.md#master-key-loss-prevention)
+
+## Percona Server for MongoDB configuration
+
+Percona Server for MongoDB configuration for OpenBao is the same as for HashCorp Vault. Refer to the [HashiCorp Vault parameters](vault.md#hashicorp-vault-parameters) for the description of available configuration options.
+
+To enable data-at-rest encryption in Percona Server for MongoDB, you need the following information:
+
+* OpenBao URL and port 
+* OpenBao secrets engine mount path
+* Path to the access token
+
+=== ":octicons-file-code-24: Configuration file"    
+
+    1. Edit the `/etc/mongod.conf` configuration file and specify the following configuration:    
+
+        ```yaml
+        security:
+          enableEncryption: true
+          vault:
+            serverName: 127.0.0.1
+            port: 8200
+            tokenFile: /etc/openbao/token
+            secret: secret/data/
+        ```
+
+    2. Start Percona Server for MongoDB:
+
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl start mongod
+        ```
+
+=== ":material-console: Command line"
+
+    Start Percona Server for MongoDB with the following parameters:
+
+    ```{.bash data-prompt="$"}
+    $ mongod --enableEncryption --vaultServerName 127.0.0.1 --vaultPort 8200 --vaultTokenFile /etc/openbao/token --vaultSecret secret/data/ --vaultDisableTLSForTesting
+    ```

docs/vault.md

@@ -41,7 +41,7 @@ security:
 
 #### Vault access policy configuration
 
-Percona Server for MongoDB checks the number of the secrets on the Vault server before adding a new one thus [preventing the loss of the old master key](#master-key-loss-prevention). For these checks, Percona Server for MongoDB requires read permissions for the secret’s metadata and the secrets engine configuration. You configure these permissions within the access policy on the Vault server.
+Percona Server for MongoDB checks the number of the secrets on the Vault server before adding a new one thus [preventing the loss of the old master key](#master-key-loss-prevention). For these checks, Percona Server for MongoDB requires read permissions for the secret's metadata and the secrets engine configuration. You configure these permissions within the access policy on the Vault server.
 
 Find the sample policy configuration below:
 
@@ -126,7 +126,7 @@ Percona Server for MongoDB checks if the number of secret versions has reached t
 
 If the number of secrets reaches the maximum, Percona Server for MongoDB logs an error and exits. This prevents the Vault server from dropping the oldest secret version and the encryption key it stores.
 
-To continue, increase the maximum versions for the secret or the entire secrets engine on the Vault server, then restart Percona Server for MongoDB. To check the number of secrets on the Vault server, ensure Percona Server for MongoDB has [read permissions for the secret’s metadata and the secrets engine configuration](#vault-access-policy-configuration).
+To continue, increase the maximum versions for the secret or the entire secrets engine on the Vault server, then restart Percona Server for MongoDB. To check the number of secrets on the Vault server, ensure Percona Server for MongoDB has [read permissions for the secret's metadata and the secrets engine configuration](#vault-access-policy-configuration).
 
 
 --8<-- "encryption-status.md"

mkdocs-base.yml

@@ -228,6 +228,7 @@ nav:
       - Encryption:
         - "Data at rest encryption": "data-at-rest-encryption.md"
         - "Use Vault": vault.md
+        - "Use OpenBao": openbao.md
         - "Use KMIP" : kmip.md
         - "Use local keyfile": keyfile.md
         - "Migrate from keyfile to Vault": encryption-mode-switch.md