Help Center/ Object Storage Service/ API Reference/ Bucket APIs/ Cross-Region Replication/ Configuring Cross-Region Replication for a Bucket
Updated on 2026-07-27 GMT+08:00
View PDF
Share

Configuring Cross-Region Replication for a Bucket

Function

Cross-region replication refers to the automatic and asynchronous replication of objects across buckets in different regions under the same account. By activating cross-region replication, OBS can copy new objects and modified objects from a source bucket in one region to a destination bucket in a different region. A bucket owner or users who have the required permission can call this API to configure cross-region replication for a bucket. For more information about cross-region replication, see Cross-Region Replication Within an Account Using OBS.

An IAM agency is required for configuring cross-region replication. The agency should be a cloud service agency of OBS and have the Tenant Administrator permissions. For details, see Cross-Region Replication Within an Account Using OBS.

To configure cross-region replication for a bucket, the following requirement must be met:

The versioning statuses of the source and destination buckets are the same. For how to configure bucket versioning, see Configuring Versioning for a Bucket.

Constraints

Table 1 Constraints on cross-region replication within an account

Item

Description

Bucket version

Only buckets whose version is 3.0 or later support cross-region replication.

You can view the version of a bucket in the Basic Information area of the bucket's Overview page on OBS Console. For details, see Viewing Bucket Information.

Functions
  • Objects in the Archive, or Deep Archive storage class cannot be replicated.
  • If the destination region does not support a specific storage class, object copies will be stored in the Standard storage class.
  • OBS currently only supports the replication between one source bucket and one destination bucket. It does not support replication from one source bucket to multiple destination buckets. The destination bucket can be modified. However, modifying the destination bucket will change the destination bucket of all existing rules.
  • Cross-region replication does not replicate appendable objects.
  • A source bucket can only have one cross-region replication rule that is applied to all objects in the bucket, or it can have up to 100 rules that are applied to objects with the specified prefix.
  • Objects encrypted with SSE-C cannot be replicated across regions.

Time

After a cross-region replication rule is configured, it may take some time to become effective. As a result, objects may not be replicated immediately.

Region
  • The source and destination buckets must be in two different regions.
  • Before replicating data, ensure that the source and destination regions can have their data replicated from each other. Figure 1 lists the supported regions. "√" indicates that data can be replicated between regions. "x" indicates that data cannot be replicated between regions.

Synchronization of existing objects
  • By default, objects uploaded before cross-region replication is enabled are not replicated to the destination bucket unless the function for synchronizing existing objects is enabled.
  • Modifying cross-region replication settings may prevent some existing objects from being replicated, so do not make modifications before the synchronization of existing objects is complete.
  • If a copied object in the destination bucket is deleted and a new replication rule that allows replication of existing objects is configured within three days of the deletion, the same version of the deleted object will not be replicated to the destination bucket again.

    For example, you first configure cross-region replication rule 1 to replicate the current version of object test.txt from the source bucket to the destination bucket. Later, you delete test.txt from the destination bucket and delete rule 1. Two days afterward, you create cross-region replication rule 2 that allows replication of existing objects. In this case, test.txt will not be replicated to the destination bucket again.

Versioning
  • The source and destination buckets must have the same versioning status (enabled or disabled). If you change the versioning status after cross-region replication has been configured, any updates made when the source and destination buckets have inconsistent versioning statuses cannot be replicated. After versioning is enabled, it can only be suspended and cannot be disabled. Therefore, exercise caution when changing the versioning status while using replication rules.
  • If versioning is enabled or suspended for both the source and destination buckets and cross-region replication is also enabled for both buckets, deleting an object without specifying its version in the source bucket will also delete the object in the destination bucket.
  • When cross-region replication is enabled, if you change the versioning status of the destination bucket, object replication will fail. To change the versioning status of the source bucket in such conditions, delete the replication configuration first and then make the change.

Access control
  • Bucket owners must have the read and write permissions for both source and destination buckets for successful replication. If OBS does not have permission to read source objects or write destination objects, objects cannot be replicated successfully. Even if OBS is granted required permissions later, the replication will not be resumed.
  • Do not delete or overwrite object copies in a destination bucket or modify their ACLs. Doing so may result in inconsistent latest object versions and access control settings between the destination and source buckets.

Tags

Others
  • Objects in a source bucket can be replicated to only one destination bucket and cannot be replicated further from that destination bucket to another bucket. For example, bucket A and bucket B are in two different regions. You can replicate data from bucket A to bucket B or the other way round. However, data copies in either bucket A or bucket B cannot be replicated anymore.
  • If BlockPublicAcls is enabled for the destination bucket but the ACLs of objects in the source bucket allow public access, cross-region replication will fail because of ACL conflicts.
