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.

Important

When you call the Put Bucket replication operation, you must have the iam:PassRole permission to be able to pass the IAM role that grants Amazon S3 replication permissions. The IAM role is specified by the Amazon Resource Name (ARN) that is used in the Role element in the replication configuration XML. For more information, see Granting a User Permissions to Pass a Role to an AWS Service in the IAM User 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 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, rule status, and details that are relevant to the destination. An empty prefix indicates all objects.

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.

<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

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 as many as 1,000 rules. Total replication configuration size is limited 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 is limited to 2 MB.

Type: Container

Children: Rule

Ancestor: None

Yes
Role

Amazon Resource Name (ARN) of an IAM role that Amazon S3 can 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 set to Enabled.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled

Yes
Prefix

Object key name prefix that identifies one or more objects to which the rule applies. Maximum prefix length is 1,024 characters. Prefixes can't overlap.

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 rules must specify the same bucket as the destination. 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 a storage class is 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 | ONEZONE_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 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

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

If you don't add this element 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 owner.

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 a key managed by AWS Key Management Service (AWS KMS), 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. 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 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

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 that the proposed configuration is valid when you call the PUT operation. The following table lists 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

The following examples show how to add a replication configuration and change the replication owner in a cross-account scenario.

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 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 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: 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:

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 that have 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, which implies 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:

<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:

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

  • The second rule tells Amazon S3 to replicate objects with the key name prefix TaxDocs/2015.

Suppose that you upload an object with the 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 following XML fragment. The code tells Amazon S3 to use the STANDARD_IA storage class when creating object replicas.

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

Example 2: Change the Replica Owner in a Cross-Account Scenario

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