Migrate MinIO Data Safely with mc mirror

Moving MinIO is more than copying the latest object files. A reliable migration must account for versions, delete markers, metadata, lifecycle rules, access policies, encryption, and writes that occur during the copy. The safest pattern is a full synchronization followed by incremental catch-up and a controlled cutover.

1. Configure source and destination aliases

Install a recent MinIO Client release and configure both endpoints:

mc alias set old https://old-minio.example.com ACCESS_KEY SECRET_KEY
mc alias set new https://new-minio.example.com ACCESS_KEY SECRET_KEY
mc admin info old
mc admin info new

Avoid placing real secrets in shell history. Prefer environment variables, a restricted configuration file, or a secrets manager.

2. Inventory the source

Before copying data, record the bucket list and important settings:

mc ls old
mc admin info old
mc ilm rule ls old/my-bucket
mc version info old/my-bucket

Also inventory users, groups, policies, bucket notifications, object-lock settings, replication rules, and server-side encryption keys. mc mirror focuses on objects; it does not automatically reproduce every administrative setting.

3. Run the initial mirror

Create the destination bucket if needed and start the full copy:

mc mb --ignore-existing new/my-bucket
mc mirror --preserve --overwrite old/my-bucket new/my-bucket

Use --remove only when the destination must be an exact mirror and you are certain that destination-only objects may be deleted. Test that behavior on a disposable bucket first.

For a long migration, run the command in a managed terminal session and save logs:

mc mirror --preserve --overwrite --json old/my-bucket new/my-bucket

4. Catch up new writes

While applications still write to the old cluster, repeat the mirror to transfer changes. Shortly before cutover:

1. Put writers into maintenance or read-only mode.
2. Run one final incremental mirror.
3. Compare source and destination.
4. Switch application endpoints and credentials.
5. Keep the old service read-only until validation is complete.

This sequence minimizes downtime without losing objects written during the first copy.

5. Validate the result

Compare object counts and total sizes, but do not treat matching totals as sufficient proof. Sample critical objects and verify metadata, content type, ETag or checksums, application reads, presigned URLs, and permissions.

mc du --recursive old/my-bucket
mc du --recursive new/my-bucket
mc stat old/my-bucket/path/to/object
mc stat new/my-bucket/path/to/object

Multipart uploads and encrypted objects can make ETags unsuitable as universal content hashes. Use application-level checksums when correctness is critical.

Versioning and deletion caveats

Confirm how the client version you use handles object versions and delete markers. If legal retention, object lock, or historical versions matter, test the complete behavior with representative data before migrating production. For very large or continuously changing datasets, MinIO replication may be a better fit than repeated mirroring.

Rollback plan

Do not delete the source immediately. Define a rollback window, preserve DNS or endpoint settings, and document how writes will be reconciled if traffic must return to the old cluster. A successful migration ends only after monitoring confirms normal error rates, latency, permissions, and object integrity.