Figure 1 Replication between regions

Authorization

To call this API, you must be the bucket owner or have the permission to configure cross-region replication for a bucket. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:bucket:PutReplicationConfiguration permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:bucket:putReplicationConfiguration permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:bucket:putReplicationConfiguration

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you must have the obs:bucket:PutReplicationConfiguration permission. For details, see Creating a Custom Bucket Policy.

URI

PUT /

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
PUT /?replication HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
x-obs-date: date 
Content-SHA256: SHA256
Content-MD5: MD5
Authorization: authorization string 
Content-Length: contentlength 

<ReplicationConfiguration> 
    <Agency>testAcy</Agency>
    <Rule> 
        <ID>rule1</ID> 
        <Prefix></Prefix> 
        <Status>rule-status</Status> 
        <Destination> 
            <Bucket>targetbucketname</Bucket> 
            <StorageClass>STANDARD</StorageClass>
            <DeleteData>Enabled</DeleteData>
        </Destination> 
        <HistoricalObjectReplication>Enabled</HistoricalObjectReplication>
        <DeleteMarker>Enabled</DeleteMarker>                     
    </Rule> 
</ReplicationConfiguration>

URI Parameters

Table 2 URI parameters

Parameter

Type

Mandatory

Description

replication

String

No

Definition

An identifier that marks this API as related to cross-region replication.

Constraints

N/A

Range

replication

Default Value

N/A

Request Headers

This request uses the headers described in the following table.

Table 3 Request header for cross-region replication

Parameter

Mandatory

Type

Description

Content-SHA256

No

String

Definition

SHA-256 digest string of the message body, that is, the string obtained after the 256-bit SHA-256 value of the message body is encoded using Base64

Constraints

You can also configure the Content-SHA256 header whose value is the Base64-encoded result of the 256-bit SHA256 of the message. Configure either Content-MD5 or Content-SHA256.

Range

N/A

Default Value

N/A

Content-MD5

Yes

String

Definition

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864. For details about how to calculate Content-MD5, see Examples for Calculating Content-MD5 in Java.

Constraints

You can also configure the Content-SHA256 header whose value is the Base64-encoded result of the 256-bit SHA256 of the message. Configure either Content-MD5 or Content-SHA256.

Range

N/A

Default Value

N/A

Request Body

This request contains the elements used to define the replication configuration for the bucket in XML format. The following table lists request elements:

Table 4 Bucket replication configuration elements

Parameter

Mandatory

Type

Description

ReplicationConfiguration

Yes

Container

Definition

Container of cross-region replication rules. ReplicationConfiguration is the parent node of Rule and Agency.

Constraints

  • A bucket can have 1 to 100 cross-region replication rules.
  • The size of the request body for configuring a cross-region replication rule at a time cannot exceed 50 KB.

Range

N/A

Default Value

N/A

Rule

Yes

Container

Definition

Container of a specified cross-region replication rule.

Constraints

A bucket can have 1 to 100 cross-region replication rules.

Range

For details, see Table 6.

Default Value

N/A

Agency

Yes

String

Definition

Name of the agency created by the user for cross-region replication.

Constraints

  • The agency must be a cloud service agency of OBS and must have the Tenant Administrator permission.
  • If Replicate KMS encrypted objects is selected, the agency must have the permission. The authorization scope of the agency must be set to Region-specific projects, and the source and destination regions must be selected.

Range

The value must contain 0 to 64 characters.

Default Value

N/A

Table 5 OBS permissions required by the agency

Action

Description

obs:object:GetObject

Obtains object content and metadata.

obs:object:DeleteObjectVersion

Deletes one or more object versions.

obs:object:PutObjectVersionAcl

Configures the object version ACL.

obs:object:AbortMultipartUpload

Aborts a multipart upload.

obs:object:PutObjectAcl

Configures the object ACL.

obs:object:DeleteObject

Deletes one or more objects.

obs:bucket:HeadBucket

Obtains bucket metadata.

obs:object:PutObject

Uploads objects with PUT or POST, copies objects, appends data to objects, initiates a multipart upload, as well as uploads and assembles parts.

obs:object:GetObjectVersionAcl

Obtains the object version ACL.

obs:bucket:GetBucketVersioning

Obtains the versioning status of a bucket.

obs:bucket:ListBucketMultipartUploads

Lists multipart uploads.

obs:object:ListMultipartUploadParts

Lists uploaded parts.

obs:object:ModifyObjectMetaData

Modifies object metadata.

obs:bucket:ListBucketVersions

Lists object versions in a bucket.

obs:bucket:ListBucket

Lists objects in a bucket.

obs:object:GetObjectVersion

