More PKI docs updates (#15757)

* Add missing key_ref parameter to gen root docs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add API docs section on key generation

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add note about managed key access

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

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

@@ -38,6 +38,7 @@ update your API calls accordingly.
 - [Managing Keys and Issuers](#managing-keys-and-issuers)
   - [List Issuers](#list-issuers)
   - [List Keys](#list-keys)
+  - [Generate Key](#generate-key)
   - [Generate Root](#generate-root)
   - [Generate Intermediate CSR](#generate-intermediate-csr)
   - [Import CA Certificates and Keys](#import-ca-certificates-and-keys)
@@ -1172,6 +1173,91 @@ $ curl \
 }
 ```
 
+### Generate Key
+
+This endpoint generates a new private key for use in the PKI mount. This key
+can be used with either the [root](#generate-root) or [intermediate](#generate-intermediate-csr)
+endpoints, using the `type=existing` variant.
+
+If the path ends with `exported`, the private key will be returned in the
+response; if it is `internal` the private key will not be returned and _cannot
+be retrieved later_; if it is `kms`, a [managed keys](#managed-keys) will be
+used.
+
+| Method | Path                               |
+| :----- | :--------------------------------- |
+| `POST` | `/pki/keys/generate/:type`         |
+
+#### Parameters
+
+- `type` `(string: <required>)` - Specifies the type of the root to
+  create. If `exported`, the private key will be returned in the response; if
+  `internal` the private key will not be returned and _cannot be retrieved
+  later_; `kms` is also supported: [see below for more details about managed
+  keys](#managed-keys). This parameter is part of the request URL.
+
+- `key_name` `(string: "")` - When a new key is created with this request,
+  optionally specifies the name for this. The global ref `default` may not
+  be used as a name.
+
+- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519`
+  or `ec`.
+
+~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+   and thus should not be used: `ed25519`.
+
+- `key_bits` `(int: 0)` - Specifies the number of bits to use for the
+  generated keys. Allowed values are 0 (universal default); with
+  `key_type=rsa`, allowed values are: 2048 (default), 3072, or
+  4096; with `key_type=ec`, allowed values are: 224, 256 (default),
+  384, or 521; ignored with `key_type=ed25519`.
+
+#### Managed Keys Parameters
+
+See [Managed Keys](#managed-keys) for additional details on this feature, if
+`type` was set to `kms`. One of the following parameters must be set
+
+- `managed_key_name` `(string: "")` - The managed key's configured name.
+
+- `managed_key_id` `(string: "")` - The managed key's UUID.
+
+#### Sample Payload
+
+```json
+{
+  "key_type": "ec",
+  "key_bits": "256",
+  "key_name": "root-key-2022"
+}
+```
+
+#### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/pki/keys/generate/internal
+```
+
+#### Sample Response
+
+```json
+{
+  "request_id": "8ad22b2f-7d14-f2cd-a10a-d1abc33676ab",
+  "lease_id": "",
+  "lease_duration": 0,
+  "renewable": false,
+  "data": {
+    "key_id": "adda2443-a8aa-d181-9d07-07c7be6a76ab",
+    "key_name": "root-key-2022",
+    "key_type": "ec"
+  },
+  "warnings": null
+}
+```
+
 ### Generate Root
 
 This endpoint generates a new self-signed CA certificate and private key. If
@@ -1214,6 +1300,10 @@ use the values set via `config/urls`.
   optionally specifies the name for this. The global ref `default` may not
   be used as a name.
 
+- `key_ref` `(string: "default")` - Specifies the key (either `default`, by
+  name, or by identifier) to use for generating this request. Only suitable
+  for `type=existing` requests.
+
 - `common_name` `(string: <required>)` - Specifies the requested CN for the
   certificate. If more than one `common_name` is desired, specify the
   alternative names in the `alt_names` list.

website/content/docs/secrets/pki/considerations.mdx

@@ -444,6 +444,10 @@ For these personas, we suggest the following ACLs, in condensed, tabular form:
 | `/root/rotate/+` | Write | Yes | | | | |
 | `/root/replace` | Write | Yes | | | | |
 
+~> Note: With managed keys, operators might need access to [read the mount
+   point's tunable data](/api-docs/system/mounts) (Read on `/sys/mounts`) and
+   may need access [to use or manage managed keys](/api-docs/system/managed-keys).
+
 ## Replicated DataSets
 
 When operating with [Performance Secondary](/docs/enterprise/replication#architecture)