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

251 lines
7.7 KiB
Plaintext

---
layout: api
page_title: Keyring - Operator - HTTP API
description: |-
The /operator/keyring endpoints allow for management of the gossip encryption
keyring.
---
# Keyring Operator HTTP API
The `/operator/keyring` endpoints allow for management of the gossip encryption
keyring. Please see the [Gossip Protocol Guide](/consul/docs/architecture/gossip) for
more details on the gossip protocol and its use.
## List Gossip Encryption Keys
This endpoint lists the gossip encryption keys installed on both the WAN and LAN
rings of every known datacenter, unless otherwise specified with the `local-only`
query parameter (see below).
If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
read privileges.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `keyring:read` |
The corresponding CLI command is [`consul keyring -list`](/consul/commands/keyring#list).
### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
- `local-only` `(bool: false)` - Setting `local-only` to true will force keyring
list queries to only hit local servers (no WAN traffic). This flag can only be set
for list queries.
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/operator/keyring
```
### Sample Response
```json
[
{
"WAN": true,
"Datacenter": "dc1",
"Segment": "",
"Keys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1,
"ZWTL+bgjHyQPhJRKcFe3ccirc2SFHmc/Nw67l8NQfdk=": 1,
"WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4=": 1
},
"PrimaryKeys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1
},
"NumNodes": 3
},
{
"WAN": false,
"Datacenter": "dc1",
"Segment": "",
"Keys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1,
"ZWTL+bgjHyQPhJRKcFe3ccirc2SFHmc/Nw67l8NQfdk=": 1,
"WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4=": 1
},
"PrimaryKeys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1
},
"NumNodes": 3
}
]
```
- `WAN` is true if the block refers to the WAN ring of that datacenter (rather
than LAN).
- `Datacenter` is the datacenter the block refers to.
- `Segment` is the network segment the block refers to.
- `Keys` is a map of each gossip key to the number of nodes it's currently
installed on.
- `PrimaryKeys` is a map of each primary gossip key to the number of nodes it's currently
installed on.
- `NumNodes` is the total number of nodes in the datacenter.
## Add New Gossip Encryption Key
This endpoint installs a new gossip encryption key into the cluster.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `POST` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
The corresponding CLI command is [`consul keyring -install`](/consul/commands/keyring#install).
### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to install into
the cluster.
### Sample Payload
```json
{
"Key": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="
}
```
### Sample Request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
```
## Change Primary Gossip Encryption Key
This endpoint changes the primary gossip encryption key. The key must already be
installed before this operation can succeed.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `PUT` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
The corresponding CLI command is [`consul keyring -use`](/consul/commands/keyring#use).
### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to begin using as
primary into the cluster.
### Sample Payload
```json
{
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}
```
### Sample Request
```shell-session
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
```
## Delete Gossip Encryption Key
This endpoint removes a gossip encryption key from the cluster. This operation
may only be performed on keys which are not currently the primary key.
| Method | Path | Produces |
| -------- | ------------------- | ------------------ |
| `DELETE` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
The corresponding CLI command is [`consul keyring -remove`](/consul/commands/keyring#remove).
### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to delete.
### Sample Payload
```json
{
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}
```
### Sample Request
```shell-session
$ curl \
--request DELETE \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
```