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-docs#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-docs#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-docs#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-docs#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
|
|
```
|