How to Change the Vault Hostname on a Raft Cluster

Overview

This article will detail how to change the hostname on a leader or follower Vault node operating in a Raft cluster. The details are specifically for changing the leader, but can be repurposed for any node in the cluster. Leadership election in this case is done automatically using the Raft Consensus Protocol. The third host requires no actions in this scenario, so is not referenced. 

Prerequisites

•  A working Vault cluster with a Raft storage backend.

Procedure

1. Stop the Vault service on the leader node. The remaining followers will automatically elect a new Raft leader.

2. Change the hostname on the original leader node by updating the Vault configuration file:

   1. Change the Raft confignode_id.

   2. If the api_addr & cluster_addr values use domain names, update these accordingly.

3. Delete the old Raft storage on the same original leader node.

4. From the original follower node that has since been elected as leader, remove the original leader node ID with vault operator raft remove-peer <old domain name>.

5. Start the Vault service on the original leader node. Raft will automatically recreate a new database.

6. On the updated follower node, rejoin the Raft cluster using the vault operator raft join https://<secondary hostname>:8200 command.

7. Verify that the updated follower node has rejoined the cluster with the new hostname and node ID with vault operator raft list-peers on both the leader and follower nodes.

8. Wait for the Raft database to replicate on your updated follower node. You can verify that this has been done by running the vault status command and verifying the Raft Committed and Applied Indexes between nodes. Also, by logging in with a token/method from the cluster and running a vault secrets list to make sure the displayed data matches that on the current leader. These steps ensure that both the token has replicated and that the secrets are up-to-date with the leader node.

9. Repeat the process as necessary across nodes within the cluster.

Additional Information

• Raft Integrated Storage