HashiCorp Certified: Consul Associate Certification
Use Gossip Encryption
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
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