Cross-account cross-region replication

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

1. Source account: Create a RAM role for data replication and grant it the least privilege required to read data from the source bucket.

2. Destination account: Modify the destination bucket's Bucket Policy to grant the source account's RAM role write permissions.

3. Source account: Return to the source account to create a cross-region replication (CRR) rule that links the source and destination buckets and starts the replication task.

Step 1: Create and authorize a RAM role

1. Create a RAM role. Go to the Create Role page. Set Principal Type to Cloud Service and Principal Name to OSS.

2. Grant the RAM role permissions to access the source bucket: Create a custom policy that includes only the permissions required to read data from the source bucket for replication.

   1. On the Create Policy page, click the JSON Editor tab. Paste the following policy into the policy editor and replace src-bucket with the name of your source bucket.

      {
         "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 Grant Permission. In the panel that appears, the principal is automatically populated. For the policy, select the custom policy you created in the previous step, and then click Confirm Grant.

3. (Optional) Grant the RAM role permissions to access Key Management Service (KMS). If you use KMS to encrypt replicated data in the destination bucket, grant the RAM role access to KMS.

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

4. Record the role ARN. On the Roles page, find the RAM role you created, navigate to its Basic Information page, and copy the role ARN. The ARN is in the format acs:ram::{source-account-uid}:role/{role-name}.

Step 2: Authorize the RAM role and prepare resources

1. Authorize the RAM role to write data to the destination bucket: In the destination account, modify the destination bucket's Bucket Policy to grant write access to the RAM role from the source account.

   1. Log on to the destination account and go to the Buckets page. Click the destination bucket.

   2. In the left-side navigation pane, choose Access Control > Bucket Policy.

   3. Click the Add in GUI tab, and then click Receive Objects to Replicate.

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

      • Obtain UID and RAM Role From: Select Source RAM role ARN for replication.

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

      • 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 first create a KMS key in the destination account.

   1. Log on to the KMS console and go to the Instance Management page. In the same region as the source bucket, purchase and enable a KMS instance. When you purchase the KMS instance, make sure that Access Management Quantity is greater than or equal to 2. Retain the default settings for other parameters.

      Note

      Cross-account replication of KMS-encrypted objects depends on KMS. The regions that support this feature are limited by KMS availability. For more information about the regions that support KMS, see Supported regions and endpoints for software key management.

   2. Under the 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, record the key ARN from the Basic Information section to use when creating the replication rule.

   3. Set a key policy for the key that you created. When you configure the policy, for the Cross-account User, specify the RAM role ARN created by the source account, which is the role ARN from the preceding steps. For more information, see Set a key policy.

      By default, this operation grants the role the necessary permissions, such as decryption (kms:Decrypt) and data key generation (kms:GenerateDataKey), allowing it to use this key to create encrypted objects in the destination bucket. Although the console wizard typically includes the required permissions, if you set a custom key policy by using an API, you must manually ensure that these permissions are correctly added.

Step 3: Create a cross-region replication rule

After you grant the required permissions, return to the console of the source account to create a replication rule and start the task.

1. Log on to the source account and go to the Buckets page. Click the source bucket.

2. In the left-side navigation pane, choose Data Management > Cross-Region Replication.

3. Click Cross-Region Replication. In the dialog box that appears, configure the following parameters:

   1. Configure Destination Bucket: Select Specify a bucket that belongs to another Alibaba Cloud account, select the region where the destination bucket is located, and enter its name.

      • Objects to Replicate: Select Synchronize all files or Objects with Specified Prefix. Objects in the source bucket that have a specified prefix are replicated to the destination bucket. By default, you can add up to 10 prefixes. To increase this limit to 100, contact Technical Support.

      • Object Tagging:

        Note

        To configure this parameter, you must meet the following conditions:

        • You have configured object tags.

        • The Replicate delete markers and Replicate permanent deletions of specific versions checkboxes are not selected.

        Select the Configure Rules checkbox to replicate objects with specific 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 filter policies:

        • Include all tags: OSS replicates an object only if all of its tags match the tags specified in the filter rule.

        • Include any one tag: OSS replicates an object if at least one of its tags matches a tag specified in the filter rule.

          Note

          Currently, tag-based filtering is not supported in the China (Shenzhen) Finance and China (Shanghai) Finance cloud regions.

      • Replicate KMS Encrypted Objects: If the source objects are encrypted with KMS and you want them to remain encrypted in the destination, select Replicate and provide the ARN of the KMS key in the destination account that you prepared in Step 2. If you select Do not replicate, KMS-encrypted objects are not replicated to the destination bucket.

        Note

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

      • RAM Role: From the drop-down list, select the RAM role that was created in the source account in Step 1.

   2. Configure Replication Policy:

      • Replicate Delete Operations (This option appears when versioning is disabled for the source bucket): Select whether to synchronize deletions of objects in the source bucket to the destination bucket.

        • Yes: Synchronizes create, modify, and delete operations to keep the destination bucket consistent with the source bucket. This option is suitable for multi-user or application environments that need to share and access the same dataset. However, with this policy, when an object in the source bucket is deleted manually or automatically by a lifecycle rule, the corresponding object in the destination bucket is also deleted and cannot be recovered.

        • No: Synchronizes new and modified objects. Deletions of objects in the source bucket do not affect the destination bucket. In disaster recovery scenarios, select No to prevent accidental deletions in the source bucket from being replicated to the backup bucket, which enhances data security.

      • Replicate Historical Data: Select whether to replicate data that existed in the source bucket before the rule takes effect. This operation overwrites objects that have the same name in the destination bucket. To prevent data loss, we recommend that you enable versioning for both the source and destination buckets.

      • Replicate delete markers (This option appears when versioning is enabled for the source bucket): Select whether to replicate delete markers from the source bucket to the destination bucket.

        • Replicate: When an object is deleted from the source bucket without a version ID specified, OSS synchronizes the delete marker from the source bucket to the destination bucket. This is suitable for scenarios that require sharing and accessing the same dataset to ensure data consistency between the source and destination buckets.

          Important

          If you configure this policy, when an object in the source bucket is deleted manually or automatically by a lifecycle rule, a delete marker is also synchronized to the destination bucket, making the data inaccessible in the destination bucket.

        • Do not replicate (recommended for disaster recovery scenarios): Delete markers created in the source bucket are not replicated to the destination bucket. This effectively prevents data loss in the destination bucket due to accidental deletions or automatic deletions by lifecycle rules in the source bucket.

      • Replicate permanent deletions of specific versions (This option appears when versioning is enabled for the source bucket): Select whether to replicate permanent deletions of specific object versions from the source bucket to the destination bucket.

        • Replicate: When you permanently delete a specific version of a source object, including the current and non-current versions, OSS also permanently deletes the corresponding version in the destination bucket. This is suitable for scenarios where you need to ensure complete data consistency between the source and destination buckets.

          Important

          If you configure this policy, object versions permanently deleted from the source bucket cannot be recovered in the destination bucket. Use this option with caution.

        • Do not replicate (recommended for disaster recovery scenarios): Permanently deleting a specific version of a source object does not synchronize the deletion of the corresponding version in the destination bucket. This prevents permanent delete operations in the source bucket from affecting data security in the destination bucket.

   3. (Optional) Configure Replication Acceleration:

      • Transfer Acceleration: If a replication task involves regions both within and outside the Chinese mainland, you can enable this feature to improve data transfer speeds. This feature incurs additional Transfer Acceleration fees.

      • Replication Time Control (RTC): When enabled, RTC keeps the replication latency for most incremental data within 10 minutes. This feature is supported only between specific regions and incurs additional cross-region replication RTC fees. For more information, see RTC overview.

4. After you confirm that all configurations are correct, click OK and then Confirm Enable.

   The replication task starts within a few minutes after the rule is created. Data replication is an asynchronous process. The time required depends on the object size, number of objects, and cross-region network latency, and can range from a few minutes to several hours. You can view the replication progress, including the synchronization status of historical and incremental data, on the Cross-Region Replication tab of the source bucket.

FAQ

Why are storage class or access time changes not replicated?

Data replication is triggered only by changes to object content, such as creating, deleting, or modifying an object. Changes to the storage class made through 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 OSS does not update the object replica in the destination bucket.

Solutions:

• Synchronize storage class: Configure an identical lifecycle rule on the destination bucket to ensure the same storage class transitions.

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

Are objects uploaded by using multipart upload replicated?

When you upload an object using multipart upload, OSS replicates each part to the destination bucket. After a CompleteMultipartUpload operation merges the parts in the source bucket, OSS then replicates the complete object as a single entity to the destination bucket.

Simplified RAM role authorization

Yes. For quick authorization, you can directly grant the AliyunOSSFullAccess system policy provided by Alibaba Cloud to the RAM role you created. However, this policy grants all permissions for all OSS resources under your account. Due to its broad scope, this policy is not recommended for production environments.

Using a JSON policy for permissions

Yes. On the Bucket Policy page of the destination bucket, you can select Add Rule by Syntax for a more flexible configuration. Keep the following points in mind when using a JSON policy:

• A new policy overwrites any existing Bucket Policy. Ensure the new policy includes all required 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 must be written as aliyunossdrsrole in the policy.

• You must accurately enter the UID of the source account, the name of the destination bucket, and the UID of the destination account.

The following code provides a policy example:

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