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

251 lines
7.5 KiB
Plaintext
Raw Normal View History

2017-04-04 16:33:22 +00:00
---
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
2017-04-04 16:33:22 +00:00
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
2020-04-06 20:27:35 +00:00
rings of every known datacenter, unless otherwise specified with the `local-only`
query parameter (see below).
2017-04-04 16:33:22 +00:00
If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
read privileges.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/operator/keyring` | `application/json` |
2017-04-04 16:33:22 +00:00
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).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `keyring:read` |
2017-04-04 16:33:22 +00:00
The corresponding CLI command is [`consul keyring -list`](/commands/keyring#list).
2022-01-10 19:21:32 +00:00
### Query Parameters
2017-04-04 16:33:22 +00:00
- `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`.
2020-04-06 20:27:35 +00:00
- `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.
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/operator/keyring
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"WAN": true,
"Datacenter": "dc1",
"Segment": "",
2017-04-04 16:33:22 +00:00
"Keys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1,
"ZWTL+bgjHyQPhJRKcFe3ccirc2SFHmc/Nw67l8NQfdk=": 1,
"WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4=": 1
2017-04-04 16:33:22 +00:00
},
"PrimaryKeys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1
},
"NumNodes": 3
2017-04-04 16:33:22 +00:00
},
{
"WAN": false,
"Datacenter": "dc1",
"Segment": "",
2017-04-04 16:33:22 +00:00
"Keys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1,
"ZWTL+bgjHyQPhJRKcFe3ccirc2SFHmc/Nw67l8NQfdk=": 1,
"WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4=": 1
2017-04-04 16:33:22 +00:00
},
"PrimaryKeys": {
"pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=": 1
},
"NumNodes": 3
2017-04-04 16:33:22 +00:00
}
]
```
- `WAN` is true if the block refers to the WAN ring of that datacenter (rather
2020-04-06 20:27:35 +00:00
than LAN).
2017-04-04 16:33:22 +00:00
- `Datacenter` is the datacenter the block refers to.
- `Segment` is the network segment the block refers to.
2017-04-04 16:33:22 +00:00
- `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.
2017-04-04 16:33:22 +00:00
- `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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `POST` | `/operator/keyring` | `application/json` |
2017-04-04 16:33:22 +00:00
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).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
2017-04-04 16:33:22 +00:00
2022-01-20 16:54:23 +00:00
The corresponding CLI command is [`consul keyring -install`](/commands/keyring#install).
2022-01-10 19:21:32 +00:00
### Query Parameters
2017-04-04 16:33:22 +00:00
- `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
2017-04-04 16:33:22 +00:00
- `Key` `(string: <required>)` - Specifies the encryption key to install into
the cluster.
### Sample Payload
```json
{
"Key": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
2017-04-04 16:33:22 +00:00
```
## Change Primary Gossip Encryption Key
This endpoint changes the primary gossip encryption key. The key must already be
installed before this operation can succeed.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `PUT` | `/operator/keyring` | `application/json` |
2017-04-04 16:33:22 +00:00
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).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
2017-04-04 16:33:22 +00:00
The corresponding CLI command is [`consul keyring -use`](/commands/keyring#use).
2022-01-10 19:21:32 +00:00
### Query Parameters
2017-04-04 16:33:22 +00:00
- `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
2017-04-04 16:33:22 +00:00
- `Key` `(string: <required>)` - Specifies the encryption key to begin using as
primary into the cluster.
### Sample Payload
```json
{
2020-04-06 20:27:35 +00:00
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
2017-04-04 16:33:22 +00:00
```
## 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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| -------- | ------------------- | ------------------ |
| `DELETE` | `/operator/keyring` | `application/json` |
2017-04-04 16:33:22 +00:00
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).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `keyring:write` |
2017-04-04 16:33:22 +00:00
The corresponding CLI command is [`consul keyring -remove`](/commands/keyring#remove).
2022-01-10 19:21:32 +00:00
### Query Parameters
2017-04-04 16:33:22 +00:00
- `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
2017-04-04 16:33:22 +00:00
- `Key` `(string: <required>)` - Specifies the encryption key to delete.
### Sample Payload
```json
{
2020-04-06 20:27:35 +00:00
"Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request DELETE \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/keyring
2017-04-04 16:33:22 +00:00
```