Vaultx.Sys.Remount (Vaultx v0.7.0)

HashiCorp Vault mount migration and remount operations.

This module provides comprehensive mount migration capabilities for Vault, allowing you to move mounted backends (both secrets engines and auth methods) to new mount points with full migration tracking and status monitoring.

Mount Migration Features

Core Operations

Move Backend: Relocate mounted backends to new paths
Migration Tracking: Monitor migration progress with unique IDs
Status Monitoring: Real-time migration status updates
Cross-Namespace Support: Move mounts across Vault namespaces

Migration Types

Secrets Engine Migration: Move KV, database, and other secrets engines
Auth Method Migration: Relocate authentication backends
Cross-Namespace Migration: Move mounts between different namespaces
Within-Namespace Migration: Rename mounts within the same namespace

Enterprise Features

Namespace Support: Full multi-tenant migration capabilities
Migration Auditing: Complete audit trail of mount movements
Rollback Support: Migration status tracking for recovery operations

Important Notes

Security Requirements

Requires both sudo and update capabilities to sys/remount
Mount migration revokes ALL leases for secrets engines
Mount migration revokes ALL tokens for auth methods

Impact Considerations

All existing leases/tokens are revoked during migration
Applications must be updated to use new mount paths
Migration is irreversible once completed

API Compliance

Fully implements HashiCorp Vault Remount API:

Usage Examples

Basic Mount Migration

# Move a secrets engine
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move("secret", "new-secret")

# Monitor migration progress
{:ok, status} = Vaultx.Sys.Remount.status(id)
status.migration_info.status #=> "in-progress" | "success" | "failure"

Cross-Namespace Migration

# Move mount between namespaces
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move(
  "ns1/ns2/secret",
  "ns1/ns3/new-secret"
)

Auth Method Migration

# Move auth method
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move(
  "auth/approle",
  "auth/new-approle"
)

Migration Status Monitoring

# Check migration status
{:ok, status} = Vaultx.Sys.Remount.status("ef3ba21c-8be8-4e5f-8d00-cb46a532c665")

case status.migration_info.status do
  "success" -> IO.puts("Migration completed successfully")
  "in-progress" -> IO.puts("Migration still running...")
  "failure" -> IO.puts("Migration failed")
end

Migration Workflow

Initiate Migration: Call move/3 with source and target paths
Receive Migration ID: Vault returns a unique migration identifier
Monitor Progress: Use status/2 to track migration progress
Handle Completion: Process success/failure based on final status
Update Applications: Modify client configurations for new paths

Summary

Types

migration_info()

Migration information structure.

migration_response()

Migration initiation response.

migration_status()

Migration status response.

Functions

move(from_path, to_path, opts \\ [])

Move a mounted backend to a new mount point.

status(migration_id, opts \\ [])

Monitor the status of a mount migration operation.

Types

migration_info()

@type migration_info() :: %{
  source_mount: String.t(),
  target_mount: String.t(),
  status: String.t()
}

Migration information structure.

migration_response()

@type migration_response() :: %{migration_id: String.t()}

Migration initiation response.

migration_status()

@type migration_status() :: %{
  migration_id: String.t(),
  migration_info: migration_info()
}

Migration status response.

Functions

move(from_path, to_path, opts \\ [])

@spec move(String.t(), String.t(), Vaultx.Types.options()) ::
  {:ok, migration_response()} | {:error, Vaultx.Base.Error.t()}

Move a mounted backend to a new mount point.

This operation moves an already-mounted backend (secrets engine or auth method) to a new mount point. The operation works for both secrets engines and auth methods, and supports cross-namespace migrations in Vault Enterprise.

Parameters

from_path - The current mount path to move from
to_path - The new destination mount path
opts - Request options (optional)

Returns

Returns {:ok, migration_response()} with a migration ID on success, or {:error, Error.t()} on failure.

Examples

# Move secrets engine within namespace
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move("secret", "new-secret")

# Move auth method
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move(
  "auth/approle",
  "auth/new-approle"
)

# Cross-namespace migration (Enterprise)
{:ok, %{migration_id: id}} = Vaultx.Sys.Remount.move(
  "ns1/ns2/secret",
  "ns1/ns3/new-secret"
)

Important Notes

All existing leases (for secrets engines) or tokens (for auth methods) are revoked
The operation requires both sudo and update capabilities
Migration is tracked via the returned migration ID
Use status/2 to monitor migration progress

status(migration_id, opts \\ [])

@spec status(String.t(), Vaultx.Types.options()) ::
  {:ok, migration_status()} | {:error, Vaultx.Base.Error.t()}

Monitor the status of a mount migration operation.

This endpoint monitors the status of a mount migration using the migration ID returned from the move/3 operation. The response contains the migration ID, source and target mounts, and a status field indicating the current state.

Parameters

migration_id - The unique migration identifier from move/3
opts - Request options (optional)

Returns

Returns {:ok, migration_status()} with detailed migration information, or {:error, Error.t()} on failure.

Status Values

"in-progress" - Migration is currently running
"success" - Migration completed successfully
"failure" - Migration failed

Examples

# Check migration status
{:ok, status} = Vaultx.Sys.Remount.status("ef3ba21c-8be8-4e5f-8d00-cb46a532c665")

status.migration_id #=> "ef3ba21c-8be8-4e5f-8d00-cb46a532c665"
status.migration_info.source_mount #=> "secret"
status.migration_info.target_mount #=> "new-secret"
status.migration_info.status #=> "success"

# Handle different status values
case status.migration_info.status do
  "success" ->
    IO.puts("Migration completed successfully")
  "in-progress" ->
    IO.puts("Migration still running, check again later")
  "failure" ->
    IO.puts("Migration failed, check Vault logs")
end