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

Configuring Cross-Region Replication for a Bucket

Functions

Cross-region replication refers to the automatic and asynchronous replication of objects across buckets in different regions. 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.

An IAM agency is required for configuring cross-region replication. For details, see Creating an Agency for Cross-Region Replication.

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

  1. The versioning statuses of the source and destination buckets are the same. For details, see Configuring Versioning for a Bucket.
  2. The source bucket's owner and agency (OBS) have the write permission for the destination bucket (with a bucket policy configured), and the agency (OBS) also has the read permission for the source bucket. This permission delegation needs to be implemented by using a bucket policy.

For details about how to configure the bucket policy, see Configuring a Bucket Policy. After the bucket policy is set, the agency (OBS) can read objects from the source bucket and copy objects to the destination bucket.

Authorization Information

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 need to grant 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 need to grant 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 need to grant the obs:bucket:PutReplicationConfiguration permission. For details, see Creating a Custom Bucket Policy.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
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>
    </Rule> 
</ReplicationConfiguration>

Request Parameters

This request contains no message parameters.

Request Headers

The request uses one header, as described in the following table.

Table 1 Request header for cross-region replication

Parameter

Mandatory (Yes/No)

Type

Description

Content-SHA256

Yes

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 Elements

The request body contains elements to specify the replication configuration for the bucket in XML format. The following table lists request elements:

Table 2 Bucket replication configuration elements

Parameter

Mandatory (Yes/No)

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 4.

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 is a string of 0 to 64 characters.

Default value:

N/A

Table 3 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 4 Rule parameter description

Parameter

Mandatory (Yes/No)

Type

Description

ID

No

String

Definition:

ID of the cross-region replication rule.

Constraints:

The rule ID must be unique.

Range:

The value is a string of 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 the Prefix is left blank, the cross-region replication rule is applied to the whole 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 1024 characters.

Default value:

N/A

Destination

Yes

Container

Definition:

Container for the destination bucket information.

Constraints:

N/A

Range:

For details, see Table 5.

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.
Table 5 Destination parameters

Parameter

Mandatory (Yes/No)

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 the replication configuration contains multiple rules, the rules must specify the same bucket as the destination bucket.

Range:

The value can contain 3 to 63 characters.

Default value:

N/A

StorageClass

No

String

Definition:

The storage class to which objects replicated to the destination bucket will be changed.

Constraints:

N/A

Range:

  • STANDARD: Standard storage
  • WARM: Infrequent Access storage
  • COLD: Archive storage
  • DEEP_ARCHIVE: Deep Archive storage (limited OBT)

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

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned for this request.

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
 
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>
     </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
Parent Topic: Advanced Bucket Settings