How to migrate from Amazon S3 to Garage

Find the S3 features each bucket relies on, size the copy, copy with rclone, repoint each application to Garage, then verify checksums before deleting from S3.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • Applications keep their S3 SDKs: each one gets a Garage endpoint, the region name set in Garage, path-style addressing unless wildcard DNS is set up, and a new key limited to its own buckets.
  • Garage has no versioning, object lock, bucket policies, ACLs, storage classes, tagging or event notifications, and its lifecycle rules cover only expiry and abandoned multipart uploads.
  • rclone copies the objects while applications still write to S3, then a second pass takes what changed once writes stop, before each application is repointed.
  • S3 objects are deleted only after rclone check matches every bucket, with objects whose ETag is not an MD5 compared by downloading both copies.
On this page (10)

Moving from Amazon S3 to Garage is a copy and a re-pointing. Garage speaks the S3 API, so applications keep their SDKs and get a new endpoint, a region name and a new pair of keys, while rclone copies the objects across. What does not come across is what Amazon keeps beside the objects: versions, object lock, bucket policies, ACLs, storage classes, most lifecycle rules and event notifications. The work is finding which of those each application quietly relies on, copying without losing a write, and checking counts and checksums before anything is deleted from S3. This guide covers the order we do it in.

Why teams move from Amazon S3 to Garage

Three reasons come up again and again.

  • The data stays where you put it. Garage runs on your hardware or in regions you choose, and with three zones in its layout every object has a copy in each. The bucket is often where most of an organisation’s data ends up, which makes it the place where residency is decided.
  • No bill per request or per byte read. S3 bills storage, requests and data transfer out. Garage costs the machines it runs on and its operation, so reading your own data back costs nothing extra.
  • A system small enough to run. Garage is a single binary with no external database or coordination service, AGPL-3.0, with no paid edition.

What you give up is real. Garage implements a narrower S3 API: no versioning, object lock, bucket policies, ACLs, storage classes, tagging, replication or event notifications, and no conditional writes. AWS services that read S3 directly, from Lambda triggers to Athena, stay with AWS. And someone has to run the cluster, which is the part Pilae takes on.

Step 1: list what each bucket relies on

Read every bucket’s configuration from AWS before anything moves. An error saying a configuration does not exist, or an empty answer, means the feature is off for that bucket.

for b in $(aws s3api list-buckets --query 'Buckets[].Name' --output text); do
  for cmd in get-bucket-versioning get-object-lock-configuration get-bucket-replication \
             get-bucket-lifecycle-configuration get-bucket-policy get-bucket-acl \
             get-bucket-notification-configuration get-bucket-encryption get-bucket-tagging \
             get-bucket-website get-bucket-cors; do
    echo "== $b $cmd"; aws s3api "$cmd" --bucket "$b" 2>&1
  done
done > s3-config.txt

Then set each answer against Garage’s S3 compatibility list:

S3 feature In Garage
Versioning None: only the current version of each object moves
Object lock None: the bucket stays on a store that has it
Replication None: copies live in Garage’s zones
Lifecycle rules Expiration and abort of incomplete multipart uploads only
Bucket policy and ACLs None: read, write or owner rights per key and bucket
Event notifications None: rebuilt in step 5
SSE-S3 and SSE-KMS None: SSE-C works; Garage leaves the rest to disk or client encryption
Bucket and object tags None
Website hosting, CORS Supported, except a website’s RedirectAllRequestsTo
Multipart, presigned Supported
Storage classes None: lifecycle transitions between classes are dropped

Configuration is half the answer; the calls each application makes are the other. Turn on server access logging for a few weeks: each record names the requester and the operation, which shows which applications use which bucket and whether any of them calls something Garage lacks, such as object tagging or reads of a specific version. Name the buckets that stay on AWS, with the reason, before anything moves.

Step 2: size the copy and its cost

