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

240 lines
7.3 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
2020-04-09 23:46:54 +00:00
keyring. Please see the [Gossip Protocol Guide](/docs/internals/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
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### 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`.
This is specified as part of the URL as a query parameter.
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. It is specified as part of the URL as a query parameter.
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
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### 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`.
This is specified as part of the URL as a query parameter.
- `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
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### 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`.
This is specified as part of the URL as a query parameter.
- `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
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### 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`.
This is specified as part of the URL as a query parameter.
- `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
```