Skip to content

S3 Implement Replication #689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
blkgrlcto wants to merge 3 commits into
base: main
Choose a base branch
from
Open

S3 Implement Replication #689

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a64de31
docs(s3): add S3 Replication documentation
blkgrlcto Jun 3, 2026
b6d1b9b
docs(s3): add metadata replication support to S3 Replication section
blkgrlcto Jun 3, 2026
ef589a8
docs(s3): add IAM enforcement documentation to S3 Replication section
blkgrlcto Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions src/content/docs/aws/services/s3.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Each object or file within S3 encompasses essential attributes such as a unique
S3 can store unlimited objects, allowing you to store, retrieve, and manage your data in a highly adaptable and reliable manner.

LocalStack allows you to use the S3 APIs in your local environment to create new buckets, manage your S3 objects, and test your S3 configurations locally.
LocalStack also supports S3 Replication, allowing you to emulate cross-bucket, cross-region, and cross-account object replication in your local environment.
The supported APIs are available on the API coverage section for [S3](#api-coverage) and [S3 Control](#api-coverage-s3-control), which provides information on the extent of S3's integration with LocalStack.

## Getting started
Expand Down Expand Up @@ -260,6 +261,57 @@ LocalStack supports SSE-C parameter validation for the following S3 APIs:

However, LocalStack does not support the actual encryption and decryption of objects using SSE-C.

## S3 Replication

S3 Replication allows you to automatically copy objects from a source bucket to one or more destination buckets.
Replication can occur within the same region or across regions, and across different account IDs.

LocalStack supports the following replication configurations:

- **One-way replication**: Objects are replicated from a source bucket to a destination bucket. You can scope replication using prefix-based or tag-based filtering, and optionally override the storage class for objects written to the destination bucket.
- **Two-way replication**: Both buckets are configured as source and destination for each other. LocalStack correctly handles this by tracking each object's `ReplicationStatus` and preventing `REPLICA` objects from being re-replicated in a loop.

### How replication works in LocalStack

LocalStack uses a scan-based replication mechanism.
A background worker scans buckets with at least one enabled replication rule approximately every second, then dispatches replication tasks for any objects that qualify.
Because of this, replication is **eventually consistent** — there is a short delay between an object being written and it appearing in the destination bucket.

### IAM enforcement

LocalStack enforces IAM permissions for S3 replication tasks using the IAM engine directly, which mirrors how AWS itself handles replication permissions.
Rather than enforcing permissions at the API level, LocalStack evaluates the required IAM actions in the context of each replication task — taking into account the object version, replication configuration, bucket context, and object tags.

LocalStack assumes the IAM role specified in your replication configuration and caches the result for subsequent tasks.
The cache is invalidated automatically if the replication configuration changes.
If the assumed role does not have the required permissions for a given replication task, that replication will fail.

### Metadata replication

LocalStack supports replication of object metadata — specifically tags and Object Lock settings. Metadata replication operates in two modes:

- **Default metadata replication**: When a source object's metadata is modified, those changes are automatically propagated to all of its replicas. This behavior is enabled by default and requires no additional configuration.
- **Replica metadata synchronization**: When enabled on the destination bucket, metadata changes made directly to a replica are synced back to the source object. This applies only when two-way replication is configured. See [Replication for metadata changes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication-for-metadata-changes.html) in the AWS documentation for more details.

### ReplicationStatus

Replicated objects are assigned a `ReplicationStatus` field, which you can inspect with `GetObject` or `HeadObject`.
The possible values follow AWS semantics:

| Status | Meaning |
|---|---|
| `PENDING` | Replication has been queued but not yet completed |
| `COMPLETED` | Object was successfully replicated to the destination |
| `FAILED` | Replication could not be completed |
| `REPLICA` | This object is itself a copy created by replication |

:::note
The following replication features are not yet supported in LocalStack and will be available in a future release:

- **IAM enforcement for tag-based filters**: IAM permission evaluation for replication rules that use tag-based filters is not yet fully supported.
- **ACL replication**: Replication of Access Control Lists is not currently supported.
:::

## Resource Browser

The LocalStack Web Application provides a [Resource Browser](/aws/connecting/console/resource-browser) for managing S3 buckets & configurations.
Expand Down