Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

Rotating gossip encryption keys in your Consul cluster helps maintain strong security posture. In this tutorial, we’ll walk through:
  1. Reviewing the current configuration
  2. Generating a new encryption key
  3. Distributing the key across the cluster
  4. Promoting the new key to primary
  5. Removing the old key

​
1. Review Current Configuration

Inspect your existing gossip encryption key in consul.d/config.hcl: 
{
  "log_level": "INFO",
  "node_name": "consul-node-b",
  "server": true,
  "ui": true,
  "leave_on_terminate": true,
  "data_dir": "/etc/consul.d/data",
  "datacenter": "us-east-1",
  "client_addr": "0.0.0.0",
  "bind_addr": "10.0.101.248",
  "advertise_addr": "10.0.101.248",
  "retry_join": ["10.0.101.110"],
  "bootstrap_expect": 2,
  "enable_syslog": true,
  "encrypt": "62qD/DH15Ax0lMRUpMKvttP53p4FAvu+FgARDU4MzA=",
  "encrypt_verify_incoming": true,
  "encrypt_verify_outgoing": true,
  "connect": {
    "enabled": true
  },
  "acl": {
    "enabled": true,
    "default_policy": "allow",
    "down_policy": "extend-cache"
  },
  "performance": {}
}
Before you begin, back up your Consul configuration and data directory. This ensures you can recover quickly if something goes wrong.

​
2. Generate a New Gossip Encryption Key

Run the following command on any Consul server or client to create a fresh base64-encoded key: 
consul keygen
# Example output:
wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=

​
3. Distribute the New Key Across the Cluster

Install the newly generated key into the cluster keyring: 
consul keyring -install wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=
You should see: 
Installing new key "wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4="

​
3.1. Verify Key Distribution

On another node, list installed keys: 
consul keyring -list
Expected output: 
==> Gathering installed encryption keys...
us-east-1 (LAN):
  62qD/DH15Ax0lMRUpMKvttP53p4FAvu+FgARDU4MzA=  [2/2]
  wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=  [2/2]

​
4. Promote the New Key to Primary

Switch the cluster’s primary gossip encryption key: 
consul keyring -use wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=
You’ll see: 
Changing primary gossip encryption key to "wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4="
Confirm the change: 
consul keyring -list
Should display the new key first under both WAN and LAN segments.

​
5. Remove the Old Encryption Key

Once every node is using the new key, remove the old one: 
consul keyring -remove 62qD/DH15Ax0lMRUpMKvttP53p4FAvu+FgARDU4MzA=
Output: 
Removing encryption key "62qD/DH15Ax0lMRUpMKvttP53p4FAvu+FgARDU4MzA="
Verify only the new key remains: 
consul keyring -list

==> Gathering installed encryption keys...
WAN:
  wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=  [2/2]
us-east-1 (LAN):
  wlVkhlSnyl7SEy63/XsXMJ/48gIQSghShhUqn/05C4=  [2/2]
Do not remove the old key until all nodes report the new key as primary. Premature removal can lead to cluster partitions and service disruptions.

​
Command Reference

CommandDescription
consul keygenGenerates a new base64-encoded key
consul keyring -install <key>Installs a key into the cluster keyring
consul keyring -listLists installed keys and their usage counts
consul keyring -use <key>Promotes a key to be the primary encryption key
consul keyring -remove <key>Deletes an old key from the keyring

Watch Video

Practice Lab