github.com/outbrain/consul@v1.4.5/website/source/api/operator/keyring.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Keyring - Operator - HTTP API
     4  sidebar_current: api-operator-keyring
     5  description: |-
     6    The /operator/keyring endpoints allow for management of the gossip encryption
     7    keyring.
     8  ---
     9  
    10  # Keyring Operator HTTP API
    11  
    12  The `/operator/keyring` endpoints allow for management of the gossip encryption
    13  keyring. Please see the [Gossip Protocol Guide](/docs/internals/gossip.html) for
    14  more details on the gossip protocol and its use.
    15  
    16  ## List Gossip Encryption Keys
    17  
    18  This endpoint lists the gossip encryption keys installed on both the WAN and LAN
    19  rings of every known datacenter.
    20  
    21  If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
    22  read privileges.
    23  
    24  | Method | Path                         | Produces                   |
    25  | ------ | ---------------------------- | -------------------------- |
    26  | `GET`  | `/operator/keyring`          | `application/json`         |
    27  
    28  The table below shows this endpoint's support for
    29  [blocking queries](/api/index.html#blocking-queries),
    30  [consistency modes](/api/index.html#consistency-modes),
    31  [agent caching](/api/index.html#agent-caching), and
    32  [required ACLs](/api/index.html#acls).
    33  
    34  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required   |
    35  | ---------------- | ----------------- | ------------- | -------------- |
    36  | `NO`             | `none`            | `none`        | `keyring:read` |
    37  
    38  ### Parameters
    39  
    40  - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
    41    non-zero value will cause nodes to relay their responses through this many
    42    randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
    43    This is specified as part of the URL as a query parameter.
    44  
    45  ### Sample Request
    46  
    47  ```text
    48  $ curl \
    49      http://127.0.0.1:8500/v1/operator/keyring
    50  ```
    51  
    52  ### Sample Response
    53  
    54  ```json
    55  [
    56    {
    57      "WAN": true,
    58      "Datacenter": "dc1",
    59      "Segment": "",
    60      "Keys": {
    61        "0eK8RjnsGC/+I1fJErQsBA==": 1,
    62        "G/3/L4yOw3e5T7NTvuRi9g==": 1,
    63        "z90lFx3sZZLtTOkutXcwYg==": 1
    64      },
    65      "NumNodes": 1
    66    },
    67    {
    68      "WAN": false,
    69      "Datacenter": "dc1",
    70      "Segment": "",
    71      "Keys": {
    72        "0eK8RjnsGC/+I1fJErQsBA==": 1,
    73        "G/3/L4yOw3e5T7NTvuRi9g==": 1,
    74        "z90lFx3sZZLtTOkutXcwYg==": 1
    75      },
    76      "NumNodes": 1
    77    }
    78  ]
    79  ```
    80  
    81  - `WAN` is true if the block refers to the WAN ring of that datacenter (rather
    82     than LAN).
    83  
    84  - `Datacenter` is the datacenter the block refers to.
    85  
    86  - `Segment` is the network segment the block refers to.
    87  
    88  - `Keys` is a map of each gossip key to the number of nodes it's currently
    89    installed on.
    90  
    91  - `NumNodes` is the total number of nodes in the datacenter.
    92  
    93  ## Add New Gossip Encryption Key
    94  
    95  This endpoint installs a new gossip encryption key into the cluster.
    96  
    97  | Method | Path                         | Produces                   |
    98  | ------ | ---------------------------- | -------------------------- |
    99  | `POST` | `/operator/keyring`          | `application/json`         |
   100  
   101  The table below shows this endpoint's support for
   102  [blocking queries](/api/index.html#blocking-queries),
   103  [consistency modes](/api/index.html#consistency-modes),
   104  [agent caching](/api/index.html#agent-caching), and
   105  [required ACLs](/api/index.html#acls).
   106  
   107  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
   108  | ---------------- | ----------------- | ------------- | --------------- |
   109  | `NO`             | `none`            | `none`        | `keyring:write` |
   110  
   111  ### Parameters
   112  
   113  - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
   114    non-zero value will cause nodes to relay their responses through this many
   115    randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
   116    This is specified as part of the URL as a query parameter.
   117  
   118  - `Key` `(string: <required>)` - Specifies the encryption key to install into
   119    the cluster.
   120  
   121  ### Sample Payload
   122  
   123  ```json
   124  {
   125    "Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
   126  }
   127  ```
   128  
   129  ### Sample Request
   130  
   131  ```text
   132  $ curl \
   133      --request POST \
   134      --data @payload.json \
   135      http://127.0.0.1:8500/v1/operator/keyring
   136  ```
   137  
   138  ## Change Primary Gossip Encryption Key
   139  
   140  This endpoint changes the primary gossip encryption key. The key must already be
   141  installed before this operation can succeed.
   142  
   143  | Method | Path                         | Produces                   |
   144  | ------ | ---------------------------- | -------------------------- |
   145  | `PUT`  | `/operator/keyring`          | `application/json`         |
   146  
   147  The table below shows this endpoint's support for
   148  [blocking queries](/api/index.html#blocking-queries),
   149  [consistency modes](/api/index.html#consistency-modes),
   150  [agent caching](/api/index.html#agent-caching), and
   151  [required ACLs](/api/index.html#acls).
   152  
   153  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
   154  | ---------------- | ----------------- | ------------- | --------------- |
   155  | `NO`             | `none`            | `none`        | `keyring:write` |
   156  
   157  ### Parameters
   158  
   159  - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
   160    non-zero value will cause nodes to relay their responses through this many
   161    randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
   162    This is specified as part of the URL as a query parameter.
   163  
   164  - `Key` `(string: <required>)` - Specifies the encryption key to begin using as
   165    primary into the cluster.
   166  
   167  ### Sample Payload
   168  
   169  ```json
   170  {
   171   "Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
   172  }
   173  ```
   174  
   175  ### Sample Request
   176  
   177  ```text
   178  $ curl \
   179      --request PUT \
   180      --data @payload.json \
   181      http://127.0.0.1:8500/v1/operator/keyring
   182  ```
   183  
   184  ## Delete Gossip Encryption Key
   185  
   186  This endpoint removes a gossip encryption key from the cluster. This operation
   187  may only be performed on keys which are not currently the primary key.
   188  
   189  | Method  | Path                         | Produces                   |
   190  | ------- | ---------------------------- | -------------------------- |
   191  | `DELETE`| `/operator/keyring`          | `application/json`         |
   192  
   193  The table below shows this endpoint's support for
   194  [blocking queries](/api/index.html#blocking-queries),
   195  [consistency modes](/api/index.html#consistency-modes),
   196  [agent caching](/api/index.html#agent-caching), and
   197  [required ACLs](/api/index.html#acls).
   198  
   199  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
   200  | ---------------- | ----------------- | ------------- | --------------- |
   201  | `NO`             | `none`            | `none`        | `keyring:write` |
   202  
   203  ### Parameters
   204  
   205  - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
   206    non-zero value will cause nodes to relay their responses through this many
   207    randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
   208    This is specified as part of the URL as a query parameter.
   209  
   210  - `Key` `(string: <required>)` - Specifies the encryption key to delete.
   211  
   212  ### Sample Payload
   213  
   214  ```json
   215  {
   216   "Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
   217  }
   218  ```
   219  
   220  ### Sample Request
   221  
   222  ```text
   223  $ curl \
   224      --request DELETE \
   225      --data @payload.json \
   226      http://127.0.0.1:8500/v1/operator/keyring
   227  ```