Set up an S3 Inventory report on every bucket that moves. It lists every object, daily or weekly, as CSV, ORC or Parquet, in a destination bucket in the same Region, and Athena can query it. AWS says the first report can take up to 48 hours, so set it up first. Include these fields:

  • Size. The total bytes and object count per bucket give the copy budget, and the figures step 7 must match.
  • Storage class and Intelligent-Tiering access tier. Objects in Glacier Flexible Retrieval or Glacier Deep Archive, and in the archive tiers of Intelligent-Tiering, cannot be read until they are restored, which for the Glacier classes has its own charge. rclone backend restore restores them by prefix.
  • Multipart upload flag and encryption status. An object uploaded in parts, or encrypted with a KMS key or a customer-provided key (SSE-C), has an ETag that is not an MD5 of its content, which decides how step 7 checks it.

The inventory also tells you whether Garage’s known issues apply: the project reports slower metadata on buckets that hold very many objects, and on very large objects. Both shape the layout and the bucket split before anything is copied.

Then the cost of leaving. AWS bills data transfer out of S3 to the internet, and every GET and LIST request the copy and the checks make. AWS states that it gives credits for data transfer out to eligible customers who move all their data off AWS, or off one service, on request to AWS Support and within a set time. EU customers switching under the EU Data Act follow AWS’s EU Data Act Addendum instead. Ask before the copy starts.

Step 3: build the cluster, buckets and keys

Settle the layout before the first object arrives, then create the buckets and keys.

  1. The replication factor. Three, with one node in each of three zones, so every object has a copy per zone. Garage documents changing the factor later as a dangerous operation it does not officially support, which rebuilds the layout from scratch.
  2. The region name. Garage accepts S3 calls signed for the region set as s3_region in its configuration, garage in its examples, and refuses others with AuthorizationHeaderMalformed. Every client must use that name, and some clients fall back to us-east-1 when none is set, or hardcode it.
  3. Addressing. Path-style requests (host/bucket/key) always work. Virtual-host style (bucket.host/key) needs root_domain in the configuration, a wildcard DNS entry and possibly a wildcard TLS certificate, so set it up only for applications that cannot do path-style.
  4. One key per application. IAM policies become Garage permissions: read, write or owner, per key and per bucket. There are no prefix-level permissions, so an IAM policy limited to a prefix inside a bucket becomes a bucket of its own. Applications that took credentials from an IAM role get a static key pair, kept in your secrets store. A key can carry an expiry date, so a contractor’s key ends when the contract does.
# Once, from one node: one node per zone, then apply layout version 1 (a layout counter)
garage layout assign -z zone-a -c 16T <node-id-a>
garage layout assign -z zone-b -c 16T <node-id-b>
garage layout assign -z zone-c -c 16T <node-id-c>
garage layout apply --version 1

# Per bucket: the bucket, then a key for each application that uses it
garage bucket create acme-invoices
garage key create invoicing-app
garage bucket allow --read --write acme-invoices --key invoicing-app

# A key for the copy only, deleted in step 7
garage key create migration-copy --expires-in 30d
garage bucket allow --read --write acme-invoices --key migration-copy

Bucket settings Garage supports are applied through the S3 API with a key that has the owner flag, the only one allowed to change them: CORS rules with put-bucket-cors, and lifecycle rules with put-bucket-lifecycle-configuration, limited to expiration and the abort of incomplete multipart uploads, with any prefix inside Filter. A bucket that S3 served publicly, through a public-read ACL or a policy, is published through Garage’s website endpoint (garage bucket website --allow, which needs a global alias for the bucket) or through presigned links.

Step 4: copy with rclone while S3 stays live

rclone reads from S3 and writes to Garage in one stream, through the machine it runs on. Garage’s documentation gives the remote for it: rclone has no Garage provider, so it is set as Other, with the region and path-style addressing above.

# ~/.config/rclone/rclone.conf
[aws]
type = s3
provider = AWS
env_auth = true
region = eu-central-1

[garage]
type = s3
provider = Other
access_key_id = GK...
secret_access_key = ...
region = garage
# Garage's S3 endpoint, on the private network
endpoint = http://garage.acme.internal:3900
force_path_style = true
acl = private
bucket_acl = private

