Metadata-Version: 2.4
Name: vault_migrate
Version: 0.1.9
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]
Requires-Dist: pretty-pie-log
Dynamic: license-file

# 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](https://pipx.pypa.io/) installs the tool in an isolated environment while making it globally available:

```bash
pipx install vault_migrate
```

### Using uv

[uv](https://github.com/astral-sh/uv) is a fast Python package installer:

```bash
# Install globally
uv tool install vault_migrate
```

### Manual Installation

For development or manual installation:

```bash
# 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`).

```bash
vault-migrate migrate.json
```

Or with a custom path:

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

## Configuration

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

```json
{
  "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:

```json
{
  "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.
