Object Storage Service:Cross-account and cross-region replication

Configuring cross-account replication requires actions on both the source and destination accounts and involves three main steps:

1. Source account: Create a RAM role specifically for data replication and grant it the minimum permissions required to read objects from the source bucket.

2. Destination account: Modify the bucket policy of the destination bucket to allow the RAM role created by the source account to write objects to it.

3. Return to the source account: Create a cross-region replication rule to associate the source and destination buckets, which starts the replication task.

Step 1: Source account: Create and authorize a RAM role

1. Create a RAM role: Go to the Create RAM role page. For Trusted Entity Type, select Cloud Service, and for Trusted Entity Name, select Object Storage.

2. Grant the RAM role permissions to access the source bucket: Create a custom permission policy that contains only the permissions required to read objects from the source bucket and start the replication task:

   1. On the Create Permission Policy page, click the Script Editor tab. Paste the following policy content into the policy editor, and replace src-bucket with the actual source Bucket name.

      {
         "Version": "1",
         "Statement": [
            {
               "Effect": "Allow",
               "Action": [
                  "oss:ReplicateList",
                  "oss:ReplicateGet"
               ],
               "Resource": [
                  "acs:oss:*:*:src-bucket",
                  "acs:oss:*:*:src-bucket/*"
               ]
            }
         ]
      }

   2. After creating the policy, go to the Roles page, find the role you just created, and click Add Permissions. In the Add Permissions panel, the principal is automatically populated. For Permission Policy, select the custom policy you created in the previous step, and then click Confirm Add Permission.

3. (Optional) Grant the RAM role permissions to access KMS: If data replicated to the destination bucket will be KMS-encrypted, you must grant the RAM role permissions to access KMS.

   On the Roles page, find the role that you just created in the list and click Add Permission. In the Add Permission panel, the principal is automatically populated. For Permission Policy, select AliyunKMSCryptoUserAccess and then click Confirm Add Permission.

4. Record the role ARN: On the Roles page, find the RAM role that you created, go to the Basic Information page, and copy the role's ARN for later use. The format is acs:ram::{Source account UID}:role/{Role name}.

Step 2: Destination account: Authorize RAM role and prepare resources

1. Authorize the RAM role to write to the destination bucket: In the destination account, modify the bucket policy of the destination bucket to allow the RAM role from the source account to write objects to it.

   1. In the destination account, navigate to the Bucket List page and click the destination bucket.

   2. In the left-side navigation pane, choose Permissions > bucket policy.

   3. Click the Visual Editor tab, and then click Receive Replicated Objects.

   4. In the panel that appears, configure the following settings:

      • Method to obtain UID and RAM role ARN: Select From Source RAM Role ARN.

      • Source RAM role ARN: Enter the RAM role ARN from the source account that you recorded in Step 1.

      • Authorization purpose: Select Cross-Account Replication.

   5. Click Generate Policy, and then click Save.

2. (Optional) Prepare a KMS key in the destination account: To replicate KMS-encrypted objects, you must prepare a KMS key in the destination account.

   1. Log on to the Instance Management page of the KMS console, and purchase and enable a KMS instance in the same region as the bucket of the source account. When you purchase the KMS instance, make sure that the Number of Access Controls is greater than or equal to 2 and leave the other parameters at their default settings.

      Note

      Replicating KMS-encrypted objects across accounts is only supported in regions where KMS is available. For more information about supported regions, see Supported regions and endpoints for software key management.

   2. In your KMS instance, create a software key. The key type must be a non-default key (a software key is recommended). After the key is created, take note of the key ARN from the Basic Information section for use when you create replication rules later.

   3. Set a key policy for the key that you created. Add the ARN of the RAM role created by the source account as an Other Account User, and specify the ARN of the role that you created in the preceding steps. For more information, see Set a key policy.

      This action grants the RAM role the necessary permissions, such as decrypt (kms:Decrypt) and generate data key (kms:GenerateDataKey), to use this key for encrypting objects in the destination bucket. The console wizard includes these permissions by default, but if you configure a custom key policy programmatically, you must ensure these permissions are included.

Step 3: Source account: Create the replication rule

After completing the authorization steps, return to the source account console to create the replication rule and start the task.

1. In the source account, navigate to the Bucket List page and click the source bucket.

2. In the left-side navigation pane, choose Data Management > Cross-region replication.

