backport of commit ce2851543f79e14611b1e8e5c997ad0fbe529dbf (#22633)

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

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

@@ -28,18 +28,35 @@ become invalid within a reasonable time of the lease expiring.
 
 ### Static roles
 
-The database secrets engine supports the concept of "static roles", which are
+With dynamic secrets, Vault generates a unique username and password pair for
-a 1-to-1 mapping of Vault Roles to usernames in a database. The current password
+each unique credential request. Vault also supports **static roles** for
-for the database user is stored and automatically rotated by Vault on a
+some database secrets engines. Static roles are a 1-to-1 mapping of Vault roles
-configurable period of time. This is in contrast to dynamic secrets, where a
+to usernames in a database. With static roles, Vault stores, and automatically
-unique username and password pair are generated with each credential request.
+rotates, passwords for the associated database user based on a configurable
-When credentials are requested for the Role, Vault returns the current
+period of time.
-password for the configured database user, allowing anyone with the proper
-Vault policies to have access to the user account in the database.
 
--> Please consult the specific database documentation on the left navigation or
+When a client requests credentials for the static role, Vault
-the table below under [Database Capabilities](#database-capabilities) to see if
+returns the current password for whichever database user is mapped to the
-a given database backend supports static roles.
+requested role. With static roles, anyone with the proper Vault policies can
+access the associated user account in the database.
+
+<Warning title="Do not use static roles for root database credentials">
+   Do not manage the same root database credentials that you provide to Vault in
+   <tt>config/</tt> with static roles.
+   
+   Vault does not distinguish between standard credentials and root credentials
+   when rotating passwords. If you assign your root credentials to a static
+   role, any dynamic or static users managed by that database configuration will
+   fail after rotation because the password for <tt>config/</tt> is no longer
+   valid.
+
+   If you need to rotate root credentials, use the
+   [Rotate root credentials](vault/api-docs/secret/database/index.mdx#rotate-root-credentials)
+   API endpoint.
+</Warning>
+
+Consult the [database capabilities table](#db-capabilities-table) to determine
+if your chosen database backend supports static roles.
 
 ## Setup
 
@@ -134,6 +151,9 @@ As of Vault 1.6, all databases support dynamic roles and static roles. All plugi
 the root user's credentials. MongoDB Atlas cannot support rotating the root user's credentials because it uses a public
 and private key pair to authenticate.
 
+<a id="db-capabilities-table" />
+
+
 | Database                                                               | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | Credential Types          |
 | ---------------------------------------------------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |---------------------------|
 | [Cassandra](/vault/docs/secrets/databases/cassandra)                         | Yes                      | Yes           | Yes (1.6+)   | Yes (1.7+)             | password                     |
@@ -222,6 +242,7 @@ disable_escaping="true"
 ```
 
 ## Tutorial
+
 Refer to the following step-by-step tutorials for more information:
 
 - [Secrets as a Service: Dynamic Secrets](/vault/tutorials/db-credentials/database-secrets)