Add documentation for new rootless password rotation workflow for DB Static Roles (#28374)

Co-authored-by: John-Michael Faircloth <[email protected]>
Co-authored-by: Sarah Chavis <[email protected]>

Author: 3 people

website/content/api-docs/secret/databases/index.mdx

@@ -534,6 +534,11 @@ this in order to know the password.
 - `username` `(string: <required>)` – Specifies the database username that this
   Vault role corresponds to.
 
+- `self_managed_password` `(string)` – <EnterpriseAlert product="vault" inline />
+  The password corresponding to the username in the database. Required when using
+  the Rootless Password Rotation workflow for static roles. Only enabled for select
+  DB engines (Postgres).
+
 - `db_name` `(string: <required>)` - The name of the database connection to use
   for this role.
 

website/content/api-docs/secret/databases/postgresql.mdx

@@ -51,6 +51,10 @@ has a number of parameters to further configure a connection.
 
 - `password` `(string: "")` - The root credential password used in the connection URL.
 
+- `self_managed` `(boolean: "false")` - <EnterpriseAlert product="vault" inline /> If
+  set, allows onboarding static roles with a rootless connection configuration. Mutually
+  exclusive with `username` and `password`. If set, will force `verify_connection` to be false.
+
 - `tls_ca` `(string: "")` - The x509 CA file for validating the certificate
   presented by the PostgreSQL server. Must be PEM encoded.
 

website/content/docs/secrets/databases/postgresql.mdx

@@ -24,9 +24,9 @@ options, including SSL options, can be found in the [pgx][pgxlib] and
 
 ## Capabilities
 
-| Plugin Name                  | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
-| ---------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |
-| `postgresql-database-plugin` | Yes                      | Yes           | Yes          | Yes (1.7+)             |
+| Plugin Name                  | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | Credential Types             |
+| ---------------------------- | ------------------------ | ------------- | ------------ | ---------------------- | ---------------------------- |
+| `postgresql-database-plugin` | Yes                      | Yes           | Yes          | Yes (1.7+)             | password, gcp_iam            |
 
 ## Setup
 
@@ -84,6 +84,70 @@ the proper permission, it can generate credentials.
     username           v-vaultuse-my-role-x
     ```
 
+## Rootless Configuration and Password Rotation for Static Roles
+
+<EnterpriseAlert product="vault" />
+
+The PostgreSQL secrets engine supports using Static Roles and its password rotation mechanisms with a Rootless
+DB connection configuration. In this workflow, a static DB user can be onboarded onto Vault's static role rotation
+mechanism without the need of privileged root accounts to configure the connection. Instead of using a single root
+connection, multiple dedicated connections to the DB are made for each static role. This workflow does not support
+dynamic roles/credentials.
+
+~> Note: It is **highly recommended** that the DB users being onboarded as static roles
+have the minimum set of privileges. Each static role will open a new connection into the DB.
+Granting minimum privileges to the DB users being onboarded ensures that multiple
+highly-privileged connections to an external system are not being made.
+
+~> Note: Out-of-band password rotations will cause Vault to be out of sync with the state of
+the DB user, and will require manually updating the user's password in the external PostgreSQL
+DB in order to resolve any errors encountered during rotation.
+
+1.  Enable the database secrets engine if it is not already enabled:
+
+    ```shell-session
+    $ vault secrets enable database
+    Success! Enabled the database secrets engine at: database/
+    ```
+
+    By default, the secrets engine will enable at the name of the engine. To
+    enable the secrets engine at a different path, use the `-path` argument.
+
+1.  Configure connection to DB without root credentials and enable the rootless
+    workflow by setting the `self_managed` parameter:
+
+    ```shell-session
+    $ vault write database/config/my-postgresql-database \
+        plugin_name="postgresql-database-plugin" \
+        allowed_roles="my-role" \
+        connection_url="postgresql://{{username}}:{{password}}@localhost:5432/database-name" \
+        self_managed=true
+    ```
+
+1.  Configure a static role that creates a dedicated connection to a user in the DB with
+    the `self_managed_password` parameter:
+
+    ```shell-session
+    $ vault write database/static-roles/my-static-role \
+      db_name="my-postgresql-database" \
+      username="staticuser" \
+      self_managed_password="password" \
+      rotation_period="1h"
+    ```
+
+1.  Read static credentials:
+
+    ```shell-session
+    $ vault read database/static-creds/static-test
+    Key                    Value
+    ---                    -----
+    last_vault_rotation    2024-09-11T14:15:13.764783-07:00
+    password               XZY42BVc-UO5bMsbgxrW
+    rotation_period        1h
+    ttl                    59m55s
+    username               staticuser
+    ```
+
 ## Client x509 certificate authentication
 
 This plugin supports using PostgreSQl's [x509 Client-side Certificate Authentication](https://www.postgresql.org/docs/16/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).