Migrate an S3 application to Rabata

Use this runbook to move an existing application's object storage to Rabata while keeping a tested rollback path. The migration is complete when the application—not just a transfer process—can perform its required storage operations against Rabata.

Inventory your current application

Before changing configuration, record how the application uses object storage:

• the SDK, library, or storage adapter and its version
• where the endpoint, signing region, bucket, and credentials are configured
• every operation the application depends on, such as writes, reads, prefix listings, deletes, multipart uploads, or presigned requests
• addressing mode, object-key conventions, metadata, content types, and cache headers
• required platform features, such as versioning, lifecycle rules, object locking, encryption controls, or ACL behavior
• current object count and stored bytes, plus a way to compare them after migration

Treat this inventory as your compatibility and acceptance checklist. Do not assume that an optional S3 feature works until your application has exercised it successfully.

Create an isolated Rabata configuration

Create a Rabata access key and a private test bucket in the dashboard. Keep the current production configuration unchanged.

Use these product values wherever your client asks for them:

Put the values in your application's normal secret and configuration system. A generic environment layout looks like this:

S3_ENDPOINT=https://s3.us-east-1.rabata.io
S3_REGION=us-east-1
S3_BUCKET=your-rabata-test-bucket
AWS_ACCESS_KEY_ID=your-rabata-access-key
AWS_SECRET_ACCESS_KEY=your-rabata-secret-key

Do not commit credentials to source control. If your application already uses different variable names, keep those names and change only their values.

Run compatibility checks through your application

Point a development or staging instance at the isolated Rabata configuration. Run checks through the same code path production uses:

1. Write an object with a unique migration-test prefix.
2. Read the object back and compare its bytes.
3. List the prefix and confirm the new key appears.
4. Verify the metadata, content type, and cache headers your application relies on.
5. Overwrite or update an object if that is part of the normal workflow.
6. Exercise multipart uploads and presigned requests only if the application uses them.
7. Delete the test objects and confirm cleanup.

Repeat the checks for every required operation from your inventory. Resolve application errors, signing errors, and behavior differences before moving historical objects.

Prepare historical objects

Choose the historical data the application must have on Rabata at cutover. Use your team's established S3 data-movement process; the correctness requirements are independent of the transfer software.

Plan for:

• a first copy while the current store remains the source of truth
• preservation of exact object keys, bytes, metadata, and content types
• an incremental pass or a controlled write freeze for objects changed during the first copy
• before-and-after object counts and byte totals
• checksums where both systems expose comparable values
• sampled reads through the application, including large and recently changed objects
• a record of failures that can be retried without recopying verified objects

Keep the current store intact. A completed copy is not yet permission to remove the rollback source.

Prepare production configuration

Create separate production credentials and the production bucket. Store the Rabata endpoint, region, bucket, and credentials in the same deployment system as the existing storage configuration.

Preserve the previous values so they can be restored quickly. If the application supports a canary environment or a small cohort, prepare that path before the main switch.

Cut over production

Choose a quiet window with an application owner and an operator present.

1. Finish the incremental copy or begin the planned write freeze.
2. Deploy the Rabata configuration to the canary or production application.
3. Confirm a production write, read, list, and delete through the application.
4. Resume normal traffic and watch application errors, storage errors, and latency.
5. Record any objects written after the switch so they can be reconciled if rollback is required.

Avoid changing application storage behavior during the same release. A configuration-only cutover is easier to diagnose and reverse.

Accept the migration

Accept the migration only when all of these statements are true:

• the production application can perform every required operation in the inventory
• new objects and sampled historical objects can be read through the application
• object counts, byte totals, and verification samples meet the agreed threshold
• metadata and content types used by clients are preserved
• no unexplained storage or signing errors remain
• the Rabata dashboard shows the expected bucket and usage
• the application owner and operator have signed off

Keep the old storage account, data, and credentials available for the retention period your team agreed on.

Roll back safely

Define rollback triggers before cutover, such as failed required operations, unexpected error rates, or verification drift.

If a trigger occurs:

1. Stop or limit writes while you determine which store holds the newest objects.
2. Restore the previous endpoint, region, bucket, and credentials.
3. Deploy and verify the application against the previous store.
4. Reconcile objects written to Rabata during the cutover window before normal writes resume.
5. Retain the Rabata data and logs until the incident is understood.

Do not delete either copy while data may exist in only one location.

After acceptance

Rotate or remove temporary migration credentials, remove test objects, and document the final production configuration. Review billing and pricing after a complete calendar month, then retire the old storage only after the rollback retention period has passed.