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

Walkthrough 2: Configure Cross-Region Replication Where Source and Destination Buckets Are Owned by Different AWS Accounts

In this walkthrough, you set up cross-region replication on the source bucket owned by one account to replicate objects in a destination bucket owned by another account.

The process is the same as setting up cross-region replication when both buckets are owned by the same account, except that you do one extra step—the destination bucket owner must create a bucket policy granting the source bucket owner permission for replication actions.

In this exercise, you perform all of the steps using the console, except creating an IAM role and setting a replication configuration on the source bucket. You perform these steps using either the AWS CLI or the AWS SDK for Java.

  1. Create two buckets.

    1. Create a source bucket in an AWS region. For example, Oregon (us-west-2) in Account A. For instructions, go to Creating a Bucket in the Amazon Simple Storage Service Console User Guide.

    2. Create a destination bucket in another AWS region. For example, US East (N. Virginia) region (us-east-1) in Account B.

  2. Enable versioning on both the buckets. For instructions, see Enabling Bucket Versioning in the Amazon Simple Storage Service Console User 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 Configuration for a Bucket with Versioning in the Amazon Simple Storage Service Console User Guide.

  3. Add the following bucket policy on the destination bucket to allow the source bucket owner permission for replication actions:

    Copy to clipboard
    { "Version":"2008-10-17", "Id":"", "Statement":[ { "Sid":"Stmt123", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::AWS-ID-Account-A:root" }, "Action":["s3:ReplicateObject", "s3:ReplicateDelete"], "Resource":"arn:aws:s3:::destination-bucket/*" } ] }

    For instructions, see Editing Bucket Permissions in the Amazon Simple Storage Service Console User Guide.

  4. Create an IAM role in Account A. Then, Account A specifies this role when adding replication configuration on the source bucket in the following step.

    Use the AWS CLI to create this IAM role. For instructions about how to setup the AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

    1. Copy the following policy and save it to a file called S3-role-trust-policy.json. The policy grants Amazon S3 permission to assume the role.

      Copy to clipboard
      { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"s3.amazonaws.com" }, "Action":"sts:AssumeRole" } ] }
    2. Copy the following policy and save it to a file called S3-role-permissions-policy.json. This access policy grants permission for various Amazon S3 bucket and object actions. In the following step, you add the policy to the IAM role you are creating.

      Copy to clipboard
      { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "s3:GetObjectVersion", "s3:GetObjectVersionAcl" ], "Resource":[ "arn:aws:s3:::source-bucket/*" ] }, { "Effect":"Allow", "Action":[ "s3:ListBucket", "s3:GetReplicationConfiguration" ], "Resource":[ "arn:aws:s3:::source-bucket" ] }, { "Effect":"Allow", "Action":[ "s3:ReplicateObject", "s3:ReplicateDelete" ], "Resource":"arn:aws:s3:::destination-bucket/*" } ] }
    3. Run the following CLI command to create a role:

      Copy to clipboard
      $ aws iam create-role \ --role-name RoleForS3CrossAccountCrossRegionReplication \ --assume-role-policy-document file://S3-role-trust-policy.json
    4. Run the following CLI command to create a policy:

      Copy to clipboard
      $ aws iam create-policy \ --policy-name PolicyForS3CrossAccountCrossRegionReplication \ --policy-document file://S3-role-permissions-policy.json
    5. Write down the policy ARN that is returned in the output by the preceding command.

    6. Run the following CLI command to attach the policy to the role:

      Copy to clipboard
      $ aws iam attach-role-policy \ --role-name RoleForS3CrossAccountCrossRegionReplication \ --policy-arn policy-arn

      Now Account A has created a role that the necessary Amazon S3 actions so it can replicate objects.

  5. Enable cross-region replication on the source bucket in Account A. In the replication configuration you add one rule requesting Amazon S3 to replicate objects with the key name prefix Tax/ to the specified destination bucket. Amazon S3 saves the replication configuration as XML as shown in the following example:

    Copy to clipboard
    <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::AWS-ID-Account-A:role/role-name</Role> <Rule> <Status>Enabled</Status> <Prefix>Tax</Prefix> <Destination><Bucket>arn:aws:s3:::destination-bucket</Bucket></Destination> </Rule> </ReplicationConfiguration>

    You can add the replication configuration to your source bucket using either the AWS CLI or AWS SDK.

    • Using AWS CLI.

      The AWS CLI requires you to specify the configuration as JSON. Save the following JSON in a file (replication.json). You need to provide your bucket name and IAM role ARN.

      Copy to clipboard
      { "Role": "arn:aws:iam::AWS-ID-Account-A:role/role-name", "Rules": [ { "Prefix": "Tax", "Status": "Enabled", "Destination": { "Bucket": "arn:aws:s3:::destination-bucket" } } ] }

      Then, run the CLI command to add replication configuration to your source bucket:

      Copy to clipboard
      $ aws s3api put-bucket-replication \ --bucket source-bucket \ --replication-configuration file://replication.json

      For instructions on how to set up the AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

      Account A can use the get-bucket-replication command to retrieve the replication configuration:

      Copy to clipboard
      $ aws s3api get-bucket-replication \ --bucket source-bucket
    • Using the AWS SDK for Java.

      For a code example, see How to Set Up Cross-Region Replication Using the AWS SDK for Java.

  6. Test the setup as follows:

    • Using Account A credentials, create objects in the source bucket and verify that Amazon S3 replicated the objects in the destination bucket owned by Account B. Time it takes for Amazon S3 to replicate an object depends on the object size. For information about finding replication status, see How to Find Replication Status of an Object.

      Note

      When you upload objects in the source bucket the object key name must have a Tax prefix (for example, Tax/document.pdf). Accordingly to the replication configuration Account A added to the source bucket, Amazon S3 will only replicate objects with the Tax prefix.

    • Update an object's ACL in the source bucket and verify that changes appear in the destination bucket.

      For instructions, go to Editing Object Permissions in the Amazon Simple Storage Service Console User Guide.

    • Update the object's metadata and verify that the changes appear in the destination bucket.

      For instructions, go to Editing Object Metadata in the Amazon Simple Storage Service Console User Guide.

    Remember, the replicas are exact copies of the objects in the source bucket.

Cross-Region Replication

What Is and Is Not Replicated

How to Find Replication Status of an Object

Walkthrough 1: Configure Cross-Region Replication Where Source and Destination Buckets Are Owned by the Same AWS Account