Configure Gossip Encryption

Consul’s gossip protocol communicates in clear text by default, making it unsuitable for production clusters. Enabling gossip encryption ensures all cluster communication remains confidential and tamper-proof.

Warning

Never expose an unencrypted Consul gossip layer to public or untrusted networks. Always enable encryption in production.

Initial Configuration

To activate gossip encryption on a new Consul agent, add the encrypt key to your agent’s JSON configuration (e.g., /etc/consul.d/agent-config.json):

{
  "log_level": "INFO",
  "server": true,
  "data_dir": "/opt/consul/data",
  "datacenter": "us-east-1",
  "ui": true,
  "key_file": "/etc/consul.d/cert.key",
  "cert_file": "/etc/consul.d/client.pem",
  "ca_file": "/etc/consul.d/chain.pem",
  "verify_incoming": true,
  "verify_outgoing": true,
  "verify_server_hostname": true,
  "encrypt": "HdQYxqepkYRADn4Zn+uD9vLge8WM+LpFAPLGhtco=",
  "leave_on_terminate": true
}

Generate a new gossip key:
```
consul keygen
```
Copy the output and paste it into the "encrypt" field above.
Restart or start the Consul agent:
```
systemctl restart consul
```

Alternatively, you can pass the key on the command line:

consul agent \
  -server \
  -data-dir=/opt/consul/data \
  -encrypt=HdQYxqepkYRADn4Zn+uD9vLge8WM+LpFAPLGhtco= \
  [...]

Key Parameters Overview

Parameter	Description
encrypt	Base64-encoded key for gossip encryption
verify_incoming	Validate incoming TLS connections
verify_outgoing	Validate outgoing TLS connections
verify_server_hostname	Enforce server hostname verification
leave_on_terminate	Gracefully leave cluster on agent shutdown

Modifying an Existing Cluster

The image is a slide titled "Modifying an Existing Cluster," explaining how to configure a cluster with gossip encryption, including the need for rolling restarts and two specific parameters.

You can introduce gossip encryption without downtime by performing a controlled rolling restart. Note that consul reload does not apply encryption changes—you must restart each agent (systemctl restart consul).

Two flags manage the transition phase:

Flag	Purpose
encrypt_verify_incoming	Enforce encryption for incoming messages
encrypt_verify_outgoing	Enforce encryption for outgoing messages

Follow these steps:

Generate a new encryption key

consul keygen
# encrypt: hqYxqeqpkYrADn4Zn+u+D9vLge8Wm+LpFAPLGhtco=

Distribute the key and disable enforcement
Update each agent’s config:

{
  "encrypt": "hqYxqeqpkYrADn4Zn+u+D9vLge8Wm+LpFAPLGhtco=",
  "encrypt_verify_incoming": false,
  "encrypt_verify_outgoing": false
}

Rolling restart #1
```
systemctl restart consul
```
Enable outgoing encryption
```
{
  "encrypt_verify_outgoing": true
}
```
Rolling restart #2
```
systemctl restart consul
```
Enable incoming encryption
```
{
  "encrypt_verify_incoming": true
}
```
Rolling restart #3
```
systemctl restart consul
```

After completing these steps, your entire cluster will encrypt gossip traffic using the new key. For production environments, integrate these steps into your configuration management or orchestration tool of choice.

Links and References

Watch Video

Watch video content