Menu
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

PUT Bucket replication

Description

In a versioning-enabled bucket, this operation creates a new replication configuration (or replaces an existing one, if present). Amazon S3 stores the configuration in the replication subresource associated with the bucket. If the replication subresource does not exist, Amazon S3 creates it; otherwise, Amazon S3 replaces the configuration stored in the subresource. For information about replication configuration, go to Cross-Region Replication in the Amazon Simple Storage Service Developer Guide.

Important

If you have an object expiration lifecycle policy in your non-versioned bucket and you want to maintain the same permanent delete behavior when you enable versioning, you must add a noncurrent expiration policy. The noncurrent expiration lifecycle policy will manage the deletes of the noncurrent object versions in the version-enabled bucket. (A version-enabled bucket maintains one current and zero or more noncurrent object versions.) For more information, see Lifecycle and Versioning in the Amazon Simple Storage Service Developer Guide.

This operation requires permission for the s3:PutReplicationConfiguration action. For more information about permissions, go to Using Bucket Policies and User Policies in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

Copy
PUT /?replication HTTP/1.1 Host: bucketname.s3.amazonaws.com Content-Length: length Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) Content-MD5: MD5 Replication configuration XML in the body

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. This header must be used as a message integrity check to verify that the request body was not corrupted in transit. For more information, go to RFC 1864.

Type: String

Default: None

Yes

Request Body

You specify the replication configuration in the request body. The configuration includes one or more rules. Each rule provides information such as an key name prefix identifying objects with specific prefixes that you want to replicate (an empty prefix indicates all objects), rule status, and details about the destination.

The destination details include the bucket where you want replicas stored and optional storage class you want to use to store the replicas.

Amazon S3 acts only on rules with the status "Enabled." The configuration also identifies an IAM role for Amazon S3 to assume for copying objects. This role must have sufficient permissions to read objects from the source bucket and replicate them into the target bucket.

Copy
<ReplicationConfiguration> <Role>IAM-role-ARN</Role> <Rule> <ID>Rule-1</ID> <Status>rule-status</Status> <Prefix>key-prefix</Prefix> <Destination>       <Bucket>arn:aws:s3:::bucket-name</Bucket> <StorageClass>optional-destination-storage-class-override</StorageClass>       </Destination> </Rule> <Rule> <ID>Rule-2</ID> ... </Rule> ... </ReplicationConfiguration>

The following table describes the XML elements in the replication configuration:

Name Description Required
ReplicationConfiguration

Container for replication rules. You can add as many as 1,000 rules. Total replication configuration size can be up to 2 MB.

Type: Container

Children: Rule

Ancestor: None

Yes
Role

Amazon Resource Name (ARN) of an IAM role for Amazon S3 to assume when replicating the objects.

Type: String

Ancestor: Rule

Yes
Rule

Container for information about a particular replication rule. Replication configuration must have at least one rule and can contain up to 1,000 rules.

Type: Container

Ancestor:ReplicationConfiguration

Yes
ID

Unique identifier for the rule. The value cannot be longer than 255 characters.

Type: String

Ancestor: Rule

No
Status

The rule is ignored if status is not Enabled.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled.

Yes
Prefix

Object keyname prefix identifying one or more objects to which the rule applies. Maximum prefix length can be up to 1,024 characters. Overlapping prefixes are not supported.

Type: String

Ancestor: Rule

Yes
Destination

Container for destination information.

Type: Container

Ancestor: Rule

Yes
Bucket

Amazon resource name (ARN) of the bucket where you want Amazon S3 to store replicas of the object identified by the rule.

If you have multiple rules in your replication configuration, note that all these rules must specify the same bucket as the destination. That is, replication configuration can replicate objects only to one destination bucket.

Type: String

Ancestor: Destination

Yes
StorageClass Optional destination storage class override to use when replicating objects. If not specified, Amazon S3 uses the storage class of the source object to create object replica.

Type: String

Ancestor: Destination

Default: Storage class of the source object.

Valid Values: STANDARD | STANDARD_IA | REDUCED_REDUNDANCY

Constraints: You cannot specify GLACIER as the storage class. You can transition objects to the GLACIER storage class using lifecycle configuration. For more information, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

No

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

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Example 1: Add 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 to the exampletargetbucket bucket any new objects created with the key name prefix "TaxDocs".

After you add a replication configuration to your bucket, Amazon S3 assumes the IAM role specified in the configuration in order to replicate objects on behalf of the bucket owner, which is the AWS account that created the bucket.

Copy
PUT /?replication HTTP/1.1 Host: examplebucket.s3.amazonaws.com x-amz-date: Wed, 11 Feb 2015 02:11:21 GMT Content-MD5: q6yJDlIkcBaGGfb3QLY69A== Authorization: authorization string Content-Length: 406 <ReplicationConfiguration> <Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role> <Rule> <ID>rule1</ID> <Prefix>TaxDocs</Prefix> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::exampletargetbucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>

The following is a sample response.

Copy
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

If you want Amazon S3 to replicate objects having key name prefixes other than "TaxDocs", you can add more rules to the replication configuration. However, you cannot set two rules that specify overlapping prefixes, implying two rules for the same set of objects. For example, Amazon S3 will respond with an error if you attempt to set the following replication configuration on a bucket.

Copy
<ReplicationConfiguration> <Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role> <Rule> <ID>rule1</ID> <Prefix>TaxDocs</Prefix> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::exampletargetbucket1</Bucket> </Destination> </Rule> <Rule> <ID>rule2</ID> <Prefix>TaxDocs/2015</Prefix> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::exampletargetbucket1</Bucket> </Destination> </Rule> </ReplicationConfiguration>

In this non-working replication configuration, note the following:

  • The first rule requests Amazon S3 to replicate objects with the key name prefix "TaxDocs" to a bucket.

  • The second rule requests Amazon S3 to replicate objects with the key name prefix "TaxDocs/2015" to another bucket.

Suppose you upload an object with keyname "TaxDocs/2015/doc1.pdf", the keyname prefix satisfies both rules. Amazon S3 does not support adding replication configuration with rules that specify overlapping prefixes.

You can optionally specify storage class for the object replicas as shown in the XML fragment which directs Amazon S3 to use the STANDARD_IA storage class when creating object replicas:

Copy
<Destination> <Bucket>arn:aws:s3:::exampletargetbucket1</Bucket> <StorageClass>STANDARD_IA</StorageClass> </Destination>