Introduction
Vault 1.10 supports the renaming of Secrets and Authentication (aka Auth) mounts as well as the ability to move them between namespaces. The process of moving a mount is commonly referred to as a Mount Migration or a Remount.
Use Case
There may be a need for mount migration - including for example:
- Renaming to align with revised Organisational Standards
- Restructuring of Roles and Responsibilities resulting in a move.
- Shifting existing mounts across several namespaces, especially when transitioning to Vault Enterprise from Vault OSS.
Required permission to perform the operation via API or CLI
- This operation requires a policy with both
sudo
andupdate
capabilities tosys/remount
.
Impact & things need to be consideration
Below are some important factors to consider prior to performing a remount - that will result in:
- Revocation of existing leases on Secrets or Auth mounts.
- Revocation of all Auth tokens associated with mount being adjusted.
- Lengthy durations are needed in order to complete revocations in the case of larger mounts.
- Preservation of most configurations associated with a mount - but excluding for example sentinel policies and any rate-limiting or resource-quotas associated to that mount path.
- Cross namespace adjustments retain former aliases that are then considered invalid after a move.
- Need to remove aliases from the source namespace and those invalid after the move.
- Need to re-create equivalent aliases and entities for the new mount in the target namespace.
- Entities and aliases are dynamically re-generated upon subsequent login for any that weren't re-created in the target namespace.
- Policies path references becoming invalid due to the move and requiring a Vault administrator to update them.
- Path filters are being respected as per the deny-list that's specific to each cluster; thus an associated deny-list may prevent that mounts availability on the associated cluster.
Steps to migrate the secret and auth methods
Using the API:
- Create a
@payload.json
for the mount being moved - as per these examples:
Same Namespace Cross Namespace Secret Mount Cross Namespace Auth Mount {
"from": "secret",
"to": "new-secret"
}{
"from": "ns1/ns2/secret",
"to": "ns1/ns3/new-secret"
}{
"from":"ns1/ns2/auth/userpass",
"to": "ns1/ns3/auth/userpass_1"
} - Use your payload with the Vault API &
curl
that will respond with a migration id for checking its status as it's being asynchronously performedcurl -L -X POST -H "X-Vault-Token: ${VAULT_TOKEN}" -d @payload.json ${VAULT_ADDR}/v1/sys/remount
# ...
# f3abdd15-57e8-08d2-efb7-3600fa937
# // ^^ UID provided in response. - The UID from the above request may then be used to monitor the status of migration - like:
VMID=f3abdd15-57e8-08d2-efb7-3600fa937
curl -L -H "X-Vault-Token: ${VAULT_TOKEN}" ${VAULT_ADDR}/v1/sys/remount/status/${VMID}
Using the CLI:
- Unlike the API approach no
@payload.json
is needed and instead, the completed paths of secret & auth including the namespace must be annotated.
Mount Type Same Namespace Secret vault secrets move secret new-secret
Auth vault auth move auth/userpass auth/new-userpass
Cross Namespace Secret vault secrets move ns1/ns2/secret ns1/ns3/new-secret
Auth vault auth move ns1/ns2/auth/userpass ns1/ns3/auth/userpass_1
Note: Accessor ID & the UUID of mounts will remain the same and unaltered after a remount.