The AWS identity rclone runs as needs to list and read every bucket that moves, and to decrypt with the KMS keys of buckets encrypted with SSE-KMS. Restore archived objects first (step 2).

# First pass, while applications still write to S3
rclone copy aws:acme-invoices garage:acme-invoices --checksum --metadata --fast-list --progress
  • --checksum compares size and MD5 rather than modification time. rclone recommends it between two S3 stores because it needs no extra request per object. Where an object has no MD5, rclone falls back to comparing sizes only.
  • --metadata copies user metadata and headers such as Cache-Control and Content-Disposition. Without it, rclone keeps only the content type and the modification time.
  • --fast-list is what Garage’s documentation recommends for buckets with many objects: fewer listing calls, on both sides.
  • Chunk size. Garage’s known issues ask for multipart chunks that are an exact multiple of its block_size. If you change rclone’s --s3-chunk-size, keep to that.

Repeat the pass as needed: objects already in Garage are skipped. The same remote layout works from MinIO, with provider = Minio on the source; Garage’s documentation marks MinIO’s own mc client as abandoned upstream and recommends rclone or the AWS CLI instead.

Step 5: replace event notifications

S3 sends event notifications to SNS topics, SQS queues, Lambda functions and EventBridge. Garage implements none of the notification endpoints, so each configuration found in step 1 needs another mechanism before its application moves.

  • The writer announces it. The application that uploads the object publishes the event itself, to your queue or a webhook, once the upload succeeds. This is the closest equivalent, and the most reliable.
  • A scheduled listing. A job lists the bucket, or a prefix, on a schedule and processes the keys it has not seen before. An n8n workflow does this with a Schedule Trigger and its S3 node, which takes a custom endpoint and path-style addressing.

The code behind a Lambda function moves with the notification, to wherever the processing now runs.

Step 6: repoint each application, then freeze its bucket

Move one application at a time, starting with one whose failure would hurt nobody.

Moving one application to Garage

  1. Test: A staging copy of the application runs against Garage.
  2. Stop writes: The application stops writing to S3.
  3. Final pass: rclone takes what changed, and counts are compared.
  4. Repoint: The application gets Garage’s endpoint, region and key.
  5. Freeze: The S3 bucket is made read-only until its owner signs off.
  1. Test first. Run the application, or its test suite, against Garage with a copy of the data. A call Garage does not implement, such as object tagging or bucket versioning, returns 501 Not Implemented there, and not in production. Headers Garage does not act on raise no error, so search the code for them: conditional writes (If-None-Match), which Garage states it cannot support, tags sent with an upload, version IDs and server-side encryption headers other than SSE-C.
  2. The final pass. Once the application has stopped writing to S3, run rclone sync, first with --dry-run, because sync also deletes from Garage what was deleted from S3. For buckets with objects that have no MD5, run this pass without --checksum, so that rclone compares modification times too, at the cost of one HEAD request per object. Then compare rclone size on both sides: object count and total size must match.
  3. Repoint. Four settings change: the endpoint, the region (Garage’s s3_region), path-style addressing (forcePathStyle in the JavaScript SDK, addressing_style = path in boto3 and the AWS CLI), and the access key and secret. An application still running in AWS reaches Garage through the published endpoint, over TLS.
  4. Presigned links work with Garage, and the links an application signs for it carry Garage’s hostname, so that host must be reachable by whoever opens them. Links S3 has already issued keep pointing at S3 until they expire.
  5. Freeze the S3 bucket. Deny writes in its bucket policy and leave it readable, so going back is a configuration change rather than a copy.

Step 7: verify, then delete from S3