Obtains the content and metadata of an object version.

obs:object:GetObjectAcl

Obtains the object ACL.

obs:bucket:GetReplicationConfiguration

Obtains the cross-region replication configuration of a bucket.
Table 6 Rule parameter description

Parameter

Mandatory

Type

Description

ID

No

String

Definition

ID of the cross-region replication rule.

Constraints

The rule ID must be unique.

Range

The value must contain 0 to 255 characters.

Default Value

N/A

Status

Yes

String

Definition

Whether to enable the cross-region replication rule.

Constraints

N/A

Range

  • Enabled: The rule is enabled.
  • Disabled: The rule is disabled.

Default Value

N/A

Prefix

Yes

String

Definition

Prefix of an object name, applicable to one or more objects.

Constraints

  • If Prefix is left blank, the cross-region replication rule applies to the entire bucket.
  • The prefix characters between rules cannot overlap. For example, two rules are configured, the prefix of rule 1 is object, and the prefix of rule 2 is obj. Both prefixes contain obj.

Range

The value is a UTF-8 string of 1 to 1,024 characters.

Default Value

N/A

Destination

Yes

Container

Definition

Container for the destination bucket information.

Constraints

N/A

Range

For details, see Table 7.

Default Value

N/A

HistoricalObjectReplication

No

String

Definition

Whether to replicate historical objects that meet the cross-region replication rule.

Constraints

N/A

Range

  • Enabled: Historical objects that meet the cross-region replication rule are replicated.
  • Disabled: Historical objects that meet the cross-region replication rule are not replicated.

Default Value

If this parameter is not set, Disabled is used by default.

DeleteMarker

No

String

Definition

Whether to replicate the delete markers of the objects that meet the cross-region replication rule.

Constraints

N/A

Range

  • Enabled: The delete markers of the objects that meet the cross-region replication rule will be replicated.
  • Disabled: The delete markers of the objects that meet the cross-region replication rule will not be replicated.

Default Value

Enabled
Table 7 Destination parameters

Parameter

Mandatory

Type

Description

Bucket

Yes

String

Definition

Name of the destination bucket for cross-region replication. The bucket is used to store object copies identified by the cross-region replication rule.

Constraints

If there are multiple rules in the cross-region replication configuration, ensure that each rule has a corresponding destination bucket name.

Range

The value can contain 3 to 63 characters.

Default Value

N/A

StorageClass

No

String

Definition

Target storage class that objects replicated to the destination bucket will be transitioned to.

Constraints

N/A

Range

  • STANDARD: Standard storage
  • WARM: Infrequent Access storage
  • COLD: Archive storage
  • DEEP_ARCHIVE: Deep Archive storage

Default Value

N/A

DeleteData

No

String

Definition

Whether to synchronously delete objects with the same names in the destination bucket through cross-region replication after the objects in the source bucket are deleted.

Constraints

N/A

Range

  • Enabled: The object deletions in the source bucket will be synchronized to the destination bucket.
  • Disabled: The object deletions in the source bucket will not be synchronized to the destination bucket.

Default Value

If this parameter is not set, Disabled is used by default.

Response Syntax

1
2
3
4
 
HTTP/1.1 status_code 
Server: OBS 
Date: date 
Content-Length: contentlength

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

This response does not contain a response body.

Error Responses

No special errors. You can find all errors in Error Code Overview.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
PUT /?replication HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: Wed, 27 Jun 2018 13:39:15 +0000
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:CdeqU0Vg9xNdJMZ0PGPgh5EnkO0=
Content-SHA256: ogX9qClMrVJUBiUSIKDFM0qO41jJM0I5SCN55/OtMyI=
Content-MD5: l/Z8mfSX+VyV8k5EhIQz5Q==
Content-Length: 330

<ReplicationConfiguration>
    <Agency>testAcy</Agency>
    <Rule>
        <ID>Rule-1</ID>
        <Status>Enabled</Status>
        <Prefix></Prefix>
        <Destination>
            <Bucket>dstbucket</Bucket>
            <StorageClass>STANDARD</StorageClass>
            <DeleteData>Enabled</DeleteData>
        </Destination>      
        <HistoricalObjectReplication>Enabled</HistoricalObjectReplication>
        <DeleteMarker>Enabled</DeleteMarker>
    </Rule>
</ReplicationConfiguration>

Sample Response

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: B59500000164417839932E5A2295674C
x-obs-id-2: 32AAAQAAEAABKAAQAAEAABAAAQAAEAABCStv51t2NMMx+Ou+ow7IWV4Sxo231fKe
Date: Wed, 27 Jun 2018 13:39:15 GMT
Content-Length: 0

Helpful Links

Parent Topic: Cross-Region Replication