Starting with version 1.0.0, Vault now supports cloud based seals with auto-unsealing capabilities in the Open Source edition and as part of this feature introduction, a new migrate
flag was added to the /sys/unseal API and vault operator unseal CLI.
This guide describes the migrate
flag usage with some helpful example migration scenarios and resources to assist with your own seal migration needs.
NOTE: Please ensure that you have a backup of your Vault data (for example with a Consul snapshot if using Consul storage, a Vault snapshot if using Raft storage, or by using the backup tool for your storage before proceeding with the migration.
Migrate from Shamir Seal Type to Cloud Seal Type
The most common case for migrate
is to update a Shamir seal-based Vault to use a cloud seal with auto-unseal capabilities.
In the following example the process is described for migrating from an existing Shamir seal type to GCP KMS seal type.
- Stop all Vault servers
- Update all of the Vault servers’ configuration to include the appropriate
seal
stanza; see the seal Stanza and documentation for the seal you will use. In this case, we’d consul the gcpckms Seal documentation; updating this can be done in one of two ways:
- If you use a single configuration file, you must update it and add the
seal
stanza to the top-level configuration, not underlistener
orstorage
, for example - If your Vault configuration is modular / consists of multiple configuration files, consider adding a new file such as
seal.hcl
with the seal stanza contents instead
# Example seal stanza
seal "gcpckms" {
# The raw JSON token for the GCP service account to use:
credentials = "/usr/vault/vault-project-user-creds.json"
# The GCP project name:
project = "vault-project"
# The GCP region name:
region = "global"
# The GCP encryption key key ring name:
key_ring = "vault-keyring"
# The GCP encryption key name:
crypto_key = "vault-key"
}
- Start a single Vault server
- Unseal the server using the command:
vault operator unseal -migrate
- Enter all the remaining unseal keys; these keys must also be entered with the
-migrate
flag ensuring everyone involved in the migration is aware - Observe that the Vault server is functional with e.g.
vault status
and by login / secret retrieval, etc. - Provided that the Vault server appears operational, start and unseal remaining servers in the same way
Once all unseal keys are provided, and the migrate
flag is present, the current Shamir shares will become the Recovery Keys for the seal and a new master key will be generated, the encryption key will be encrypted with the new master key, and the master key will be encrypted with the seal and stored in the storage backend.
Subsequent restarting of Vault servers going forward should then result in them automatically unsealing.
Migrate from Cloud Seal Type to Shamir Seal Type
While not as common as the first case, but also handy for multiple migration paths, this example shows how one might migrate from an existing GCP KMS seal type to the Shamir seal type.
- Stop all Vault servers
- Update the Vault server’s configuration’s appropriate
seal
stanza to include adisabled = "true"
option (note that true is a string and must be quoted in this case); updating this can be done in one of two ways:
- If you use a single configuration file, you must update it and add the
disabled = "true"
option to theseal
stanza - If your Vault configuration is modular / consists of multiple configuration files, edit the appropriate file and add
disabled = "true"
to theseal
stanza to update it
# Example seal stanza
seal "gcpckms" {
# The raw JSON token for the GCP service account to use:
credentials = "/usr/vault/vault-project-user-creds.json"
# The GCP project name:
project = "vault-project"
# The GCP region name:
region = "global"
# The GCP encryption key key ring name:
key_ring = "vault-keyring"
# The GCP encryption key name:
crypto_key = "vault-key"
# Disable this seal type
disabled = "true"
}
- Start a single Vault server
- Initiate an unseal using the command and enter the first recovery key:
vault operator unseal -migrate
- Enter all the remaining unseal keys; these keys must also be entered with the
-migrate
flag ensuring everyone involved in the migration is aware - Observe that the Vault server is functional with e.g.
vault status
and by login / secret retrieval, etc. - Provided that the Vault server appears operational, start and unseal remaining servers in the same way
Once all recovery keys have been entered, the encryption key will be encrypted with the recovery key generated master key, the recovery key and stored Auto Unseal master key will be deleted, and Vault will again become unsealed.
When disabling the seal, it will no long be used to unseal Vault but the credentials will still be available for any migration that is issued.
Migrate from Cloud Seal Type to Different Cloud Seal Type
The migrate
flag does not currently support direct migration of seal type from one cloud based seal type to another.
Instead, you can use the steps described above to migrate from the source cloud seal type to a Shamir based seal type, and then migrate from the Shamir based seal type to the target cloud based seal type.
Resources
Help is available in the CLI:
vault operator unseal --help
and from these web resources: