The Wayback Machine - https://web.archive.org/web/20190716164405/https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTreplication.html
Sign In to the Console
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » Operations on Buckets » PUT Bucket replication

PUT Bucket replication

Description

Creates a replication configuration or replaces one. For more information, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.

Requests

Syntax

PUT /?replication HTTP/1.1
Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string 
Content-MD5: MD5

Replication configuration XML in the body

For more information, see the following topics:

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required
Content-MD5

The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message integrity check to verify that the request body was not corrupted in transit. For more information, see RFC 1864.

Type: String

Default: None

 Yes
x-amz-bucket-object-lock-token

Use to allow Amazon S3 object lock to be enabled for an existing bucket.

Type: String

Default: None

 No

Request Body

Specify the replication configuration in the request body. In the replication configuration, you provide the name of the destination bucket where you want Amazon S3 to replicate objects, the IAM role that Amazon S3 can assume to replicate objects on your behalf, and other relevant information.

A replication configuration must include at least one rule, and can contain a maximum of 1,000. Each rule identifies a subset of objects to replicate by filtering the objects in the source bucket. To choose additional subsets of objects to replicate, add a rule for each subset. All rules must specify the same destination bucket.

You can add other configuration options to rules. For more information, see Replication Configuration Overview in the Amazon S3 Developer Guide.

The following table describes the XML elements in a replication configuration.

Name Description Required
Account

The account ID of the destination bucket owner. In a cross-account scenario, if you tell Amazon S3 to change replica ownership to the AWS account that owns the destination bucket by adding the AccessControlTranslation element, this is the account ID of the destination bucket owner. For more information, see Cross-Region Replication Additional Configuration: Change Replica Owner in the Amazon Simple Storage Service Developer Guide.

Type: String

Ancestor: Destination

Container for replication rules. You can add a maximum of 1,000 rules. The maximum size of a replication configuration size is 2 MB.

Type: Container

Children: Rule

Ancestor: None

 Yes, if you specify the AccessControlTranslation element
ReplicationConfiguration

A container for replication rules. You can add a maximum of 1,000 rules. The maximum size of a replication configuration size is 2 MB.

Type: Container

Children: Rule

Ancestor: None

 Yes
Role

The Amazon Resource Name (ARN) of an IAM role that Amazon S3 can assume when replicating the objects.

Type: String

Ancestor: Rule

 Yes
Rule

A container for information about a particular replication rule. A replication configuration must include at least one rule, and can contain up to 1,000 rules.

Type: Container

Ancestor:ReplicationConfiguration

 Yes
ID

A unique identifier for the rule. The value is limited to 255 characters.

Type: String

Ancestor: Rule

 No
Status

If you don't set the Status to Enabled, the rule is ignored.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled

 Yes
Destination

A container for destination information.

Type: Container

Ancestor: Rule

 Yes
Bucket

The Amazon Resource Name (ARN) of the bucket where you want Amazon S3 to store replicas of the objects identified by the rule.

If you have multiple rules, all rules must specify the same bucket as the destination. A replication configuration can replicate objects to only one destination bucket.

Type: String

Ancestor: Destination

 Yes
StorageClass An optional destination storage class override to use when replicating objects. If you don't specify a storage class, Amazon S3 uses the storage class of the source object for object replicas.

Type: String

Ancestor: Destination

Default: Storage class of the source object

Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE

Constraints: If you specify the STANDARD_IA or ONEZONE_IA storage class for object replicas, there are pricing considerations if the object replicas are less than 128 KB. For more information, see https://aws.amazon.com/s3/pricing/.

No
AccessControlTranslation

Use only in a cross-account scenario, where different AWS accounts own source and destination buckets, to change replica ownership to the AWS account that owns the destination bucket.

If you don't add this element to the replication configuration, replicas are owned by same AWS account that owns the source object.

Type: String

Ancestor: Destination

 No
Owner Identifies the replica owner.

Type: String

Ancestor: AccessControlTranslation

Default: Storage class of the source object

Valid values: Destination

 Yes, if AccessControlTranslation is specified

Specifying a Filter

To specify a subset of the objects in the source bucket to apply a replication rule to, add the Filter element as a child of the Rule element. You can filter objects based on an object key prefix, one or more object tags, or both. The following table describes the elements for filtering in a Rule.

Name Description Required
Filter

A container that describes the filters that identify the source objects that you want to replicate.

You can optionally specify one of these child elements: Prefix, Tag, or And.

Use the And child element to specify an object filter that combines an object key Prefix and one or more Tags.

An empty Filter element indicates that the rule applies to all objects.

Ancestor: Rule

Yes.

And

A container element for a Prefix and one or more Tag elements. At least one child element is required.

Ancestor: Filter

 Yes, if you want to specify more than one filtering criteria. For example, one object key prefix and one or more object tags.
Prefix

An object key prefix that identifies one or more objects to which the rule applies. The maximum length of a Prefix is 1,024 characters. If prefixes in multiple rules overlap (if multiple rules apply to the same object), rule priority determines which rule applies to the object.

Note

In previous versions of replication configuration, only the object key prefix could be used as a rule filter (where you add the Prefix element as a child of the Rule element). Amazon S3 supports this for backward compatibility. But in the lastest configuration, Amazon S3 allows you to specify either the Filter or Prefix as child of the Rule. For more information, see Backward Compatibility in the Amazon S3 Developer Guide.

Type: String

Ancestor: Filter

 No
Tag

A container that provides a tag key and value.

Ancestor: Filter

 No
Key

