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 enablying gossip erncryption 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.
- 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.
- 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
Generate a new gossip encryption key
Consul
Enable gossip encryption on an existing 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.
WAN Joined Datacenters Note: If using multiple WAN joined datacenters, be sure to use the same encryption key in all datacenters.
The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the
consul keygen
command to generate a
cryptographically suitable key:
$ consul keygen
pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
With that key, you can enable encryption on the agent. If encryption is enabled,
the output of consul agent
will include "Encrypt: true":
$ cat encrypt.json
{"encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="}
$ consul agent -data-dir=/tmp/consul -config-file=encrypt.json
==> WARNING: LAN keyring exists but -encrypt given, using keyring
==> WARNING: WAN keyring exists but -encrypt given, using keyring
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!
Node name: 'Armons-MacBook-Air.local'
Datacenter: 'dc1'
Server: false (bootstrap: false)
Client Addr: 127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, RPC: 8400)
Cluster Addr: 10.1.10.12 (LAN: 8301, WAN: 8302)
Gossip encrypt: true, RPC-TLS: false, TLS-Incoming: false
...
All nodes within a Consul cluster must share the same encryption key in order to send and receive cluster information.
Configuring Gossip Encryption on an existing cluster
As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster through the following process. Review this step-by-step tutorial to encrypt gossip on an existing cluster.