3. Click Cross-region replication and configure the following parameters in the dialog box:

   1. Configure destination bucket: Select Specify a bucket in another account, choose the region of the destination bucket, and enter its name.

      • Objects to Replicate: Select Synchronize all files or Replicate objects with specified prefixes. Objects in the source bucket with the specified prefixes are replicated to the destination bucket. By default, you can add a maximum of 10 prefixes. To increase the number of prefixes, contact to request an adjustment. The limit can be increased to a maximum of 100.

      • Object Tag:

        Note

        To configure this parameter, the following conditions must be met:

        • Object tags have been set.

        • Replicate delete markers and Replicate deletion operations are not selected.

        After you select the Set Rules checkbox, you can copy objects with specified tags to the destination Bucket. You can add up to 10 tags (key-value pairs). After you add the tags, you can select one of the following tag filtering policies:

        • Match all tags: If all tags of an object are included in the tag set specified in the filter rule, the object is replicated.

        • Match any tag: The object is replicated if it has a tag that matches one of the tags in the filter rule.

          Note

          Currently, tag-based filtering is not supported in the China (Zhangjiakou), China (Zhongwei), and Mexico regions.

      • Replicate KMS-encrypted objects: If source objects are encrypted with KMS, select Replicate to keep them encrypted in the destination bucket. Provide the destination KMS key ARN that you prepared in Step 2. If you select Do Not Replicate, KMS-encrypted objects will not be replicated to the destination bucket.

        Note

        You can check the encryption status of the source object and destination bucket by using the HeadObject and GetBucketEncryption operations, respectively.

      • Authorization role: From the drop-down list, select the RAM role you created in the source account in Step 1.

   2. Configure replication policy:

      • Replicate existing objects: Choose whether to replicate existing objects in the source bucket that were created before the rule was enabled. This action overwrites objects with the same name in the destination bucket. To prevent data loss, we recommend enabling versioning for both the source and destination buckets.

      • Replicate delete markers: Choose whether deleting an object in the source bucket also deletes the corresponding object in the destination bucket. In disaster recovery scenarios, select No to prevent accidental deletions in the source bucket from being synchronized to the backup bucket, which enhances data security.

        • No: Replicates new and modified objects. Deleting an object in the source bucket does not affect the destination bucket. This prevents data loss in the destination bucket caused by manual deletion or automated lifecycle rule deletions in the source bucket.

          Note

          If versioning is enabled for the source bucket, deleting an object without specifying a version ID creates a delete marker in the source bucket. This delete marker is replicated to the destination bucket.

        • Yes: Replicates create, modify, and delete operations to keep the destination bucket consistent with the source bucket. This ensures data consistency and is suitable for environments where multiple users or applications need to share and access the same dataset. However, with this policy, when an object is deleted from the source bucket (either manually or by a lifecycle rule), the corresponding object in the destination bucket is also deleted and cannot be recovered.

   3. (Optional) Configure replication acceleration:

      • Transfer acceleration: Enable this feature to improve data transfer speeds for replication tasks between the Chinese mainland and other regions. This feature incurs additional transfer acceleration fees.

      • Replication time control (RTC): When enabled, this feature ensures that most new or modified objects are replicated within 10 minutes. This feature is only supported between certain regions and incurs additional cross-region replication RTC fees. For more information, see RTC Feature Overview.

4. After confirming that all settings are correct, click OK and then Confirm to Enable.

   The replication task starts within a few minutes after the rule is created. Object replication is an asynchronous process, and the time required can range from a few minutes to several hours, depending on the object size, quantity, and cross-region network latency. You can monitor the replication progress, including the replication status of existing and new objects, on the Cross-region replication tab of the source bucket.

FAQ

Which object changes are not replicated?

Replication is triggered only by changes to object content (such as create, delete, or modify operations). Changes to the storage class made via a lifecycle rule or a CopyObject operation, and updates to the last access time (LastAccessTime), do not involve writing new object content. Therefore, these actions do not trigger a new replication task, and the object replica in the destination bucket is not updated.

Solution:

• Synchronize storage class: We recommend configuring an identical lifecycle rule on the destination bucket to match the storage class transitions of the source bucket.

• Update LastAccessTime: To update the last access time of an object in the destination bucket, access the object directly in that bucket (for example, by making a GetObject request). This will trigger a refresh of its LastAccessTime.

Is multipart upload replicated?

When an object is uploaded using multipart upload, each part is replicated to the destination bucket. After the parts are combined in the source bucket (CompleteMultipartUpload), the resulting complete object is also replicated to the destination bucket.

Is there a simpler way to grant permissions?

Yes. For a quick setup, you can attach the AliyunOSSFullAccess system policy provided by Alibaba Cloud directly to the RAM role. However, this policy grants full access to all OSS resources in your account, which is overly permissive. We do not recommend using it in a production environment.

Can I use a JSON policy for authorization?

Yes. On the bucket policy page for the destination bucket, you can select the JSON Editor for more flexible configuration. Keep the following points in mind when using a JSON policy:

• The new policy will overwrite any existing bucket policy, so ensure the new policy includes all necessary authorization rules.

• The Principal field in the policy must contain the ARN of the RAM role from the source account.

• If the role name contains uppercase letters, you must convert them to lowercase in the policy. For example, the role AliyunOssDrsRole should be written as aliyunossdrsrole in the policy.

• You must accurately specify the source account's UID, the destination bucket's name, and the destination account's UID.

The following is an example policy:

{
    "Version":"1",
    "Statement":[
        {
            "Effect":"Allow",
            "Action":[
                "oss:ReplicateList",
                "oss:ReplicateGet",
                "oss:ReplicatePut",
                "oss:ReplicateDelete"
            ],
            "Principal": [
                "arn:sts::{source-account-id}:assumed-role/{role-name}/*"
            ],
            "Resource":[
                "acs:oss:*:{destination-account-id}:{destination-bucket-name}",
                "acs:oss:*:{destination-account-id}:{destination-bucket-name}/*"
            ]
        }
    ]
}