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. If it does exist, Amazon S3 replaces the configuration stored in the subresource. For information about replication configuration, see 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 permissions for the s3:PutReplicationConfiguration action. For more information about permissions, see 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 Content-MD5: MD5 Replication configuration XML in the body

For more information about authorization, see Authenticating Requests (AWS Signature Version 4).

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, see 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 a key name prefix that identifies objects with specific prefixes that you want to replicate (an empty prefix indicates all objects), rule status, and details relevant to the destination.

The destination details include the bucket where you want replicas stored and, optionally, the 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 so that Amazon S3 can copy 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> <Account>The destination bucket owner account Id used if owner override is used</Account> <AccessControlTranslation> <Owner>Destination</Owner> </AccessControlTranslation>       </Destination> </Rule> <Rule> <ID>Rule-2</ID> ... </Rule> ... </ReplicationConfiguration>

In the <Destination>, both <StorageClass> and <AccessControlTranslation> are optional. If you specify the <AccessControlTranslation> element to change the replica ownership to the destination bucket owner, you must also specify the <Account> element.

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

Name Description Required
Account

Destination bucket owner account ID. In a cross-account scenario, if you direct 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 as many as 1,000 rules. Total replication configuration size can be up to 2 MB.

Type: Container

Children: Rule

Ancestor: None

Yes, if you specify the AccessControlTranslation element.
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 key name 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, all these rules must specify the same bucket as the destination. That is, a 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 replicas.

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, see Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

  • When you specify the STANDARD_IA storage class for object replicas, there are pricing considerations when the object replicas are less than 128 KB. For more information, see https://aws.amazon.com/s3/pricing/.

No
AccessControlTranslation

Optional. Add this only in a cross-account scenario (where source and destination bucket owners are not the same), and you want to change replica ownership to the AWS account that owns the destination bucket.

If this is not added to the replication configuration, the replicas are owned by same AWS account that owns the source object.

Type: String

Ancestor: Destination

No
Owner Identifies the replica ownership.

Type: String

Ancestor: AccessControlTranslation

Default: Storage class of the source object.

Valid values: Destination

Yes, if AccessControlTranslation is specified.

If you want Amazon S3 to replicate objects created with server-side encryption using an AWS KMS-managed key, you must add the following configuration elements. 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

Container that describes additional filters in identifying source objects that you want to replicate.

Currently, Amazon S3 supports only the filter that you can specify for objects created with server-side encryption using an AWS KMS-managed key. That is, 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

Container element for Status.

Ancestor: SourceSelectionCriteria

Yes, if SourceSelectionCriteria is specified.
Status

Flag that directs 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

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) for 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

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

HTTP Error Code Cause
HTTP 400

InvalidRequest

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

HTTP 400 InvalidArgument

<Account> element is empty and 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

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

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

You can optionally specify the 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>

Example 2: Change Replica Owner in Cross-Account Scenario

For more information, see Cross-Region Replication Additional Configuration: Change Replica Owner in the Amazon Simple Storage Service Developer Guide.