From a64de31475f751960b1bfed78e64c5ad5b767e0d Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Wed, 3 Jun 2026 17:42:54 -0400 Subject: [PATCH 1/5] 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/5] 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/5] 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. ::: From 765ce98832192b35556bae076559663692fd5de7 Mon Sep 17 00:00:00 2001 From: Kiah Imani Date: Thu, 25 Jun 2026 11:26:02 -0400 Subject: [PATCH 4/5] Apply suggestion from @bentsku Co-authored-by: Ben Simon Hartung <42031100+bentsku@users.noreply.github.com> --- src/content/docs/aws/services/s3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index 5c5a1a4f..98b1983d 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -264,7 +264,7 @@ However, LocalStack does not support the actual encryption and decryption of obj ## 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. +Replication can occur within the same region or across regions, and across different accounts. LocalStack supports the following replication configurations: From 104d813777b598716c88ceaac3fbdb028ec1862a Mon Sep 17 00:00:00 2001 From: Kiah Imani Date: Thu, 25 Jun 2026 11:40:44 -0400 Subject: [PATCH 5/5] Update s3.mdx address PR review feedback on S3 Replication section --- src/content/docs/aws/services/s3.mdx | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index 98b1983d..56234492 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -15,7 +15,6 @@ 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 @@ -269,26 +268,17 @@ Replication can occur within the same region or across regions, and across diffe 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. +- **Two-way replication**: Both buckets are configured as source and destination for each other, and replication is configured to work in both directions. ### 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. +LocalStack supports IAM enforcement for S3 replication. +IAM permissions are evaluated in the context of each replication task using the IAM engine directly, which mirrors how AWS itself handles replication permissions. ### Metadata replication LocalStack supports replication of object metadata — specifically tags and Object Lock settings. Metadata replication operates in two modes: +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. @@ -308,7 +298,8 @@ 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 for tag-based filters**: IAM permission evaluation for replication rules that use tag-based filters is not yet fully supported. +- **`s3:ReplicateTags` deny evaluation**: Explicitly denying `s3:ReplicateTags` will not cause replication to be denied if the object has tags. +- **KMS-encrypted object replication**: Objects encrypted with customer-provided KMS keys are not replicated, even when replication of KMS-encrypted objects is explicitly configured. See [Replicating objects created with server-side encryption using AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication-config-for-kms-objects.html#replications) in the AWS documentation for more details. - **ACL replication**: Replication of Access Control Lists is not currently supported. :::