Migration guide
This page contains a guide to migrate a HashiCorp Vault cluster to OpenBao.
This guide assumes in-place upgrade, that is, OpenBao will replace the Vault server process on all nodes. All configuration, including all endpoints and URLs will remain unchanged.
OpenBao API should be compatible with Vault to the extent that existing clients should not even register a difference.
Some clients/service might have to be restarted.
Constraints
- Vault version 1.14.1 (OSS)
- OpenBao version 2.2.0
- Raft storage
- Shamir unseal (no auto-unseal)
Previous (and future) OpenBao versions will probably work fine. However, this guide was tested with OpenBao 2.2.0 with Shamir unseal.
Only the community edition (v1.14.x) Vault was tested, not Vault Enterprise.
Limitations
If your Vault version is lower than 1.14.1, upgrade to v1.14.1.
This guide will not work on Vault versions 1.15.0 and newer; use at your own risk.
If your Vault has been bootstrapped with Vault version < 1.3, you may need to rekey. Vault pre 1.3 used a different Shamir seal implementation which has been removed from OpenBao.
This guide is based on a fairly simple setup, ymmv.
Plugins
OpenBao comes without many plugins by default. If your plugin isn't included, you may need to resort to some workarounds. This guide assumes no external plugins (external to Bao) are used.
Known issues
Check known-issues documentation to get familiar with currently known problems and issues of the latest release.
Breaking changes
- OpenBao uses a different type of
tokens
in the form of
[sbr].<random>while Vault uses much longer tokens ({hvs,hvb,hvr}.<long_random>). Old tokens will still be accepted according to their TTLs. However, newly issued tokens will have the Bao form. This is not a breaking change on Bao side but it might break some assupmtions consumers make about the token format. Make sure your consumers are aware of this change.
Preparation
Backup
Make a backup of your data! A raft snapshot will do. So will a filesystem snapshot so long as your filesystem supports atomic snapshots (like ZFS or BTRFS).
Install and configure OpenBao
Make sure to have OpenBao installed and configured, but not started on your nodes. The configuration is largely compatible.
It is recommended to use different storage path for the OpenBao instance. The nodes will pull the data from the cluster when joining, there is no need to reuse existing data. This also has the added benefit that a rollback is slightly easier in case it's needed.
If you use Vault audit file backend, you need to make sure OpenBao
can write to the existing file. In most cases this means something
like chown openbao:openbao vault_audit_log.log. You need to do this
after you stop the Vault instance a node.
If you have disable_mlock in your Vault config, remove it. OpenBao does
not use mlock since 2.0.0.
Upgrade the cluster
In this guide we do not rely on Autopilot
Make a note of which node is the leader:
$ vault status
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
...
Active Node Address https://vault-03.example.com:8200
...
or
curl https://vault.example.com:8200/v1/sys/leader
One by one, upgrade the follower nodes first.
- stop Vault service
- start OpenBao service
- join the node to the cluster
$ bao operator raft join vault-03.example.com:8200 - unseal the node
$ bao operator unseal - wait until the node becomes a voter (Voter field is
true) Assuming you just joined nodevault-04:$ bao operator raft list-peers
Node Address State Voter
---- ------- ----- -----
...
vault-04 172.17.13.4:8201 follower false
...
Repeat for for all follower nodes.
Once all followers run OpenBao, upgrade the leader like this:
First make sure the leader steps down:
VAULT_ADDR=https://vault-03.example.com:8200 vault operator step-down
Make sure the cluster elected a new leader:
$ vault status
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
...
Active Node Address https://vault-01.example.com:8200
...
Repeat steps 1 through 5 above on the former leader, except in step 3 use the current leader address.