Secrets Engine and Authentication Mount Migration – HashiCorp Help Center

Introduction

Vault 1.10+ supports the moving or renaming of secrets and authentication mounts. This also allows the ability to move the mounts from one namespace to another. This article will explain this process further, along with things to consider the impact of this operation.

Use Case

Possible reasons to move/rename a mount:

Renaming to align with revised organizational standards
Restructuring of roles and responsibilities resulting in a move
Moving existing mounts to a namespace, especially when transitioning to Vault Enterprise from Vault OSS

Prerequisite

This operation requires a policy with both sudo and update capabilities to sys/remount

Impact

There are some important factors to consider prior to performing a mount move:

Revocation of existing leases or tokens associated to the mount.
- This can cause the operation to take some time while leases are being revoked.
Configuration associated with the mount will stay intact, but this excludes associated sentinel policies and rate-limiting or resource-quotas which are associated based on the path.
When moving from one namespace to another, aliases from the source namespace will become invalid. Must recreate aliases and entities for the new mount in the target namespace.
Entities and aliases are dynamically regenerated upon subsequent login for any that weren't recreated in the target namespace.
Note: Accessor ID and UUID of mounts will remain the same after a remount.
Policies associated to the paths being altered will also need to be changed.
Path filters being used with replication can be effected based on possible deny-lists.

Procedure

API

1. Sample payloads:

Within Namespace

{
  "from": "secret",
  "to": "new-secret"
}

Secrets Engine (cross Namespace)

{
  "from": "ns1/ns2/secret",
  "to": "ns1/ns3/new-secret"
}

Auth Mount (cross Namespace)

{
  "from":"ns1/ns2/auth/userpass",
  "to": "ns1/ns3/auth/new-userpass"
}

2. Sample request, using the sys/remount API endpoint:

curl -L -X POST -H "X-Vault-Token: ${VAULT_TOKEN}" -d @payload.json ${VAULT_ADDR}/v1/sys/remount

3. Sample response:

{
  "migration_id": "f3abdd15-57e8-08d2-efb7-3600fa937"
}

4. Monitoring migration status using the sys/remount/status API endpoint along with the migration_id:

curl -L -H "X-Vault-Token: ${VAULT_TOKEN}" ${VAULT_ADDR}/v1/sys/remount/status/:migration_id

CLI

1. Sample commands:

Auth Mount (within Namespace)

vault auth move auth/userpass auth/new-userpass

Secrets Engine (within Namespace)

vault secrets move secret new-secret