Seal Migration

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.

1. Stop all Vault servers
2. 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:

1. If you use a single configuration file, you must update it and add the seal stanza to the top-level configuration, not under listener or storage, for example
2. If your Vault configuration is modular / consists of multiple configuration files, consider adding a new file such asseal.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"
}

3. Start a single Vault server
4. Unseal the server using the command: vault operator unseal -migrate
5. Enter all the remaining unseal keys; these keys must also be entered with the -migrate flag ensuring everyone involved in the migration is aware
6. Observe that the Vault server is functional with e.g. vault status and by login / secret retrieval, etc.
7. 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.

1. Stop all Vault servers
2. Update the Vault server’s configuration’s appropriate seal stanza to include a disabled = "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:

1. If you use a single configuration file, you must update it and add the disabled = "true" option to the seal stanza
2. If your Vault configuration is modular / consists of multiple configuration files, edit the appropriate file and add disabled = "true" to the seal 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"
}

3. Start a single Vault server
4. Initiate an unseal using the command and enter the first recovery key: vault operator unseal -migrate
5. Enter all the remaining unseal keys; these keys must also be entered with the -migrate flag ensuring everyone involved in the migration is aware
6. Observe that the Vault server is functional with e.g. vault status and by login / secret retrieval, etc.
7. 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:

1. seal Stanza
2. /sys/unseal API
3. vault operator unseal CLI
4. gcpckms Seal