Introduction
The keyring command is used to examine and modify the encryption keys used in Consul’s Gossip Pools. It is capable of distributing new encryption keys to the cluster, retiring old encryption keys, and changing the keys used by the cluster to encrypt messages.
Use Case
The key idea is to utilize Consul keyring to rotate gossip keys and ensure all the nodes use the same Gossip Key. Otherwise, it will be cumbersome to update gossip key for a cluster with large number of nodes.
Procedure
-
List your current keys and verify that all nodes have the proper key
[root@consul-server-1 ~]# consul keyring -list ==> Gathering installed encryption keys... WAN: EJbKPoWYlR32wp8pKJUIeA== [3/3] dc1 (LAN): EJbKPoWYlR32wp8pKJUIeA== [11/11] -
Generate a new key using consul keyring
[root@consul-server-1 ~]# consul keygen T10PI3J63ghegokJRLhNlg== -
Add your newly generated key to the keyring
[root@consul-server-1 ~]# consul keyring -install T10PI3J63ghegokJRLhNlg== ==> Installing new gossip encryption key... -
Verify that the key has been spread throughout the cluster
[root@consul-server-1 ~]# consul keyring -list ==> Gathering installed encryption keys... WAN: T10PI3J63ghegokJRLhNlg== [3/3] EJbKPoWYlR32wp8pKJUIeA== [3/3] dc1 (LAN): EJbKPoWYlR32wp8pKJUIeA== [11/11] T10PI3J63ghegokJRLhNlg== [11/11] -
Promote the new key to primary.
[root@consul-server-1 ~]# consul keyring -use T10PI3J63ghegokJRLhNlg== ==> Changing primary gossip encryption key... -
Remove the old primary from the keyring.
[root@consul-server-1 ~]# consul keyring -remove EJbKPoWYlR32wp8pKJUIeA== ==> Removing gossip encryption key... -
Verify that the keyring contains only one key.
[root@consul-server-1 ~]# consul keyring -list ==> Gathering installed encryption keys... WAN: T10PI3J63ghegokJRLhNlg== [3/3] dc1 (LAN): T10PI3J63ghegokJRLhNlg== [11/11]
Additional Information
To learn how to setup gossip encryption on new and existing cluster, visit the following guide on HashiCorp Lean.