# anticipatedd/pv-migrate architecture

> Architecture diagram of the GitHub repository anticipatedd/pv-migrate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anticipatedd/pv-migrate
- Repository: https://github.com/anticipatedd/pv-migrate

## Overview

pv-migrate is a CLI and kubectl plugin for moving Kubernetes PVC data, plus backing up PVCs to and restoring them from rclone-supported object storage. The main migration flow accepts source and destination claims, resolves their cluster and PVC details, then tries configured transfer strategies; bucket workflows run an rclone job against a mounted claim. The README documents additional strategy, push, detach, and backend capabilities. Some subsystem wiring is inferred from documented behavior and package boundaries because the excerpts are partial.

Main entry points: [`internal/strategy/strategy.go`](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/strategy.go) (Strategy selection), [`internal/bucketstorage/bucketstorage.go`](https://github.com/anticipatedd/pv-migrate/blob/main/internal/bucketstorage/bucketstorage.go) (Bucket job setup), [`internal/rsync/cmd.go`](https://github.com/anticipatedd/pv-migrate/blob/main/internal/rsync/cmd.go) (rsync over SSH), [`internal/migrator/migrator.go`](https://github.com/anticipatedd/pv-migrate/blob/main/internal/migrator/migrator.go) (Strategy orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["CLI entry<br/>[main.go]"]
  node_commands["Command handlers"]
end

subgraph group_migration["PVC migration"]
  node_migration_api["Migration API<br/>[pvmigrate.go]"]
  node_migrator["Strategy orchestrator<br/>[migrator.go]"]
  node_pvc_info["PVC inspection<br/>[info.go]"]
end

subgraph group_transfer["Transfer strategies"]
  node_strategies["Strategy selection<br/>[strategy.go]"]
  node_mount_strategy["Shared mount<br/>[mount.go]"]
  node_clusterip_strategy["ClusterIP<br/>[clusterip.go]"]
  node_loadbalancer_strategy["Load balancer<br/>[loadbalancer.go]"]
  node_nodeport_strategy["NodePort<br/>[nodeport.go]"]
  node_local_strategy["Local tunnel<br/>[local.go]"]
  node_rsync["rsync over SSH<br/>[cmd.go]"]
end

subgraph group_backup["Bucket workflows"]
  node_backup_api["Backup API<br/>[backup.go]"]
  node_restore_api["Restore API<br/>[restore.go]"]
  node_bucket_job["Bucket job setup<br/>[bucketstorage.go]"]
  node_rclone["rclone runner<br/>[cmd.go]"]
end

subgraph group_ops["Cluster operations"]
  node_k8s_client["Kubernetes client<br/>[client.go]"]
  node_helm["Helm integration<br/>[helm.go]"]
  node_progress["Progress and logs<br/>[handler.go]"]
end

node_operator(("Operator"))
node_bucket["Object storage"]
node_cluster["Kubernetes cluster"]

node_operator -->|"runs"| node_cli
node_cli -->|"builds commands"| node_commands
node_commands -->|"runs migration"| node_migration_api
node_commands -->|"runs backup"| node_backup_api
node_commands -->|"runs restore"| node_restore_api
node_migration_api -->|"starts migration"| node_migrator
node_migrator -->|"gets clients"| node_k8s_client
node_migrator -->|"inspects claims"| node_pvc_info
node_migrator -->|"selects strategies"| node_strategies
node_strategies -->|"dispatches"| node_mount_strategy
node_strategies -->|"dispatches"| node_clusterip_strategy
node_strategies -->|"dispatches"| node_loadbalancer_strategy
node_strategies -->|"dispatches"| node_nodeport_strategy
node_strategies -->|"dispatches"| node_local_strategy
node_mount_strategy -->|"runs transfer"| node_rsync
node_clusterip_strategy -->|"runs transfer"| node_rsync
node_loadbalancer_strategy -->|"runs transfer"| node_rsync
node_nodeport_strategy -->|"runs transfer"| node_rsync
node_local_strategy -->|"runs transfer"| node_rsync
node_rsync -->|"copies PVC data"| node_cluster
node_backup_api -->|"starts backup"| node_bucket_job
node_restore_api -->|"starts restore"| node_bucket_job
node_bucket_job -->|"gets client"| node_k8s_client
node_bucket_job -->|"installs job"| node_helm
node_bucket_job -->|"configures mover"| node_rclone
node_rclone -->|"reads or writes"| node_bucket
node_k8s_client -->|"accesses resources"| node_cluster
node_migrator -->|"reports progress"| node_progress
node_bucket_job -->|"reports progress"| node_progress

click node_cli "https://github.com/anticipatedd/pv-migrate/blob/main/cmd/pv-migrate/main.go"
click node_commands "https://github.com/anticipatedd/pv-migrate/tree/main/internal/app"
click node_migration_api "https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/pvmigrate.go"
click node_migrator "https://github.com/anticipatedd/pv-migrate/blob/main/internal/migrator/migrator.go"
click node_pvc_info "https://github.com/anticipatedd/pv-migrate/blob/main/internal/pvc/info.go"
click node_strategies "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/strategy.go"
click node_mount_strategy "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/mount.go"
click node_clusterip_strategy "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/clusterip.go"
click node_loadbalancer_strategy "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/loadbalancer.go"
click node_nodeport_strategy "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/nodeport.go"
click node_local_strategy "https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/local.go"
click node_rsync "https://github.com/anticipatedd/pv-migrate/blob/main/internal/rsync/cmd.go"
click node_backup_api "https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/backup.go"
click node_restore_api "https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/restore.go"
click node_bucket_job "https://github.com/anticipatedd/pv-migrate/blob/main/internal/bucketstorage/bucketstorage.go"
click node_rclone "https://github.com/anticipatedd/pv-migrate/blob/main/internal/rclone/cmd.go"
click node_k8s_client "https://github.com/anticipatedd/pv-migrate/blob/main/internal/k8s/client.go"
click node_helm "https://github.com/anticipatedd/pv-migrate/blob/main/internal/helm/helm.go"
click node_progress "https://github.com/anticipatedd/pv-migrate/blob/main/internal/narrate/handler.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands toneBlue
class node_migration_api,node_migrator,node_pvc_info,node_bucket toneAmber
class node_strategies,node_mount_strategy,node_clusterip_strategy,node_loadbalancer_strategy,node_nodeport_strategy,node_local_strategy,node_rsync toneMint
class node_backup_api,node_restore_api,node_bucket_job,node_rclone toneRose
class node_k8s_client,node_helm,node_progress,node_operator,node_cluster toneIndigo
```

## Components

### CLI workflows

- [CLI entry](https://github.com/anticipatedd/pv-migrate/blob/main/cmd/pv-migrate/main.go): `cmd/pv-migrate/main.go`
- [Command handlers](https://github.com/anticipatedd/pv-migrate/tree/main/internal/app): `internal/app`

### PVC migration

- [Migration API](https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/pvmigrate.go): `pvmigrate/pvmigrate.go`
- [Strategy orchestrator](https://github.com/anticipatedd/pv-migrate/blob/main/internal/migrator/migrator.go): `internal/migrator/migrator.go`
- [PVC inspection](https://github.com/anticipatedd/pv-migrate/blob/main/internal/pvc/info.go): `internal/pvc/info.go`

### Transfer strategies

- [Strategy selection](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/strategy.go): `internal/strategy/strategy.go`
- [Shared mount](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/mount.go): `internal/strategy/mount.go`
- [ClusterIP](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/clusterip.go): `internal/strategy/clusterip.go`
- [Load balancer](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/loadbalancer.go): `internal/strategy/loadbalancer.go`
- [NodePort](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/nodeport.go): `internal/strategy/nodeport.go`
- [Local tunnel](https://github.com/anticipatedd/pv-migrate/blob/main/internal/strategy/local.go): `internal/strategy/local.go`
- [rsync over SSH](https://github.com/anticipatedd/pv-migrate/blob/main/internal/rsync/cmd.go): `internal/rsync/cmd.go`

### Bucket workflows

- [Backup API](https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/backup.go): `pvmigrate/backup.go`
- [Restore API](https://github.com/anticipatedd/pv-migrate/blob/main/pvmigrate/restore.go): `pvmigrate/restore.go`
- [Bucket job setup](https://github.com/anticipatedd/pv-migrate/blob/main/internal/bucketstorage/bucketstorage.go): `internal/bucketstorage/bucketstorage.go`
- [rclone runner](https://github.com/anticipatedd/pv-migrate/blob/main/internal/rclone/cmd.go): `internal/rclone/cmd.go`

### Cluster operations

- [Kubernetes client](https://github.com/anticipatedd/pv-migrate/blob/main/internal/k8s/client.go): `internal/k8s/client.go`
- [Helm integration](https://github.com/anticipatedd/pv-migrate/blob/main/internal/helm/helm.go): `internal/helm/helm.go`
- [Progress and logs](https://github.com/anticipatedd/pv-migrate/blob/main/internal/narrate/handler.go): `internal/narrate/handler.go`

### Other components

- **Operator**
- **Object storage**
- **Kubernetes cluster**

## Connections

- Operator → CLI entry: runs
- CLI entry → Command handlers: builds commands
- Command handlers → Migration API: runs migration
- Command handlers → Backup API: runs backup
- Command handlers → Restore API: runs restore
- Migration API → Strategy orchestrator: starts migration
- Strategy orchestrator → Kubernetes client: gets clients
- Strategy orchestrator → PVC inspection: inspects claims
- Strategy orchestrator → Strategy selection: selects strategies
- Strategy selection → Shared mount: dispatches
- Strategy selection → ClusterIP: dispatches
- Strategy selection → Load balancer: dispatches
- Strategy selection → NodePort: dispatches
- Strategy selection → Local tunnel: dispatches
- Shared mount → rsync over SSH: runs transfer
- ClusterIP → rsync over SSH: runs transfer
- Load balancer → rsync over SSH: runs transfer
- NodePort → rsync over SSH: runs transfer
- Local tunnel → rsync over SSH: runs transfer
- rsync over SSH → Kubernetes cluster: copies PVC data
- Backup API → Bucket job setup: starts backup
- Restore API → Bucket job setup: starts restore
- Bucket job setup → Kubernetes client: gets client
- Bucket job setup → Helm integration: installs job
- Bucket job setup → rclone runner: configures mover
- rclone runner → Object storage: reads or writes
- Kubernetes client → Kubernetes cluster: accesses resources
- Strategy orchestrator → Progress and logs: reports progress
- Bucket job setup → Progress and logs: reports progress