S3 Implement Replication

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,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.