Add API docs on pause_duration, /tidy-cancel

Signed-off-by: Alexander Scheel <[email protected]>

website/content/api-docs/secret/pki.mdx

@@ -70,6 +70,7 @@ update your API calls accordingly.
   - [Tidy](#tidy)
   - [Configure Automatic Tidy](#configure-automatic-tidy)
   - [Tidy Status](#tidy-status)
+  - [Cancel Tidy](#cancel-tidy)
 - [Cluster Scalability](#cluster-scalability)
 - [Managed Key](#managed-keys) (Enterprise Only)
 - [Vault CLI with DER/PEM responses](#vault-cli-with-der-pem-responses)
@@ -3197,6 +3198,18 @@ expiration time.
   the time must be after the expiration time of the certificate (according to
   the local clock) plus the duration of `safety_buffer`. Defaults to `72h`.
 
+- `pause_duration` `(string: "0s")` - Specifies the duration to pause
+  between tidying individual certificates. This releases the revocation
+  lock and allows other operations to continue while tidy is running.
+  This allows an operator to control tidy's resource utilization within
+  a timespan: the LIST operation will remain in memory, but the space
+  between reading, parsing, and updates on-disk cert entries will be
+  increased, decreasing resource utilization.
+
+~> Note: Using too long of a `pause_duration` can result in tidy operations
+   not concluding during this lifetime! Using too short of a pause duration
+   (but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy)
+   to stop a running operation after the sleep period is over.
 
 #### Sample Payload
 
@@ -3325,6 +3338,46 @@ $ curl \
   },
 ```
 
+### Cancel Tidy
+
+This endpoint allows cancelling a running tidy operation. It takes no
+parameter and cancels the tidy at the next available checkpoint, which
+may process additional certificates between when the operation was
+marked as cancelled and when the operation stopped.
+
+The response to this endpoint is the same as the [status](#tidy-status).
+
+| Method | Path               |
+| :----- | :----------------- |
+| `POST` | `/pki/tidy-cancel` |
+
+#### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    http://127.0.0.1:8200/v1/pki/tidy-cancel
+
+```
+
+#### Sample Response
+
+```json
+  "data": {
+    "safety_buffer": 60,
+    "tidy_cert_store": true,
+    "tidy_revoked_certs": true,
+    "error": null,
+    "message": "Tidying certificate store: checking entry 234 of 488",
+    "revoked_cert_deleted_count": 0,
+    "cert_store_deleted_count": 2,
+    "state": "Cancelling",
+    "time_started": "2021-10-20T14:52:13.510161-04:00",
+    "time_finished": null
+  },
+```
+
 ---
 
 ## Cluster Scalability