diff --git a/website/content/api-docs/operator/keyring.mdx b/website/content/api-docs/operator/keyring.mdx new file mode 100644 index 000000000..aed4787fd --- /dev/null +++ b/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 diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 7dec54398..53377090b 100644 --- a/website/data/api-docs-nav-data.json +++ b/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"