Help Center/ Object Storage Service/ API Reference (Ankara Region)/ APIs/ Advanced Bucket Settings/ Configuring Cross-Cluster Replication for a Bucket
Updated on 2024-04-15 GMT+08:00

Configuring Cross-Cluster Replication for a Bucket

Functions

Cross-cluster replication refers to the automatic and asynchronous replication of objects across buckets in different clusters. By activating the cross-cluster replication function, OBS can copy new objects and modified objects from a source bucket to a destination bucket in another cluster in the same region.

If cross-cluster or cross-region replication has been configured for a bucket, configuring another replication policy will overwrite the existing one.

The following two requirements must be met for configuring the cross-cluster replication for a bucket:

  1. Cross-cluster replication can be configured only when the versioning statuses of the source and destination buckets are the same. For details about how to configure bucket versioning, see Configuring Versioning for a Bucket.
  2. The owner and agency (OBS) of the source bucket must have the permission to write the destination bucket (configured with BucketPolicy), and the agency (OBS) must have the read permission for the source bucket. This permission delegation needs to be implemented by calling the BucketPolicy API.

    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.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
PUT /?replication HTTP/1.1 
Host: bucketname.obs.region.example.com
x-obs-date: date 
Content-MD5: l/Z8mfSX+VyV8k5EhIQz5Q==
Authorization: authorization string 
Content-Length: contentlength 
<ReplicationConfiguration> 
   <Agency>testAcy</Agency>
     <Rule> 
        <ID>rule1</ID> 
        <Prefix>key-prefix</Prefix> 
        <Status>rule-status</Status> 
        <Destination> 
           <Bucket>targetbucketname</Bucket> 
        </Destination> 
     </Rule> 
</ReplicationConfiguration>

Request Parameters

This request contains no message parameters.

Request Headers

This request uses the headers described in the following table.

Table 1 Request headers for cross-cluster replication

Header

Description

Mandatory

Content-MD5

Base64-encoded 128-bit MD5 digest of the message according to RFC 1864.

Yes

Request Elements

This request 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

Element

Description

Mandatory

ReplicationConfiguration

Container for the replication rules. A maximum of 100 rules can be configured. The size of the XML file can reach 50 KB.

Type: container

Child: Rule

Parent: none

Yes

Agency

Name of the agency, which can have a maximum of 64 characters.

Type: string

Parent: ReplicationConfiguration

Yes

Rule

Container of a specified replication rule.

There must be at least one rule for the replication configuration. A maximum of 100 rules can be configured.

Type: container

Parent: ReplicationConfiguration

Yes

ID

Unique identifier of a rule, with a maximum length of 255 characters.

Type: string

Parent: Rule

No

Status

If the value of this element is Disabled, this rule will be ignored.

Type: string

Parent: Rule

Value options: Enabled, Disabled

Yes

Prefix

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

The maximum length of a prefix is 1,024 bytes. Duplicated prefixes are not supported.

Type: string

Parent: Rule

Yes

Destination

Container for the destination bucket information.

Type: container

Parent: Rule

Yes

Bucket

Bucket used to store object copies that are marked by rules.

If the replication configuration contains multiple rules, the rules must specify the same bucket as the destination bucket.

Type: string

Parent: Destination

Yes

DeleteData

Keyword for synchronizing object deletion operations. If the value is Enabled, the object deletion for the source bucket will be replicated to the destination bucket.

Type: string

Parent: Destination

Value options: Enabled, Disabled

No

HistoricalObjectReplication

Keyword for copying a historical object. If the value is Enabled, historical objects meeting this rule are copied.

Type: string

Parent: Rule

Value options: Enabled, Disabled

No

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
PUT /?replication HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Wed, 27 Jun 2018 13:39:15 +0000
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:CdeqU0Vg9xNdJMZ0PGPgh5EnkO0=
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>
          <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