Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
  • API Introduction
    • Consistency Modes
    • Blocking Queries
    • Filtering
    • Agent Caching

    • Overview
    • Tokens
    • Legacy Tokens
    • Policies
    • Roles
    • Auth Methods
    • Binding Rules
  • Admin Partitions
    • Overview
    • Checks
    • Services
    • Connect
  • Catalog
  • Cluster Peering
  • Config
    • Overview
    • Certificate Authority (CA)
    • Intentions
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
    • Overview
    • Area
    • Autopilot
    • Keyring
    • License
    • Raft
    • Segment
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs
Type '/' to Search

»Keyring Operator HTTP API

The /operator/keyring endpoints allow for management of the gossip encryption keyring. Please see the Gossip Protocol Guide 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.

MethodPathProduces
GET/operator/keyringapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonekeyring:read

The corresponding CLI command is consul 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

$ curl \
    http://127.0.0.1:8500/v1/operator/keyring
$ curl \
    http://127.0.0.1:8500/v1/operator/keyring

»Sample Response

[
  {
    "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": 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.

MethodPathProduces
POST/operator/keyringapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonekeyring:write

The corresponding CLI command is consul 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

{
  "Key": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="
}
{
  "Key": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="
}

»Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/operator/keyring
$ 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.

MethodPathProduces
PUT/operator/keyringapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonekeyring:write

The corresponding CLI command is consul 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

{
  "Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}
{
  "Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/operator/keyring
$ 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.

MethodPathProduces
DELETE/operator/keyringapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonekeyring:write

The corresponding CLI command is consul 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

{
  "Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}
{
  "Key": "WbL6oaTPom+7RG7Q/INbJWKy09OLar/Hf2SuOAdoQE4="
}

»Sample Request

$ curl \
    --request DELETE \
    --data @payload.json \
    http://127.0.0.1:8500/v1/operator/keyring
$ curl \
    --request DELETE \
    --data @payload.json \
    http://127.0.0.1:8500/v1/operator/keyring
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager