How to Set Up Cross-Region Replication

To set up cross-region replication, you need two buckets—source and destination. These buckets must be versioning-enabled and in different AWS regions. For a list of AWS regions where you can create a bucket, see Regions and Endpoints in the AWS General Reference.

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 Configuration for a Bucket with Versioning in the Amazon Simple Storage Service Console User Guide.

You can replicate objects from a source bucket to only one destination bucket. If both of the buckets are owned by the same AWS account, do the following to set up cross-region replication from the source to the destination bucket:

Create an IAM role to grant Amazon S3 permission to replicate objects on your behalf.
Add a replication configuration on the source bucket.

In addition, if the source and destination buckets are owned by two different AWS accounts, the destination bucket owner must also add a bucket policy to grant the source bucket owner permissions to perform replication actions.

Create an IAM Role

By default, all Amazon S3 resources—buckets, objects, and related subresources—are private: only the resource owner can access the resource. So, Amazon S3 needs permission to read objects from the source bucket and replicate them to the destination bucket. You grant these permissions by creating an IAM role. When you create an IAM role, you attach the following role policies:

A trust policy in which you trust Amazon S3 to assume the role as shown:
```
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Service":"s3.amazonaws.com"
         },
         "Action":"sts:AssumeRole"
      }
   ]
}
```
Note
The Principal in the policy identifies Amazon S3. For more information about IAM roles, see IAM Roles in the IAM User Guide.
An access policy in which you grant the role permission to perform the replication task on your behalf. The following access policy grants these permissions:
- The s3:GetReplicationConfiguration and s3:ListBucket permissions on the source bucket so Amazon S3 can retrieve replication configuration and list bucket (the current permission model requires the s3:ListBucket permission to access the delete markers).
- The s3:GetObjectVersion and s3:GetObjectVersionAcl permissions on all objects in the versioning-enabled source bucket. This allows Amazon S3 to get a specific object version and ACL on it.
- The s3:ReplicateObject and s3:ReplicateDelete permissions on objects in the destination bucket so that Amazon S3 can replicate objects or delete markers from the destination bucket. For information about delete markers, see Delete Operation and Cross-Region Replication.
- The s3:GetObjectVersionTagging permission allows S3 to read object tags for replication (see Object Tagging). If S3 does not get this permission, S3 will replicate the objects but not the object tags.
For a list of Amazon S3 actions, see Specifying Permissions in a Policy.
```
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetReplicationConfiguration",
            "s3:ListBucket"
         ],
         "Resource":[
            "arn:aws:s3:::source-bucket"
         ]
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetObjectVersion",
            "s3:GetObjectVersionAcl",
            "s3:GetObjectVersionTagging"
         ],
         "Resource":[
            "arn:aws:s3:::source-bucket/*"
         ]
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:ReplicateObject",
            "s3:ReplicateDelete",
            "s3:ReplicateTags"
         ],
         "Resource":"arn:aws:s3:::destination-bucket/*"
      }
   ]
}
```
Permission for the s3:ReplicateObject action also allows replication of object tags. Therefore, if grant permission for he s3:ReplicateObject on the destination bucket, S3 will also replicate object tags (you don't need to explicitly grant permission for the s3:ReplicateTags action).

Add Replication Configuration

When you add a replication configuration to a bucket, Amazon S3 stores the configuration as XML. The following are example configurations. For more information about the XML structure, see PUT Bucket replication in the Amazon Simple Storage Service API Reference.

Example 1: Replication Configuration with One Rule Requesting

The following replication configuration has one rule. It requests Amazon S3 to replicate all objects to the specified destination bucket. The rule specifies an empty prefix indicating all objects. The configuration also specifies an IAM role Amazon S3 can assume to replicate objects on your behalf.

<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Role>arn:aws:iam::account-id:role/role-name</Role>
  <Rule>
    <Status>Enabled</Status>
    <Prefix></Prefix>
    <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination>
  </Rule>
</ReplicationConfiguration>

If the <Rule> does not specify storage class, Amazon S3 uses the storage class of the source object to create object replica. You can optionally specify a storage class, as shown, which Amazon S3 uses to create replicas. Note that the <StorageClass> element cannot be empty.

<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Role>arn:aws:iam::account-id:role/role-name</Role>
  <Rule>
    <Status>Enabled</Status>
    <Prefix></Prefix>
    <Destination>
       <Bucket>arn:aws:s3:::destinationbucket</Bucket>
       <StorageClass>storage-class</StorageClass>
    </Destination>
  </Rule>
</ReplicationConfiguration>

The storage class you specify can be any of the storage classes that Amazon S3 supports, except the GLACIER storage class. You can only transition objects to the GLACIER storage class using lifecycle. For more information, see PUT Bucket replication. For more information about lifecycle management, see Object Lifecycle Management. For more information about storage classes, see Storage Classes.

Example 2: Replication Configuration with Two Rules, Each Specifying a Key Name Prefix

The following replication configuration specifies two rules. The first rule requests Amazon S3 to replicate objects with the key name prefix TaxDocs/. The second rule requests Amazon S3 to replicate objects with key name prefix ProjectDocs/. For example, Amazon S3 replicates objects with key names TaxDocs/doc1.pdf and ProjectDocs/project1.txt, but it does not replicate any object with the key name PersonalDoc/documentA. Note that both rules specify the same destination bucket.

<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Role>arn:aws:iam::account-id:role/role-name</Role>
  <Rule>
    <Prefix>TaxDocs</Prefix>
     ...
  </Rule>
 <Rule>
    <Prefix>ProjectDocs</Prefix>
     ...
  </Rule>
</ReplicationConfiguration>

Note that you cannot specify overlapping prefixes. The following example configuration has two rules specifying overlapping prefixes TaxDocs/ and TaxDocs/2015, which is not allowed.

<ReplicationConfiguration>
  <Role>arn:aws:iam::account-id:role/role-name</Role>
  <Rule>
    <Prefix>TaxDocs</Prefix>
    <Status>Enabled</Status>
    <Destination>
      <Bucket>arn:aws:s3:::destinationbucket</Bucket>
    </Destination>
  </Rule>
  <Rule>
    <Prefix>TaxDocs/2015</Prefix>
    <Status>Enabled</Status>
    <Destination>
      <Bucket>arn:aws:s3:::destinationbucket</Bucket>
    </Destination>
  </Rule>
</ReplicationConfiguration>

When adding replication configuration to a bucket, you have two scenarios to consider depending on who owns the source and destination buckets.

Scenario 1: Buckets Owned by the Same AWS Account

When both the source and destination buckets are owned by the same AWS account, you can use the Amazon S3 console to set up cross-region replication. Assuming you have source and destination buckets that are both versioning-enabled, you can use the console to add replication configuration on the source bucket. For more information, see the following topics:

Walkthrough 1: Configure Cross-Region Replication Where Source and Destination Buckets Are Owned by the Same AWS Account
Enabling Cross-Region Replication in the Amazon Simple Storage Service Console User Guide.

Scenario 2: Buckets Owned by Different AWS Accounts

When the source and destination buckets are owned by two different AWS accounts, you cannot add replication configuration using the console because you cannot specify that a destination bucket is owned by another AWS account in the console. Instead, you need to add replication configuration programmatically using AWS SDKs or the AWS Command Line Interface. To do this, you need to specify a replication configuration as XML. The following is an example replication configuration:

<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Role>arn:aws:iam::46173example:role/CrrRoleName</Role>
  <Rule>
    <Status>Enabled</Status>
    <Prefix>TaxDocs</Prefix>
    <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination>
  </Rule>
</ReplicationConfiguration>

The configuration requests Amazon S3 to replicate objects with the key prefix TaxDocs/ to the destinationbucket. The configuration also specifies an IAM role that Amazon S3 can assume to replicate objects on your behalf. For more information about the XML structure, see PUT Bucket replication in the Amazon Simple Storage Service API Reference.

Because the destination bucket is owned by another AWS account, the destination bucket owners must also grant the source bucket owner permissions to replicate (replicate and delete) objects as shown:

{
   "Version":"2008-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "AWS":"arn:aws:iam::SourceBucketOwnerAcctID:root"
         },
         "Action":["s3:ReplicateObject", "s3:ReplicateDelete"],
         "Resource":"arn:aws:s3:::destination bucket/*"
      }
   ]
}

This bucket policy on the destination bucket grants source bucket owner permissions for the Amazon S3 object operations (s3:ReplicateObject and s3:ReplicateDelete) on the destination bucket.

For an example walkthrough, see Walkthrough 2: Configure Cross-Region Replication Where Source and Destination Buckets Are Owned by Different AWS Accounts.

If objects in the source bucket are tagged, note the following:

If the source bucket owners grants S3 permission for the s3:GetObjectVersionTagging and s3:ReplicateTags actions to replicate object tags (via the IAM role), S3 will replicate the tags along with the objects. For information about the IAM role, see Create an IAM Role.

If the destination bucket owner does not want the tags replicated, the owner can add the following statement to the destination bucket policy to explicitly deny permission for the s3:ReplicateTags action.

...
   "Statement":[
      {
         "Effect":"Deny",
         "Principal":{
            "AWS":"arn:aws:iam::SourceBucketOwnerAcctID:root"
         },
         "Action":["s3:ReplicateTags"],
         "Resource":"arn:aws:s3:::destination bucket/*"
      }
   ]
...