How to Migrate Vault Auto-Unseal to AWS KMS

This will be brief, as it's really easy! What follows are the steps required to migrate an existing HashiCorp Vault server from being sealed manually using Shamir keys (the default) to using auto-unseal with an AWS KMS key.

In the previous post I covered how to configure the AWS KMS and create a key that could be used by Vault. Now we're ready to use it.

Instructions

Gather the following information before beginning:

1. The AWS region where the IAM user and KMS key to be used for auto-unseal are hosted (e.g. eu-west-2)
2. The AccessKeyId for the IAM user Vault will use to connect to AWS KMS
3. The SecretAccessKey for the IAM user Vault will use to connect to AWS KMS
4. The KeyId of the AWS KMS key that will be used to auto-unseal Vault

Steps to migrate a server from Shamir-based seal to an AWS KMS-based seal:

Shutdown Vault

Connect via SSH to the Vault server with sufficient permissions tos tart and stop the Vault service and edit the configuration file.

1. Stop the Vault service using, for example:
   systemctl stop vault
2. Take a backup copy of the Vault server’s hcl file:
   cp /etc/vault.d/vault.hcl /etc/vault.d/vault.hcl.bak

Edit the vault.hcl file

Use your preferred text editor to open the Vault configuration file (usually /etc/vault.d/vault.hcl).

1. Add the following stanza (substituting the values for region, keys etc):
   seal "awskms" { region = "{{AWS Region}}" access_key = "{{AccessKeyId}}" secret_key = "{{SecretAccessKey}}" kms_key_id = "{{KeyId}}" }
2. Save the file.
3. Start the Vault service:
   systemctl start vault

Migrate the Vault Seal

If you watch the log message as Vault starts you might see it recognise that something has changed. However, the final step is to migrate the seal from Shamir keys to the AWS key.

1. Create an environment variable to allow Vault unseal commands to be supplied:
   export VAULT_ADDR=https://127.0.0.1:8200
2. Execute the following command three (3) times, assuming that 3 Shamir key shards are required to unseal Vault normally:
   vault operator unseal -migrate

Enter three different keys, as you would normally, to unseal Vault. Vault should now be unsealed and operational. Verify this by executing the vault status command. The original seal key shards become recovery keys.