57f8ebfa26
* Adding check-legacy-links-format workflow * Adding test-link-rewrites workflow * chore: updates link checker workflow hash * Migrating links to new format Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
158 lines
3.9 KiB
Plaintext
158 lines
3.9 KiB
Plaintext
---
|
|
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]: /nomad/docs/operations/key-management
|
|
[`nomad operator root keyring`]: /nomad/docs/commands/operator/root/keyring-rotate
|
|
[blocking queries]: /nomad/api-docs#blocking-queries
|
|
[required ACLs]: /nomad/api-docs#acls
|