Gossip Encryption
This topics describes how to enable gossip encryption on a Consul datacenter.
Note
WAN federated datacenters: If using multiple WAN joined datacenters, be sure to use the same encryption key in all datacenters.
Enable gossip encryption
We recommend enabling gossip encryption to all new deployed Consul datacenters.
If you have an existing datacenter running Consul 0.8.4
and above, it is possible to modify its configuration to support gossip encryption.
Below are listed the steps required for both scenarios:
- Enable gossip encryption on a new datacenter
- Use
consul keygen
to generate a new gossip encryption key. - Create a configuration file that includes the
encrypt
parameter set to the newly generated key. - Distribute the configuration file to all the agent nodes that need to be pert of the datacenter and start the Consul agent on all the nodes.
- Use
- Enable gossip encryption on an existing datacenter
- Use
consul keygen
to generate a new gossip encryption key. - Create a configuration file that includes the
encrypt
parameter set to the newly generated key andencrypt_verify_incoming
andencrypt_verify_outgoing
set tofalse
. - Distribute the configuration file to all the agent nodes that need to be pert of the datacenter and perform a rolling restart of all the agents.
- Update the
encrypt_verify_outgoing
setting totrue
and perform a rolling restart of all the agents. - Update the
encrypt_verify_incoming
setting totrue
and perform a rolling restart of all the agents.
- Use
Enable gossip encryption on a new datacenter
Enabling gossip encryption only requires that you set an encryption key when
starting the Consul agent. The key can be set via the encrypt
parameter.
Enabling gossip encryption on a new datacenter is a straightforward process and should be the default approach for all new datacenters you are deploying.
Step 1: Generate an encryption key using
consul keygen
.$ consul keygen pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
Step 2: Create a configuration file that includes the
encrypt
parameter set to the newly generated key.<CodeTabs> <CodeBlockConfig filename="/etc/consul.d/encryption.hcl"> ```hcl encrypt = "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=" ``` </CodeBlockConfig> <CodeBlockConfig filename="/etc/consul.d/encryption.json"> ```json
{ "encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=" }
``` </CodeBlockConfig> </CodeTabs>
Step 3: Distribute the configuration file to all the agent nodes that need to be pert of the datacenter and start the Consul agent on all the nodes.
If gossip encryption is properly configured Gossip Encryption: true
will be shown in the logs at startup.
consul.log
==> Starting Consul agent...
Version: '1.19.0'
Build Date: '2024-06-12 13:59:10 +0000 UTC'
Node ID: 'e74b1ade-e932-1707-cdf1-6579b8b2536c'
Node name: 'consul-server-0'
Datacenter: 'dc1' (Segment: '<all>')
Server: true (Bootstrap: false)
Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: 8443, gRPC: -1, gRPC-TLS: 8503, DNS: 53)
Cluster Addr: 172.19.0.7 (LAN: 8301, WAN: 8302)
Gossip Encryption: true
Auto-Encrypt-TLS: true
ACL Enabled: true
Reporting Enabled: false
ACL Default Policy: deny
HTTPS TLS: Verify Incoming: false, Verify Outgoing: true, Min Version: TLSv1_2
gRPC TLS: Verify Incoming: false, Min Version: TLSv1_2
Internal RPC TLS: Verify Incoming: true, Verify Outgoing: true (Verify Hostname: true), Min Version: TLSv1_2
## ...
Enable gossip encryption on an existing datacenter
Gossip encryption can also be enabled on existing datacenters, but requires several extra steps.
Step 1: Generate an encryption key using
consul keygen
.$ consul keygen pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
Step 2: Create a configuration file that includes the
encrypt
parameter set to the newly generated key. Setencrypt_verify_incoming
andencrypt_verify_outgoing
tofalse
.<CodeTabs> <CodeBlockConfig filename="/etc/consul.d/encryption.hcl"> ```hcl encrypt = "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=" encrypt_verify_incoming = false encrypt_verify_outgoing = false ``` </CodeBlockConfig> <CodeBlockConfig filename="/etc/consul.d/encryption.json"> ```json
{ "encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=", "encrypt_verify_incoming": false, "encrypt_verify_outgoing": false }
``` </CodeBlockConfig> </CodeTabs>
Step 3: Distribute the configuration file to all the agent nodes that need to be pert of the datacenter and initiate a rolling update of all the agents with these new values. After this step, the agents will be able to decrypt gossip but will not yet be able to send encrypted traffic. A rolling update can be made by restarting the Consul agents (clients and servers) in turn.
consul reload
orkill -HUP <process_id>
is not sufficient to change the gossip configuration.Step 4: Update the
encrypt_verify_outgoing
setting totrue
and perform another rolling update of all the agents by restarting Consul on each agent. The agents will now be sending encrypted gossip but will still allow incoming unencrypted traffic. Complete the process on all the nodes before moving to the next step.<CodeTabs> <CodeBlockConfig filename="/etc/consul.d/encryption.hcl"> ```hcl encrypt = "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=" encrypt_verify_incoming = false encrypt_verify_outgoing = true ``` </CodeBlockConfig> <CodeBlockConfig filename="/etc/consul.d/encryption.json"> ```json
{ "encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=", "encrypt_verify_incoming": false, "encrypt_verify_outgoing": true }
``` </CodeBlockConfig> </CodeTabs>
Step 4: Update the
encrypt_verify_incoming
setting totrue
and perform a final rolling update on all the agents.<CodeTabs> <CodeBlockConfig filename="/etc/consul.d/encryption.hcl"> ```hcl encrypt = "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=" encrypt_verify_incoming = true encrypt_verify_outgoing = true ``` </CodeBlockConfig> <CodeBlockConfig filename="/etc/consul.d/encryption.json"> ```json
{ "encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=", "encrypt_verify_incoming": true, "encrypt_verify_outgoing": true }
``` </CodeBlockConfig> </CodeTabs>