AWS AmazonS3: S3 replication: document rule exclusions and KMS multi-Region key replicas
Summary
Adds a new 'Excluding objects from a rule' section describing how to use the <Not>/<Or> filter elements to exclude prefixes or tags from a replication rule (including rule-priority, delete-marker, and status behavior), and adds documentation for the <UseSourceMultiRegionKey> element that encrypts replicas with the related AWS KMS multi-Region key in the destination Region.
Security assessment
The change is purely documentation of S3 replication configuration features. The KMS portion documents how replicas are encrypted with a related multi-Region key (or a ReplicaKmsKeyID for single-Region keys), which is encryption-related guidance with security impact for data-at-rest in the destination bucket. The exclusion section documents replication scope (objects not replicated keep status NONE and generate no replication events), which is security-adjacent because unreplicated data is not covered by the destination copy, but no specific vulnerability, CVE, or incident is referenced.
Evidence
+For objects encrypted with AWS KMS multi-Region keys, you can add the `<UseSourceMultiRegionKey>` element. Amazon S3 encrypts each replica with the related multi-Region key in the destination Region. With this element, `<ReplicaKmsKeyID>` is optional and applies to objects encrypted with single-Region keys. The rule still requires the `<SourceSelectionCriteria>` element shown in the previous example.
Diff
diff --git a/AmazonS3/latest/userguide/replication-add-config.md b/AmazonS3/latest/userguide/replication-add-config.md index 6c55a9c..67a2c8e 100644 --- a//AmazonS3/latest/userguide/replication-add-config.md +++ b//AmazonS3/latest/userguide/replication-add-config.md @@ -110 +110 @@ You can also specify other configuration options. For example, you might choose -To choose a subset of objects that the rule applies to, add an optional filter. You can filter by object key prefix, object tags, or a combination of both. If you filter on both a key prefix and object tags, Amazon S3 combines the filters by using a logical `AND` operator. In other words, the rule applies to a subset of objects with both a specific key prefix and specific tags. +To choose a subset of objects that the rule applies to, add an optional filter. You can filter by object key prefix, object tags, or a combination of both. If you filter on both a key prefix and object tags, Amazon S3 combines the filters by using a logical `AND` operator. In other words, the rule applies to a subset of objects with both a specific key prefix and specific tags. You can also exclude objects from a rule by prefix or tag. For more information, see Excluding objects from a rule. @@ -184,0 +185,66 @@ To replicate objects that have been tagged after the `PutObject` operation, you +### Excluding objects from a rule + +With exclusions, a rule can replicate a bucket or prefix except the prefixes or tagged objects that you name, such as `logs/` or objects tagged `environment=test`. To exclude objects, add a `<Not>` element to the rule filter. The rule doesn't replicate an object whose key starts with a prefix in `<Not>`, or that has a tag in `<Not>`. + +To exclude one prefix or tag, place it directly inside `<Not>`. To exclude more than one, wrap them in an `<Or>` element. Amazon S3 excludes an object that matches any entry. + +The following filter replicates objects under `data/`, except objects under `data/logs/` or `data/tmp/` and objects with the tag `environment=test`. + + + <Filter> + <And> + <Prefix>data/</Prefix> + <Not> + <Or> + <Prefix>data/logs/</Prefix> + <Prefix>data/tmp/</Prefix> + <Tag> + <Key>environment</Key> + <Value>test</Value> + </Tag> + </Or> + </Not> + </And> + </Filter> + +Exclusions follow these rules: + + * To combine exclusions with an include prefix or tags, `<Not>` goes inside `<And>` with them, as in the previous example. + + * `<Not>` contains exactly one `<Prefix>`, `<Tag>`, or `<Or>` element. + + * `<Or>` is allowed only inside `<Not>`. + + * For a rule with only exclusions, `<Not>` goes directly inside `<Filter>`. The rule applies to all objects in the bucket except the excluded ones. + + + + +The following filter replicates all objects in the bucket except objects under `logs/`. + + + <Filter> + <Not> + <Prefix>logs/</Prefix> + </Not> + </Filter> + +Prefix exclusions match the start of the object key, the same as the include prefix. For example, `data/log` excludes both `data/logs/` and `data/login/`. To exclude a folder, end the prefix with a slash. Tag exclusions match the exact tag key and value when the object is written. + +###### Exclusions and rule priority + +An excluded object doesn't match the rule that excludes it. Another rule for the same destination that matches the object still replicates it, even if that rule has a lower priority. To keep a prefix or tag out of a destination, add the exclusion to every rule for that destination. + +###### Other behavior + +Exclusions also affect replication in the following ways: + + * An object that no rule replicates has the replication status `NONE` and doesn't generate replication events. For more information, see [Getting replication status information](./replication-status.html). + + * Amazon S3 doesn't replicate delete markers under an excluded prefix. A rule that excludes by tag is a tag-based rule, so it doesn't support delete marker replication. For more information, see [Replicating delete markers between buckets](./delete-marker-replication.html). + + * An exclusion applies to objects that you write after you update the rule. Adding an exclusion doesn't remove replicas that are already in the destination. + + + + @@ -369,0 +436,13 @@ Your source bucket might contain objects that were created with server-side encr +For objects encrypted with AWS KMS multi-Region keys, you can add the `<UseSourceMultiRegionKey>` element. Amazon S3 encrypts each replica with the related multi-Region key in the destination Region. With this element, `<ReplicaKmsKeyID>` is optional and applies to objects encrypted with single-Region keys. The rule still requires the `<SourceSelectionCriteria>` element shown in the previous example. + + + <Destination> + <Bucket>arn:aws:s3:::amzn-s3-demo-destination-bucket</Bucket> + <EncryptionConfiguration> + <UseSourceMultiRegionKey> + <Status>Enabled</Status> + </UseSourceMultiRegionKey> + <ReplicaKmsKeyID>Optional: AWS KMS key ID for objects encrypted with single-Region keys</ReplicaKmsKeyID> + </EncryptionConfiguration> + </Destination> +