How to migrate from a single Vault server to a local cluster without losing secrets

Vault
1

I have a vault server which runs as a single server with raft as storage. It uses shamir type of seal with 5 shares and three thresholds.
Since I encountered situations in which vault times out, and saw in the documentation that for raft storage is indicated to run at least 3-5 servers in a cluster I tried to run a local cluster following this tutorial specificaly raft storage. I could set it up using the documentation for it.

The problem was that I wanted to copy the secrets from the vault instance(single server) to the cluster. Here I tried to make a snapshot and then restore it in the cluster.
The command used in the local cluster to restore the snapshot was:

vault operator raft snapshot restore  -force ./path/to/.snapshot

Then I unsealed the vault using three thresholds from the original vault server:

vault operator unseal -migrate

As you can see, since the seal type differs in both I had to use -force flag and then -migrate in the command which unsealed the vault in the cluster.

Now it is not clear for me if the auto unseal (using a transit key generated by vault_1) is broken now, since I had to unseal it manually using three thresholds. Running vault status command after applying the snapshot returns:

Key Value

---

Seal Type transit
Recovery Seal Type shamir
Initialized true
Sealed false
Total Recovery Shares 5
Threshold 3
Version 1.20.0
Build Date 2025-06-23T10:21:30Z
Storage Type raft
Cluster Name vault-cluster-daxxxxxx
Cluster ID 8xxxxxxxx-xxx
Removed From Cluster false
HA Enabled true
HA Cluster [https://127.0.0.3:8201](https://127.0.0.3:8201/)
HA Mode standby
Active Node Address [http://127.0.0.3:8200](http://127.0.0.3:8200/)
Raft Committed Index 22612
Raft Applied Index 22612

What is the right approach to migrate from vault which runs as a single server to a vault cluster. How do we copy the secrets along with policies between different vault architectures ?

2

You are correct in that HashiCorp recommends using 3/5/7 nodes when using raft/integrated storage. Since you already have a single server with raft/integrated storage running, I’m thinking you could add more nodes to make it a cluster, without having to manually migrate data. Vault would then handle all the data transfer throughout the new nodes.

You should be able to spin up 2 new servers, and join them using the vault operator raft join command.

If raft is used for storage , the node must be joined before unsealing and the leader-api-addr argument must be provided.

You then can run vault operator raft list-peers to confirm the nodes are added to form a multi-node cluster.

3

@michaelkosir Using the command provided will join the second server to the cluster and the sealing option will remain the same for the second server (three thresholds) right ? Is it possible to migrate to a Transit key option for unsealing so that the other servers connected to the cluster unseal automatically?

4

That is correct. If your current single node Vault instance is using Shamir keys for unseal, adding two more nodes (using the commands above) to form a 3-node cluster will still use the original Shamir keys for unsealing all the nodes within the cluster.

If you then want to migrate seal mechanisms, I would treat that as a separate step, and perform it either before or after joining the new nodes.

An important note, you cannot perform the seal migration process without downtime. Be sure to create a backup before you start the seal migration process, in case something goes wrong. Be sure to checkout the seal migrations concepts and documentation.

Additionally, Transit for auto-unseal would require another Vault cluster, similar to the diagram below. Be sure to read all the best practices when it comes to the Transit auto-unseal mechanism.

image
image1397×677 25.8 KB