From a64de31475f751960b1bfed78e64c5ad5b767e0d Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Wed, 3 Jun 2026 17:42:54 -0400 Subject: [PATCH 1/3] docs(s3): add S3 Replication documentation --- src/content/docs/aws/services/s3.mdx | 36 ++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index 6b448706..33fab4d2 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -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 @@ -260,6 +261,41 @@ 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. + +### 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**: Replication-specific IAM permissions (such as `s3:ReplicateObject`) are not currently enforced. +- **Metadata replication**: Replication of object metadata changes, used in two-way replication scenarios, is not yet supported. 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. +::: + ## Resource Browser The LocalStack Web Application provides a [Resource Browser](/aws/connecting/console/resource-browser) for managing S3 buckets & configurations. From b6d1b9b40b185048c7407d8e7cd0097678968c5a Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Wed, 3 Jun 2026 18:13:25 -0400 Subject: [PATCH 2/3] docs(s3): add metadata replication support to S3 Replication section --- src/content/docs/aws/services/s3.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index 33fab4d2..78af38f9 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -277,6 +277,13 @@ 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. +### 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`. @@ -293,7 +300,7 @@ The possible values follow AWS semantics: The following replication features are not yet supported in LocalStack and will be available in a future release: - **IAM enforcement**: Replication-specific IAM permissions (such as `s3:ReplicateObject`) are not currently enforced. -- **Metadata replication**: Replication of object metadata changes, used in two-way replication scenarios, is not yet supported. 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. +- **ACL replication**: Replication of Access Control Lists is not currently supported. ::: ## Resource Browser From ef589a8aeaa2395315deb1a54d63f294bc200361 Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Wed, 3 Jun 2026 18:20:07 -0400 Subject: [PATCH 3/3] docs(s3): add IAM enforcement documentation to S3 Replication section --- src/content/docs/aws/services/s3.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index 78af38f9..5c5a1a4f 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -277,6 +277,15 @@ 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: @@ -299,7 +308,7 @@ The possible values follow AWS semantics: :::note The following replication features are not yet supported in LocalStack and will be available in a future release: -- **IAM enforcement**: Replication-specific IAM permissions (such as `s3:ReplicateObject`) are not currently enforced. +- **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. :::