pv-migrate

pv-migrate is a CLI tool and kubectl plugin that moves the data of Kubernetes PersistentVolumeClaims. It copies directly from one PVC to another, in the same namespace, across namespaces or across clusters. It can also back up a PVC to bucket storage (S3-compatible, Azure Blob, GCS or any rclone remote) and restore it later.

---

Warning

Heads up: this is a side project I maintain in my spare time. I might take a long time to look at issues or PRs, or not get to them at all. Sorry in advance, and thanks for understanding.

---

Demo

Copying a claim into another one:

When a migration fails, the output explains why:

• the exit code the data mover returned, with the meaning that mover's own documentation attaches to it,
• the last lines of the failed pod's log,
• what the cluster reported about the resources involved.

Why this exists

On Kubernetes, renaming a resource like a Deployment is a manifest change. You create the same object with a new name or namespace, apply it, and move on.

PVCs are different. The Kubernetes object is only the metadata. The data lives in the storage backend, and there is no built-in way to move it.

pv-migrate moves that data. It runs a proven data mover (rsync or rclone) inside the cluster, so nothing is copied through your machine unless you ask for it.

Quick start

pv-migrate --source old-pvc --dest new-pvc

This copies the contents of old-pvc into new-pvc in the current namespace, trying the cheapest strategy first. See Installation for how to get the binary, and Usage for everything else.

Workflows

PVC-to-PVC migration

Copies data directly from one PVC to another with rsync, usually over SSH. This is the original workflow.

pv-migrate --source old-pvc --dest new-pvc

See PVC-to-PVC migration for the strategies and more examples.

Bucket backup and restore

Backs up a PVC to object storage with rclone and restores it later. Use it for backups, one-off exports, or moves where direct connectivity between the clusters is not available.

pv-migrate backup \
  --source app-data \
  --backend s3 \
  --bucket pv-backups \
  --name app-data-2026-04-11

pv-migrate restore \
  --dest app-data-restore \
  --backend s3 \
  --bucket pv-backups \
  --name app-data-2026-04-11

See Bucket backup and restore for the backends, the object layout, raw rclone config mode and the permission caveats.

Use cases

• A database has a 50Gi PVC and needs more space, but the storage class does not support volume expansion. Create a bigger PVC and copy the data over.
• A PVC has to move from namespace ns-a to namespace ns-b. Create the PVC with the same manifest in ns-b and copy its content.
• A workload moves from one cloud provider to another, and the data has to follow it to the new cluster. pv-migrate copies it over the internet, encrypted with SSH.
• A volume needs another StorageClass, e.g., from a ReadWriteOnce one like local-path to a ReadWriteMany one like NFS. The storage class is not editable, so create the new PVC and copy.
• A PVC needs a backup in object storage before a risky operation, or its data has to leave the cluster for a later restore. pv-migrate backup writes it to a bucket, pv-migrate restore brings it back.
• Scheduled PVC backups with Kubernetes building blocks only. Run pv-migrate backup from a CronJob, and handle retention with bucket lifecycle rules.
• Direct cluster-to-cluster connectivity is not available or only temporary. Back up the source PVC to a bucket, then restore from that bucket into the destination cluster.

Highlights

• In-namespace, in-cluster and cross-cluster migrations
• rsync over SSH with a freshly generated Ed25519 or RSA key pair for every run
• Backup to and restore from S3-compatible storage, Azure Blob, GCS, or any custom rclone remote
• Several migration strategies, tried in order, with fallback:
  • mount both PVCs in a single pod (mount)
  • ClusterIP service (clusterip)
  • LoadBalancer service (loadbalancer)
  • NodePort service (nodeport, opt-in)
  • port-forward through the local machine (local, opt-in)
• Customizable strategy order
• Push mode (--rsync-push) for when the source side cannot expose a service, e.g., behind a firewall or NAT
• Detach mode (--detach) for large transfers, so the job keeps running after the CLI exits
• Overrides for the generated manifests through Helm values: images, affinity, resources and everything else the chart exposes
• amd64, arm64 and arm32v7 (Raspberry Pi and similar) binaries and images
• Shell completion for bash, zsh, fish and PowerShell

Installation

See docs/install.md for the install options (Homebrew, krew, Scoop, release archives, Docker) and shell completion. The shortest one:

brew install utkuozdemir/pv-migrate/pv-migrate

The artifacts live here:

• GitHub releases: archives and checksums for Linux, macOS and Windows
• Docker Hub and GHCR: the CLI image, next to the three data mover images (pv-migrate-rsync, pv-migrate-sshd, pv-migrate-rclone)
• krew index, the Homebrew tap and the Scoop bucket

Releases are signed, and the install guide has the verification commands.

Usage

See docs/usage.md for the usage guides and the command reference:

• PVC-to-PVC migration
• Bucket backup and restore
• CLI reference

Star history

Contributing

See CONTRIBUTING.md for the process, .github/SECURITY.md for reporting a security problem, and .github/GOVERNANCE.md for how the project is run. The security model says what the tool promises and where the trust boundaries are, and the roadmap says what is planned and what is deliberately not.

AGENTS.md is the project guide for humans and AI assistants working in this repository: how the pieces fit together, and which invariants are easy to break by accident.