docs: keyring HTTP API documentation (#14513)

website/content/api-docs/operator/keyring.mdx

@@ -0,0 +1,157 @@
+---
+layout: api
+page_title: Keyring - Operator - HTTP API
+description: |-
+  The /operator/keyring endpoints provide tools for Nomad operators to interact with the root keyring.
+---
+
+# Keyring Operator HTTP API
+
+The `/operator/keyring` endpoints manage encryption root keys used for storing
+variables and signing workload identities, including examining active encryption
+keys, rotating keys, or removing unused keys.
+
+See the [Key Management] documentation for information how these capabilities
+are used. For instructions on how to use the CLI to perform these operations
+manually, please see the documentation for the [`nomad operator root keyring`]
+commands.
+
+## List Keys
+
+This endpoint retrieves a list of root keys known to the cluster. Note that only
+key metadata is returned and the key material is never made available via the
+HTTP API.
+
+| Method | Path                        | Produces           |
+|--------|-----------------------------|--------------------|
+| `GET`  | `/v1/operator/keyring/keys` | `application/json` |
+
+The table below shows this endpoint's support for [blocking queries] and
+[required ACLs].
+
+| Blocking Queries | ACL Required |
+|------------------|--------------|
+| `YES`            | `management` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+    https://localhost:4646/v1/operator/keyring/keys
+```
+
+### Sample Response
+
+```json
+[
+  {
+    "Algorithm": "aes256-gcm",
+    "CreateIndex": 13,
+    "CreateTime": 1662665630638648800,
+    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
+    "ModifyIndex": 13,
+    "State": "active"
+  },
+  {
+    "Algorithm": "aes256-gcm",
+    "CreateIndex": 6,
+    "CreateTime": 1662665528857979100,
+    "KeyID": "64b96f4b-f167-f2dd-9148-7867f7e420e3",
+    "ModifyIndex": 12,
+    "State": "inactive"
+  },
+  {
+    "Algorithm": "aes256-gcm",
+    "CreateIndex": 12,
+    "CreateTime": 1662665624108063000,
+    "KeyID": "f9725e52-9b49-5b55-a8eb-083e23db4a3e",
+    "ModifyIndex": 13,
+    "State": "inactive"
+  }
+]
+```
+
+## Rotate Key
+
+This endpoint forces the server to rotate the active root key.
+
+| Method | Path                          | Produces           |
+|--------|-------------------------------|--------------------|
+| `PUT`  | `/v1/operator/keyring/rotate` | `application/json` |
+
+The table below shows this endpoint's support for [blocking queries] and
+[required ACLs].
+
+| Blocking Queries | ACL Required |
+|------------------|--------------|
+| `NO`             | `management` |
+
+
+### Parameters
+
+- `full` `(bool: false)` - Decrypt all existing variables and re-encrypt with
+  the new key. This API request will immediately return and the re-encryption
+  process will run asynchronously on the leader.
+
+
+### Sample Request
+
+```shell-session
+$ curl \
+    -XPUT \
+    https://localhost:4646/v1/operator/keyring/rotate
+```
+
+### Sample Response
+
+```json
+{
+  "Index": 13,
+  "Key": {
+    "Algorithm": "aes256-gcm",
+    "CreateIndex": 0,
+    "CreateTime": 1662665630638648800,
+    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
+    "ModifyIndex": 0,
+    "State": "active"
+  }
+}
+```
+
+## Delete Key
+
+This endpoint deletes a root key in the `inactive` state.
+
+| Method   | Path                               | Produces           |
+|----------|------------------------------------|--------------------|
+| `DELETE` | `/v1/operator/keyring/key/:key_id` | `application/json` |
+
+The table below shows this endpoint's support for [blocking queries] and
+[required ACLs].
+
+| Blocking Queries | ACL Required |
+|------------------|--------------|
+| `NO`             | `management` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+    -XDELETE \
+    https://localhost:4646/v1/operator/keyring/key/68237d9-1770-4d34-9c41-1f220107fc10
+```
+
+
+### Sample Response
+
+```json
+{
+  "Index": 16
+}
+```
+
+
+[Key Management]: /docs/concepts/key-management
+[`nomad operator root keyring`]: /docs/commands/operator/root/keyring
+[blocking queries]: /api-docs#blocking-queries
+[required ACLs]: /api-docs#acls

website/data/api-docs-nav-data.json

@@ -90,13 +90,17 @@
         "path": "operator/autopilot"
       },
       {
-        "title": "Raft",
-        "path": "operator/raft"
+        "title": "Keyring",
+        "path": "operator/keyring"
       },
       {
         "title": "License",
         "path": "operator/license"
       },
+      {
+        "title": "Raft",
+        "path": "operator/raft"
+      },
       {
         "title": "Scheduler",
         "path": "operator/scheduler"