Provides an object tag key. The Tag Key and Value are case sensitive. A Tag Key can have 1-128 characters.

Type: String

Ancestor: EncryptionConfiguration

No

Value

Provides the object Tag Value. The Tag Key and Value are case sensitive. The Tag Value can have 0-256 characters.

Type: String

Ancestor: EncryptionConfiguration

No

When you add the Filter element in the configuration, you must also add the elements described in this table.

Name Description Required
DeleteMarkerReplication

A container that describes whether Amazon S3 replicates the delete markers. If you specify a Filter, you must specify this element. However, in the latest version of replication configuration (when Filter is specified), Amazon S3 doesn't replicate delete markers. Therefore, the DeleteMarkerReplication element can contain only <Status>Disabled</Status>. For an example configuration, see The Basic Rule Configuration in the Amazon S3 Developer Guide.

Note

If you don't specify the Filter element, Amazon S3 assumes the replication configuration is the earlier version, V1. In the earlier version, Amazon S3 handled replication of delete markers differently. For more information, see Backward Compatibility in the Amazon S3 Developer Guide.

Ancestor: Rule

 Yes, if Filter is specified
Status Indicates whether to replicate delete markers.

Type: String

Ancestor: DeleteMarkerReplication

Valid values: Disabled

 Yes, if DeleteMarkerReplication is specified
Priority

If you specify multiple rules with overlapping filters, identifies the rule priority. For example, if two rules apply to the same object based on the Filter specified, then the rule with higher priority supersedes. The higher the numerical value of this element, the higher the rule priority. For more information, see Backward Compatibility in the Amazon S3 Developer Guide.

Type: Integer

Ancestor: Rule

Valid values: 0 - INT-MAX.

 Yes, if Filter is specified

Handling Replication of Encrypted Objects

By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption with AWS KMS-managed keys, . To replicate AWS MKS-encrypted objects, add the following optional configuration. For information about replication configuration, see CRR: Replicating Objects Created with SSE Using AWS KMS-Managed Encryption Keys in the Amazon Simple Storage Service Developer Guide.

Name Description Required
SourceSelectionCriteria

A container that describes additional filters that identify the source objects that you want to replicate.

Currently, Amazon S3 supports only the filter for objects created with server-side encryption using an AWS KMS-managed key. You can choose to enable or disable replication of these objects.

Ancestor: Rule

 Yes, if you want Amazon S3 to replicate objects created with server-side encryption using AWS KMS-managed keys
SseKmsEncryptedObjects

A container element for Status.

Ancestor: SourceSelectionCriteria

 Yes, if SourceSelectionCriteria is specified
Status

A flag that tells Amazon S3 whether to replicate objects created with server-side encryption using an AWS KMS-managed key.

Type: String

Ancestor: SseKmsEncryptedObjects

Valid Values: Enabled, Disabled

 Yes, if SseKmsEncryptedObjects is specified
EncryptionConfiguration

A container that provides encryption-related information.

Ancestor: Destination

 Yes, if SourceSelectionCriteria is specified
ReplicaKmsKeyID

Provides the AWS KMS Key ID (Key ARN or Alias ARN) of the destination bucket. Amazon S3 uses this key to encrypt replicas.

Type: String

Ancestor: EncryptionConfiguration

 Yes, if EncryptionConfiguration is specified

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

When you call the PUT operation, Amazon S3 checks the validity of the proposed AnalyticsConfiguration element and verifies that the proposed configuration is valid. The following table lists errors and possible causes.

HTTP Error Code Cause
HTTP 400

InvalidRequest

If the <Owner> in <AccessControlTranslation> has a value, the <Account> element must be specified.

HTTP 400 InvalidArgument

The <Account> element is empty. It must contain a valid account ID.

HTTP 400 InvalidArgument

The AWS account specified in the <Account> element must match the destination bucket owner.

For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

The following example shows how to add a replication configuration.

Example 1: Add a Replication Configuration

The following is a sample PUT request that creates a replication subresource on the specified bucket and saves the replication configuration in it. The replication configuration specifies a rule to replicate objects to the exampletargetbucket bucket. The rule includes a filter to replicate only the objects created with the key name prefix TaxDocs and that have two specific tags.

After you add a replication configuration to your bucket, Amazon S3 assumes the AWS Identity and Access Management (IAM) role specified in the configuration to replicate objects on behalf of the bucket owner. The bucket owner is the AWS account that created the bucket. 

PUT /?replication HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
Date: Wed, 11 Feb 2015 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: length

<ReplicationConfiguration>
  <Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role>
  <Rule>
    <ID>rule1</ID>
    <Status>Enabled</Status>
    <Priority>1</Priority>
    <DeleteMarkerReplication>
       <Status>Disabled</Status>
    </DeleteMarkerReplication>
    <Filter>
       <And>
           <Prefix>TaxDocs</Prefix>
           <Tag>
             <Key>key1</Key>
             <Value>value1</Value>
           </Tag>
           <Tag>
             <Key>key1</Key>
             <Value>value1</Value>
           </Tag>
       </And>
    </Filter>
    <Destination>
      <Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
    </Destination>
  </Rule>
</ReplicationConfiguration>

The following is a sample response:

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 11 Feb 2015 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Filtering using the <Filter> element is supported in the latest XML configuration. If you are using an earlier version of the XML configuration, you can filter only on key prefix. In that case, you add the <Prefix> element as a child of the <Rule>.

For more examples of replication configuration, see Replication Configuration Overview in the Amazon S3 Developer Guide.