Delete nothing from S3 until every bucket has been checked object by object.

  1. Check every object. rclone check aws:acme-invoices garage:acme-invoices --combined report.txt compares sizes and MD5 hashes and writes a line per object: identical, missing on one side, or different.
  2. Check the objects without an MD5 by content. The multipart flag and encryption status in the inventory list them; rclone check --download --files-from <list> reads both copies and compares them byte for byte. On the S3 side that reading is billed as data transfer out, so keep it to those objects.
  3. Sign off. The bucket owner confirms the application works on Garage, and Garage’s own backups of the bucket have run.
  4. Delete. Empty the S3 bucket, older versions and delete markers included. AWS recommends keeping an emptied bucket rather than deleting it, because a deleted bucket’s name can be taken by another AWS account, which would then receive any request still sent to it. Then remove the IAM users and keys the applications used, the inventory configurations and the access logging, and delete the migration-copy key in Garage.

Running Garage in production

Replicas protect against a lost disk or a lost zone, not against a delete: a delete reaches all three copies, and there is no versioning to undo it.

  • Three zones of similar size. The smallest zone sets how much the cluster can hold. Garage spreads data most evenly over fewer, bigger nodes.
  • Metadata on SSD, with snapshots. Garage’s known issues report that its default LMDB metadata engine can be corrupted by an unclean shutdown, and recommend automatic metadata snapshots (metadata_auto_snapshot_interval) as the way back.
  • TLS in front. The S3 endpoint has no TLS of its own, so it stays on a private network, and anything published goes through a proxy that adds it.
  • Backups beyond the replicas, to another location, and upgrades taken one major release at a time.

Pilae operates Garage this way: one node per zone, placed on your premises, in Pilae Cloud regions you choose, or both, with the S3 traffic carried inside your private network and published through the gate only if you choose. Every application gets its own key on its own buckets. Buckets are backed up daily, encrypted, to an offsite location in the country your contract names, and on Enterprise a restore test every month is recorded in the console. The Pilae Agent rehearses each upgrade on a copy of the cluster and applies it in your window once you approve.

Let Pilae run the move

Pilae runs Amazon S3 to Garage migrations at a fixed price: the inventory of buckets and the features they rely on, the cluster and its keys, the copy and the final pass, the replacement of event notifications, the move of every application with its way back, and the checks before S3 is emptied. Then we operate Garage for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about the buckets you want to move and we will scope it.

Questions

Do our applications need code changes to use Garage?

Usually not. Garage speaks the S3 API, so an application keeps its SDK and gets a new endpoint, the region name set in Garage, path-style addressing and a new key. Code changes only where an application calls something Garage does not implement, such as versioning, object lock, tagging, bucket policies or event notifications. Garage answers those calls with 501 Not Implemented, which testing finds before production does. Conditional writes are the exception: Garage states it cannot support them and does not act on the If-None-Match header, so they raise no error and are found by reading the code.

Do object versions come across?

No. Garage has no versioning, so rclone copies the current version of each object. Older versions and delete markers stay in S3. If anything relies on them, keep that bucket on S3 or archive the versions elsewhere before the bucket is deleted.

What does leaving S3 cost?

AWS bills data transfer out of S3 to the internet, and every request the copy and the checks make. AWS states that it gives credits for that transfer to eligible customers moving all their data off AWS, or off one service, on request to AWS Support and within a set time; EU customers switching under the EU Data Act follow its EU Data Act Addendum. Ask before the copy starts. Objects in the Glacier archive classes also carry a charge to restore them.

Can Garage hold data that must be immutable?

No. Garage has no object lock, and the project states that a safe object lock cannot be built on its design, which has no consensus algorithm. A bucket that needs write-once storage stays on a store that has it. Backup tools that keep their own snapshots, such as restic, work with Garage as a target.

Is Garage open source?

Yes. Garage is AGPL-3.0 throughout, with no paid edition and no features held back for a commercial licence. It is developed by Deuxfleurs, a French non-profit association.

How long does an S3 to Garage migration take?

It depends on two things: how many applications use the buckets and which S3 features each relies on, and how many bytes cross the network. The inventory in step 1 and the S3 Inventory report in step 2 settle both, and Pilae quotes the move at a fixed price once they are done.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.