docs: db schedule-based static role rotations (#22863)

* docs: db schedule-based static role rotations

* fix broken link

* add mutual exclusion notice on overview page

* prepend slash to relative link

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

@@ -479,7 +479,7 @@ $ curl \
 
 This endpoint creates or updates a static role definition. Static Roles are a
 1-to-1 mapping of a Vault Role to a user in a database which are automatically
-rotated based on the configured `rotation_period`.
+rotated based on the configured `rotation_period` or `rotation_schedule`.
 
 ~> This endpoint distinguishes between `create` and `update` ACL capabilities.
 
@@ -498,20 +498,40 @@ this in order to know the password.
 - `username` `(string: <required>)` – Specifies the database username that this
   Vault role corresponds to.
 
-- `rotation_period` `(string/int: <required>)` – Specifies the amount of time
-  Vault should wait before rotating the password. The minimum is 5 seconds.
-
 - `db_name` `(string: <required>)` - The name of the database connection to use
   for this role.
 
+- `rotation_period` `(string/int)` – Specifies the amount of time Vault should
+  wait before rotating the password. The minimum is 5 seconds.  Uses [duration
+  format strings](/vault/docs/concepts/duration-format). Mutually exclusive
+  with `rotation_schedule`.
+
+- `rotation_schedule` `(string)` – A cron-style string that will define the
+  schedule on which rotations should occur. This should be a "standard"
+  [cron-style](https://en.wikipedia.org/wiki/Cron) string made of five fields
+  of which each entry defines the minute, hour, day of month, month, and day of
+  week respectively. For example, a value of `0 0 * * SAT` will set rotations
+  to occur on Saturday at 00:00. Mutually exclusive with `rotation_period`.
+
+  ~> **Warning**: The `rotation_period` and `rotation_schedule` fields are
+  mutually exclusive. One of them must be set but not both.
+
+- `rotation_window` `(string/int)` – Specifies the amount of time in which the
+  rotation is allowed to occur starting from a given `rotation_schedule`. If
+  the credential is not rotated during this window, due to a failure or
+  otherwise, it will not be rotated until the next scheduled rotation. The
+  minimum is 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
+  Optional when `rotation_schedule` is set and disallowed when `rotation_period`
+  is set.
+
 - `rotation_statements` `(list: [])` – Specifies the database statements to be
   executed to rotate the password for the configured database user. Not every
   plugin type will support this functionality. See the plugin's API page for
   more information on support and formatting for this parameter.
 
 @include 'db-secrets-credential-types.mdx'
 
-### Sample payload
+### Sample payload with rotation period
 
 ```json
 {
@@ -524,6 +544,20 @@ this in order to know the password.
 }
 ```
 
+### Sample payload with rotation schedule
+
+```json
+{
+  "db_name": "mysql",
+  "username": "static-database-user",
+  "rotation_statements": [
+    "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
+  ],
+  "rotation_schedule": "0 0 * * SAT",
+  "rotation_window": "1h"
+}
+```
+
 ### Sample request
 
 ```shell-session
@@ -555,7 +589,7 @@ $ curl \
     http://127.0.0.1:8200/v1/database/static-roles/my-static-role
 ```
 
-### Sample response
+### Sample response with rotation period
 
 ```json
 {
@@ -566,7 +600,24 @@ $ curl \
     "rotation_statements": [
       "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
     ],
-    "rotation_period": "1h"
+    "rotation_period": 3600
+  }
+}
+```
+
+### Sample response with rotation schedule
+
+```json
+{
+  "data": {
+    "credential_type": "password",
+    "db_name": "mysql",
+    "username": "static-user",
+    "rotation_statements": [
+      "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
+    ],
+    "rotation_schedule": "0 0 * * SAT",
+    "rotation_window": 3600
   }
 }
 ```
@@ -644,7 +695,7 @@ $ curl \
     http://127.0.0.1:8200/v1/database/static-creds/my-static-role
 ```
 
-### Sample response
+### Sample response with rotation period
 
 ```json
 {
@@ -658,6 +709,21 @@ $ curl \
 }
 ```
 
+### Sample response with rotation schedule
+
+```json
+{
+  "data": {
+    "username": "static-user",
+    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
+    "last_vault_rotation": "2019-05-06T15:26:42.525302-05:00",
+    "rotation_schedule": "0 0 * * SAT",
+    "rotation_window": 3600,
+    "ttl": 5000
+  }
+}
+```
+
 ## Rotate static role credentials
 
 This endpoint is used to rotate the Static Role credentials stored for a given

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

@@ -28,17 +28,16 @@ become invalid within a reasonable time of the lease expiring.
 
 ### Static roles
 
-With dynamic secrets, Vault generates a unique username and password pair for
-each unique credential request. Vault also supports **static roles** for
-some database secrets engines. Static roles are a 1-to-1 mapping of Vault roles
-to usernames in a database. With static roles, Vault stores, and automatically
-rotates, passwords for the associated database user based on a configurable
-period of time.
-
-When a client requests credentials for the static role, Vault
-returns the current password for whichever database user is mapped to the
-requested role. With static roles, anyone with the proper Vault policies can
-access the associated user account in the database.
+Vault also supports **static roles** for all database secrets engines. Static
+roles are a 1-to-1 mapping of Vault roles to usernames in a database. With
+static roles, Vault stores and automatically rotates passwords for the
+associated database user based on a configurable period of time or rotation
+schedule.
+
+When a client requests credentials for the static role, Vault returns the
+current password for whichever database user is mapped to the 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
@@ -51,7 +50,7 @@ access the associated user account in the database.
    valid.
 
    If you need to rotate root credentials, use the
-   [Rotate root credentials](vault/api-docs/secret/database/index.mdx#rotate-root-credentials)
+   [Rotate root credentials](/vault/api-docs/secret/databases#rotate-root-credentials)
    API endpoint.
 </Warning>
 
@@ -188,6 +187,43 @@ of dynamic and static roles configure the credential that Vault will generate an
 make available to database plugins. See the documentation of individual database
 plugins for the credential types they support and usage examples.
 
+## Schedule-based static role rotation
+
+The database secrets engine supports configuring schedule-based automatic
+credential rotation for static roles with the
+[rotation_schedule](/vault/api-docs/secret/databases#rotation_schedule) field.
+For example:
+
+```shell-session
+$ vault write database/static-roles/my-role \
+    db_name=my-database \
+    username="vault" \
+    rotation_schedule="0 * * * SAT"
+```
+
+This configuration will set the role's credential rotation to occur on Saturday
+at 00:00.
+
+Additionally, this schedule-based approach allows for optionally configuring a
+[rotation_window](/vault/api-docs/secret/databases#rotation_window) in which
+the automatic rotation is allowed to occur. For example:
+
+```shell-session
+$ vault write database/static-roles/my-role \
+    db_name=my-database \
+    username="vault" \
+    rotation_window="1h" \
+    rotation_schedule="0 * * * SAT"
+```
+
+This configuration will set rotations to occur on Saturday at 00:00. The 1
+hour `rotation_window` will prevent the rotation from occuring after 01:00. If
+the static role's credential is not rotated during this window, due to a failure
+or otherwise, it will not be rotated until the next scheduled rotation.
+
+!> The `rotation_period` and `rotation_schedule` fields are
+mutually exclusive. One of them must be set but not both.
+
 ## Password generation
 
 Passwords are generated via [Password Policies](/vault/docs/concepts/password-policies).