daf5e3ea10
Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
251 lines
7.5 KiB
Plaintext
251 lines
7.5 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](/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](/api-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------- |
|
|
| `NO` | `none` | `none` | `keyring:read` |
|
|
|
|
The corresponding CLI command is [`consul keyring -list`](/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](/api-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | --------------- |
|
|
| `NO` | `none` | `none` | `keyring:write` |
|
|
|
|
The corresponding CLI command is [`consul keyring -install`](/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](/api-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | --------------- |
|
|
| `NO` | `none` | `none` | `keyring:write` |
|
|
|
|
The corresponding CLI command is [`consul keyring -use`](/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](/api-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | --------------- |
|
|
| `NO` | `none` | `none` | `keyring:write` |
|
|
|
|
The corresponding CLI command is [`consul keyring -remove`](/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
|
|
```
|