Vault Migrate

A Python tool for migrating secrets between HashiCorp Vault instances, supporting KV (Key-Value) secrets engines with namespace and mount point mapping.

Features

• Migrate secrets between different Vault instances
• Support for Vault namespaces
• Flexible mount point and path prefix mapping
• Configurable TLS verification and custom CA bundles
• JSON-based configuration for reproducible migrations

Installation

Using pipx (Recommended)

pipx installs the tool in an isolated environment while making it globally available:

pipx install vault_migrate

Using uv

uv is a fast Python package installer:

# Install globally
uv tool install vault_migrate

Manual Installation

For development or manual installation:

# Clone the repository
git clone https://github.com/TheLonelyGhost/vault-migrate.git
cd vault-migrate

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Usage

The vault-migrate command takes a single positional argument: the path to your migration configuration file (typically named migrate.json).

vault-migrate migrate.json

Or with a custom path:

vault-migrate /path/to/my-migration-config.json

Configuration

Create a migrate.json file with your migration configuration. Here's a complete example:

{
  "settings": {
    "source": {
      "address": "https://vault-source.example.com:8200",
      "token": "hvs.source-token-here",
      "tls_verify": true,
      "ca_bundle_path": "/path/to/source-ca-bundle.pem"
    },
    "target": {
      "address": "https://vault-target.example.com:8200",
      "token": "hvs.target-token-here",
      "tls_verify": true,
      "ca_bundle_path": "/path/to/target-ca-bundle.pem"
    },
    "mapping_file": "out/mapping.json",
    "timeout": 10
  },
  "kv": [
    {
      "from": {
        "namespace": "source-namespace",
        "mount": "secret",
        "path_prefix": "app/production"
      },
      "to": {
        "namespace": "target-namespace",
        "mount": "kv",
        "path_prefix": "applications/prod"
      }
    },
    {
      "from": {
        "namespace": "source-namespace",
        "mount": "secret",
        "path_prefix": "shared/credentials"
      },
      "to": {
        "namespace": "target-namespace",
        "mount": "kv",
        "path_prefix": "shared/creds"
      }
    }
  ]
}

Configuration Schema

settings (required)

Global settings for the migration:

• source (required): Source Vault connection configuration

  • address (string, required): Vault server URL
  • token (string, required): Vault authorization token
  • tls_verify (boolean, optional): Enable TLS verification (default: true)
  • ca_bundle_path (string, optional): Path to custom CA certificate bundle

• target (required): Target Vault connection configuration

  • Same fields as source

• mapping_file (string, optional): Path to output mapping file (default: "out/mapping.json")

• timeout (integer, optional): Request timeout in seconds (default: 10)

kv (optional)

Array of KV secrets engine mappings. Each mapping defines how secrets should be migrated from source to target:

• from (required): Source location

  • namespace (string, required): Source Vault namespace
  • mount (string, required): Source KV mount point
  • path_prefix (string, required): Source path prefix within the mount

• to (required): Target location

  • namespace (string, required): Target Vault namespace
  • mount (string, required): Target KV mount point
  • path_prefix (string, required): Target path prefix within the mount

Minimal Configuration Example

For a simple migration without namespaces or custom paths:

{
  "settings": {
    "source": {
      "address": "https://vault-old.example.com:8200",
      "token": "hvs.source-token"
    },
    "target": {
      "address": "https://vault-new.example.com:8200",
      "token": "hvs.target-token"
    }
  },
  "kv": [
    {
      "from": {
        "namespace": "",
        "mount": "secret",
        "path_prefix": ""
      },
      "to": {
        "namespace": "",
        "mount": "secret",
        "path_prefix": ""
      }
    }
  ]
}

Requirements

• Python 3.10 or higher
• Network access to both source and target Vault instances
• Valid Vault tokens with appropriate permissions for reading and writing secrets

License

See LICENSE file for details.