Introduction
As your application evolves, you may need to reorganize your secrets for better management and security. In this step-by-step guide, we will walk you through the process of migrating KV secrets stored in Vault to a new path (or rename a path) . By the end of this tutorial, you'll have the knowledge and confidence to seamlessly move your secrets to a new location while ensuring their integrity and accessibility.
Step 1: Backup Your Existing Data
Before proceeding with any major changes, it is essential to back up your existing data to ensure data integrity and safety. Please review this step before moving forward:
https://developer.hashicorp.com/vault/tutorials/standard-procedures/sop-backup
Step 2: Create a Policy for Managing Secrets
To perform the migration, we'll need a policy with appropriate capabilities. Let's create a policy named "kv-admin" that grants the necessary access for managing secrets.
https://developer.hashicorp.com/vault/docs/concepts/policies
$ vault policy write kv-admin - << EOF
path "sys/mounts/kv/vault/zaid/*" {
capabilities = ["create", "update", "list"]
}
path "kv/vault/zaid/*" {
capabilities = ["create", "read", "update", "patch", "delete", "list"]
}
path "sys/remount" {
capabilities = ["create", "update", "sudo"]
}
path "sys/remount/status/*" {
capabilities = ["read"]
}
path "sys/mounts" {
capabilities = ["read"]
}
EOF
Explanation: The policy "kv-admin" allows users to create, read, update, and delete secrets under the path "kv/vault/zaid/". It also grants access to manage mounts and remount secrets.
Step 3: Create a Token with the "kv-admin" Policy
Now, let's create a token with the "kv-admin" policy so that we can interact with Vault using this token.
https://developer.hashicorp.com/vault/docs/commands/token/create#examples
$ vault token create -period=360m -policy=kv-admin
This command will generate a new token with the "kv-admin" policy attached to it. Login using the token generated above.
https://developer.hashicorp.com/vault/docs/commands/login#examples
Step 4: Enable the Secret Engine
In this step, we'll enable the secret engine to store our secrets. Let's enable the "kv-v2" secrets engine at the path "kv/vault/zaid/hc".
https://developer.hashicorp.com/vault/docs/commands/secrets/enable
$ vault secrets enable -path=kv/vault/zaid/hc kv-v2
Success! The "kv-v2" secrets engine is now enabled at the path "kv/vault/zaid/hc/".
Step 5: Write Secrets to the Old Path
Now, let's write some secrets to the old path "kv/vault/zaid/hc/".
$ for i in {1..5}; do sleep 1; vault kv put kv/vault/zaid/hc/$i-secret id="$((i+5))"; done
This loop will create five secrets with different IDs under the path "kv/vault/zaid/hc/".
Step 6: Verify Secrets in the Old Path
Let's verify that the secrets have been successfully written to the old path.
https://developer.hashicorp.com/vault/docs/commands/kv/list
$ vault kv list kv/vault/zaid/hc
Keys
----
1-secret
2-secret
3-secret
4-secret
5-secret
This command will list all the keys (secrets) present under the old path "kv/vault/zaid/hc/".
Step 7: Start the Migration Process
Before we proceed, ensure you have a clear plan for the new path where you want to migrate the secrets. In this step, we'll start the migration process to move the secrets from the old path "kv/vault/zaid/hc/" to the new path "kv/vault/zaid/hashicorp/".
https://developer.hashicorp.com/vault/docs/commands/secrets/move
$ vault secrets move kv/vault/zaid/hc kv/vault/zaid/hashicorp
Started moving secrets engine kv/vault/zaid/hc/ to kv/vault/zaid/hashicorp/, with migration ID 92a710d6-bd87-7f79-9af8-586bfb8cc020
Waiting for terminal status in migration of secrets engine kv/vault/zaid/hc/ to kv/vault/zaid/hashicorp/, with migration ID 92a710d6-bd87-7f79-9af8-586bfb8cc020
Success! Finished moving secrets engine kv/vault/zaid/hc/ to kv/vault/zaid/hashicorp/, with migration ID 92a710d6-bd87-7f79-9af8-586bfb8cc020
The secrets engine migration has been initiated. Vault will move the secrets from the old path to the new path.
Step 8: Monitor the Progress of the Migration
Let's monitor the progress of the migration to ensure it completes successfully. Please ensure that you use the correct migration ID obtained from the previous step in the command below:
https://developer.hashicorp.com/vault/api-docs/system/remount#monitor-migration-status
$ vault read sys/remount/status/92a710d6-bd87-7f79-9af8-586bfb8cc020 -format=json | jq
The output will show the migration status and other relevant details.
Step 9: Verify the Secret Migration
Finally, let's verify that the secrets have been moved to the new path.
$ vault kv list kv/vault/zaid/hashicorp
Keys
----
1-secret
2-secret
3-secret
4-secret
5-secret
This command will list all the keys (secrets) present under the new path "kv/vault/zaid/hashicorp/".