S3 Implement Replication#689
Open
blkgrlcto wants to merge 3 commits into
Open
Conversation
blkgrlcto
requested review from
HarshCasper,
aidehn,
bentsku,
k-a-il and
quetzalliwrites
as code owners
bentsku
requested changes
Jun 8, 2026
bentsku
left a comment
bentsku
left a comment
Contributor
There was a problem hiding this comment.
Thanks a lot for jumping on this! Sorry that at the time, we didn't have the new PR templates giving more context for the documentation updates, and in my PR descriptions there were a lot of internal-only informations.
I would remove a lot of the internal details (see comments) and then I think we'd be good to go 👍
How do we want to release such documentation changes? It's already part of dev but not stable yet
| 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. |
Contributor
There was a problem hiding this comment.
nit: this might be giving too much importance to the replication feature, I'd remove it from this top level part
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| Replication can occur within the same region or across regions, and across different account IDs. | |
| Replication can occur within the same region or across regions, and across different accounts. |
| 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. |
Contributor
There was a problem hiding this comment.
note: I wouldn't add implementation specific details about how we handle certain things in the docs
Comment on lines
+274
to
+278
| ### 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. |
Contributor
There was a problem hiding this comment.
same here, I would delete this paragraph entirely 👍
Comment on lines
+280
to
+287
| ### 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. |
Contributor
There was a problem hiding this comment.
similar again here, I think we're giving too much info about the internals, I think a small sentence somewhere that we do support IAM enforcement would be enough
| 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 |
Contributor
There was a problem hiding this comment.
praise: this is really good 👍
| :::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. |
Contributor
There was a problem hiding this comment.
sorry my explanation on the PR was not very good, but I would remove this sentence (the IAM for tag-based filters) because it does work.
The current limitations are:
- explicitly denying
s3:ReplicateTagswill not cause the replication to be denied in LocalStack if the object has tags - objects encrypted with customer provided KMS keys are by default not replicated in AWS, except if you configure it explicitly with https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication-config-for-kms-objects.html#replications. In LocalStack, even with the configuration, they are not replicated currently
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
ReplicationStatusfield and its possible valuesRelated Docs tickets
ReplicationStatus)